In short
In a Script in ServerScriptService, when the Tool is activated, call workspace:GetPartBoundsInBox(cframe, size, params) with a box placed a few studs in front of the attacker's HumanoidRootPart. Exclude the attacker with OverlapParams.ExcludeInstances, find the Humanoid of each part it returns, and keep a table of characters already hit so each one takes damage only once per swing.
- Run the query on the server, so a cheater cannot claim hits that did not happen.
- A spatial query sees players who are standing still inside the box.
Touchedoften misses them, which is why hitboxes do not use it. - Keep the box on for a short window (about 0.2 seconds) and check it every frame, so fast enemies running into the swing still count.
Get the script
Melee hitbox script for any Tool
One Script in ServerScriptService: every Tool tagged Melee checks a box in front of its holder and damages each enemy once per swing.
-- Script in ServerScriptService named MeleeHitbox.
-- Every Tool tagged "Melee" checks a box in front of its holder after each click.
local CollectionService = game:GetService("CollectionService")
local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local DAMAGE = 20 -- health each hit takes
local SWING_COOLDOWN = 0.6 -- seconds between swings for one player
local HITBOX_SIZE = Vector3.new(5, 5, 5) -- width, height and depth of the box in studs
local HITBOX_DISTANCE = 3.5 -- studs from the attacker's root to the centre of the box
local WINDUP = 0.1 -- seconds between the click and the hitbox turning on
local ACTIVE_TIME = 0.2 -- seconds the hitbox stays on
local FRIENDLY_FIRE = false -- true lets players hurt their own team
local SHOW_HITBOX = false -- true draws the box in red while it is on
local lastSwing: { [Player]: number } = {}
local function isTeammate(attacker: Player, target: Player?): boolean
if FRIENDLY_FIRE or not target then
return false
end
return not attacker.Neutral and not target.Neutral and attacker.Team == target.Team
end
-- A red see-through part that shows where the hitbox is. CanQuery is off,
-- so the hitbox never finds its own debug part.
local function makeDebugBox(): Part
local box = Instance.new("Part")
box.Name = "HitboxDebug"
box.Anchored = true
box.CanCollide = false
box.CanTouch = false
box.CanQuery = false
box.Transparency = 0.7
box.Color = Color3.fromRGB(255, 60, 60)
box.Size = HITBOX_SIZE
box.Parent = workspace
return box
end
local function swing(attacker: Player, character: Model, root: BasePart)
local params = OverlapParams.new()
params.ExcludeInstances = { character } -- never hit yourself or your own sword
local alreadyHit: { [Model]: boolean } = {} -- one hit per character per swing
local debugBox = if SHOW_HITBOX then makeDebugBox() else nil
local startTime = os.clock()
local connection: RBXScriptConnection? = nil
connection = RunService.Heartbeat:Connect(function()
-- Turn the hitbox off when its time is up or the attacker is gone
if os.clock() - startTime > ACTIVE_TIME or not root:IsDescendantOf(workspace) then
if connection then
connection:Disconnect()
end
if debugBox then
debugBox:Destroy()
end
return
end
-- The box follows the attacker: HITBOX_DISTANCE studs in front of their root
local boxCFrame = root.CFrame * CFrame.new(0, 0, -HITBOX_DISTANCE)
if debugBox then
debugBox.CFrame = boxCFrame
end
for _, part in workspace:GetPartBoundsInBox(boxCFrame, HITBOX_SIZE, params) do
local model = part:FindFirstAncestorOfClass("Model")
local humanoid = model and model:FindFirstChildOfClass("Humanoid")
if model and humanoid and humanoid.Health > 0 and not alreadyHit[model] then
alreadyHit[model] = true
if not isTeammate(attacker, Players:GetPlayerFromCharacter(model)) then
humanoid:TakeDamage(DAMAGE)
end
end
end
end)
end
local function setUpTool(instance: Instance)
if not instance:IsA("Tool") then
return
end
local tool = instance
-- Activated fires on the server too, so the client needs no RemoteEvent for a click
tool.Activated:Connect(function()
local character = tool.Parent
if not (character and character:IsA("Model")) then
return
end
local attacker = Players:GetPlayerFromCharacter(character)
local humanoid = character:FindFirstChildOfClass("Humanoid")
local root = humanoid and humanoid.RootPart
if not (attacker and humanoid and root) or humanoid.Health <= 0 then
return
end
-- The cooldown is checked here, on the server, per player
local now = os.clock()
if now - (lastSwing[attacker] or 0) < SWING_COOLDOWN then
return
end
lastSwing[attacker] = now
task.wait(WINDUP)
-- Still holding this weapon and still alive after the windup?
if tool.Parent ~= character or humanoid.Health <= 0 then
return
end
swing(attacker, character, root)
end)
end
for _, tool in CollectionService:GetTagged("Melee") do
setUpTool(tool)
end
CollectionService:GetInstanceAddedSignal("Melee"):Connect(setUpTool)
Players.PlayerRemoving:Connect(function(player: Player)
lastSwing[player] = nil
end)
RoCode builds it in the place you have open in Roblox Studio, on Windows or macOS with a desktop browser; on a phone the button sends the prompt and the link to your computer. Free to start, with free credits every day. More Roblox Studio scripts
Where to put it
ServerScriptService
MeleeHitbox Script new
StarterPack
Sword Tool (tag: Melee)
Handle Part
Settings you can change
DAMAGEIn the script- Health each hit takes. Players have 100 health by default. Default:
20. SWING_COOLDOWNIn the script- Seconds between swings for one player. The server checks it, so an auto clicker cannot swing faster. Default:
0.6. SHOW_HITBOXIn the script- Set to
truewhile testing to draw the box in red each time it is on. Default:false.
Tag the Tool, not the Handle: select the Tool, scroll to Tags in the Properties window, click + and type Melee.
What a cheater can and cannot doThe client only says "I clicked" (the Tool's Activated event). The server picks the box, the cooldown and the damage, so a cheater cannot hit from across the map or swing faster. They can still move their own character, so a player who teleports next to someone can hit them: why, and what helps.
Type-checked with luau-lsp strict against Roblox's API definitions on 14 November 2026. Not playtested in Studio yet: press Play and watch the Output window before you publish.
Prompt for RoCode
Add a melee hitbox to my game: one Script in ServerScriptService that makes every Tool tagged Melee check a 5 by 5 by 5 stud box 3.5 studs in front of the holder with GetPartBoundsInBox for 0.2 seconds after each click, excludes the attacker, damages each other character once per swing for 20, has a 0.6 second server cooldown per player and no friendly fire.
On this page
How a hitbox works
When a player swings, the server places an invisible box in front of them and asks the engine which parts are inside it. Most of those parts are body parts: an arm, a torso, a leg. Each one belongs to a character Model with a Humanoid. The script walks up from each part to its Model, damages that Humanoid once, and ignores the rest of the parts from the same body.
Roblox has three spatial queries. All three live on workspace and take an optional OverlapParams that says what to skip.
| Method | Shape it checks | Good for |
|---|---|---|
GetPartBoundsInBox(cframe, size, params) | A box you describe with a CFrame and a size. It compares bounding boxes, so it is fast. | Swords, punches, kicks: almost every melee hitbox. |
GetPartBoundsInRadius(position, radius, params) | A sphere around a point, again by bounding box. | Ground slams and explosions that hit all around. |
GetPartsInPart(part, params) | The real shape of an existing part, such as a mesh or a wedge. | Odd shapes where a box is too rough. Slower. |
Step 1: Try a box query
Before wiring a weapon, see what a box query returns. This test script checks a box at the middle of the map once a second and prints every character inside it.
- Hover over ServerScriptService in the Explorer, click + and insert a Script. Name it
HitboxTest. - Paste the code below and press Play. Walk to the middle of the Baseplate and watch the Output window.
- Delete the script when you are done. It is only for learning.
-- Script in ServerScriptService named HitboxTest. Delete it after testing.
local BOX_CFRAME = CFrame.new(0, 3, 0) -- the centre of the box
local BOX_SIZE = Vector3.new(8, 6, 8) -- width, height and depth in studs
while true do
local found: { [Model]: boolean } = {}
for _, part in workspace:GetPartBoundsInBox(BOX_CFRAME, BOX_SIZE) do
-- A body part's first Model ancestor is the character
local model = part:FindFirstAncestorOfClass("Model")
if model and model:FindFirstChildOfClass("Humanoid") then
found[model] = true
end
end
for model in found do
print(model.Name, "is inside the box")
end
task.wait(1)
end
The query returns parts, not players, and it returns every part: the Baseplate under you, your head, both arms and any accessories. That is why the script stores each Model in the found table first. Using the Model as a table key means a character with 15 parts inside the box is still counted once. The real hitbox uses the same trick.
Step 2: A hitbox for every melee weapon
Now the real thing. One Script handles every Tool tagged Melee, so a sword, an axe and a frying pan all share the same hitbox code.
- Make the weapon: insert a Tool into StarterPack and name it
Sword. Insert a Part inside it named exactlyHandle(the Tool holds it by this part). Untick Anchored on the Handle. - Select the Tool, find Tags in the Properties window, click + and type
Melee. - Insert a Script into ServerScriptService named
MeleeHitboxand paste the code below.
-- Script in ServerScriptService named MeleeHitbox.
-- Every Tool tagged "Melee" checks a box in front of its holder after each click.
local CollectionService = game:GetService("CollectionService")
local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local DAMAGE = 20 -- health each hit takes
local SWING_COOLDOWN = 0.6 -- seconds between swings for one player
local HITBOX_SIZE = Vector3.new(5, 5, 5) -- width, height and depth of the box in studs
local HITBOX_DISTANCE = 3.5 -- studs from the attacker's root to the centre of the box
local WINDUP = 0.1 -- seconds between the click and the hitbox turning on
local ACTIVE_TIME = 0.2 -- seconds the hitbox stays on
local FRIENDLY_FIRE = false -- true lets players hurt their own team
local SHOW_HITBOX = false -- true draws the box in red while it is on
local lastSwing: { [Player]: number } = {}
local function isTeammate(attacker: Player, target: Player?): boolean
if FRIENDLY_FIRE or not target then
return false
end
return not attacker.Neutral and not target.Neutral and attacker.Team == target.Team
end
-- A red see-through part that shows where the hitbox is. CanQuery is off,
-- so the hitbox never finds its own debug part.
local function makeDebugBox(): Part
local box = Instance.new("Part")
box.Name = "HitboxDebug"
box.Anchored = true
box.CanCollide = false
box.CanTouch = false
box.CanQuery = false
box.Transparency = 0.7
box.Color = Color3.fromRGB(255, 60, 60)
box.Size = HITBOX_SIZE
box.Parent = workspace
return box
end
local function swing(attacker: Player, character: Model, root: BasePart)
local params = OverlapParams.new()
params.ExcludeInstances = { character } -- never hit yourself or your own sword
local alreadyHit: { [Model]: boolean } = {} -- one hit per character per swing
local debugBox = if SHOW_HITBOX then makeDebugBox() else nil
local startTime = os.clock()
local connection: RBXScriptConnection? = nil
connection = RunService.Heartbeat:Connect(function()
-- Turn the hitbox off when its time is up or the attacker is gone
if os.clock() - startTime > ACTIVE_TIME or not root:IsDescendantOf(workspace) then
if connection then
connection:Disconnect()
end
if debugBox then
debugBox:Destroy()
end
return
end
-- The box follows the attacker: HITBOX_DISTANCE studs in front of their root
local boxCFrame = root.CFrame * CFrame.new(0, 0, -HITBOX_DISTANCE)
if debugBox then
debugBox.CFrame = boxCFrame
end
for _, part in workspace:GetPartBoundsInBox(boxCFrame, HITBOX_SIZE, params) do
local model = part:FindFirstAncestorOfClass("Model")
local humanoid = model and model:FindFirstChildOfClass("Humanoid")
if model and humanoid and humanoid.Health > 0 and not alreadyHit[model] then
alreadyHit[model] = true
if not isTeammate(attacker, Players:GetPlayerFromCharacter(model)) then
humanoid:TakeDamage(DAMAGE)
end
end
end
end)
end
local function setUpTool(instance: Instance)
if not instance:IsA("Tool") then
return
end
local tool = instance
-- Activated fires on the server too, so the client needs no RemoteEvent for a click
tool.Activated:Connect(function()
local character = tool.Parent
if not (character and character:IsA("Model")) then
return
end
local attacker = Players:GetPlayerFromCharacter(character)
local humanoid = character:FindFirstChildOfClass("Humanoid")
local root = humanoid and humanoid.RootPart
if not (attacker and humanoid and root) or humanoid.Health <= 0 then
return
end
-- The cooldown is checked here, on the server, per player
local now = os.clock()
if now - (lastSwing[attacker] or 0) < SWING_COOLDOWN then
return
end
lastSwing[attacker] = now
task.wait(WINDUP)
-- Still holding this weapon and still alive after the windup?
if tool.Parent ~= character or humanoid.Health <= 0 then
return
end
swing(attacker, character, root)
end)
end
for _, tool in CollectionService:GetTagged("Melee") do
setUpTool(tool)
end
CollectionService:GetInstanceAddedSignal("Melee"):Connect(setUpTool)
Players.PlayerRemoving:Connect(function(player: Player)
lastSwing[player] = nil
end)
The box is placed with root.CFrame * CFrame.new(0, 0, -HITBOX_DISTANCE). Multiplying by a CFrame moves in the root's own directions, and in Roblox the front of a part is its minus Z side, so minus 3.5 on Z means 3.5 studs in front of the attacker, whichever way they face.
The alreadyHit table is the "one hit per swing" rule. The hitbox runs every frame for 0.2 seconds, which is around a dozen checks. Without the table, an enemy standing in the box would take damage on every one of them and die from a single swing. Each new swing makes a new empty table, so the next swing can hit them again.
The tag works for Tools copied from StarterPack too. Every time a player spawns, Roblox copies the Sword into their Backpack, the copy keeps its Melee tag, and GetInstanceAddedSignal sets it up.
Step 3: Tune the box with the debug view
A hitbox that feels unfair is usually the wrong size or in the wrong place. Set SHOW_HITBOX = true, press Play, and swing at a dummy (the Rig Builder in the Avatar tab inserts one). The red box appears for each swing and follows you while it is on.
| Weapon | HITBOX_SIZE | HITBOX_DISTANCE | ACTIVE_TIME |
|---|---|---|---|
| Punch | Vector3.new(4, 4, 4) | 2.5 | 0.15 |
| Sword | Vector3.new(5, 5, 5) | 3.5 | 0.2 |
| Spear | Vector3.new(3, 4, 9) | 5.5 | 0.2 |
| Big hammer | Vector3.new(8, 6, 7) | 4 | 0.3 |
These are starting points, not rules. Make the box a little bigger than looks right: players judge hits by what they see on their screen, which is slightly behind what the server sees (next section). Set WINDUP to the moment in your swing animation where the blade is in front of the player, so the hit lands when it looks like it should.
Lag, fairness and cheaters
The server checks the box against where it thinks each character is. Every player's device sends its own character's position to the server, which takes a moment, so the server's picture is a little behind each screen. A swing that clearly connected on your screen can miss on the server by a stud or so. A slightly larger box and a hitbox that stays on for a few frames hide most of this.
- What the server stops: swinging faster than the cooldown, hitting with a weapon you are not holding, hitting while dead, hitting from far away, hitting the same enemy many times per swing.
- What it cannot fully stop: a cheater moves their own character, so they could teleport next to someone and swing. Big games add movement checks on the server (such as comparing how far a character moved against its WalkSpeed). That is a separate system and not part of this guide.
Step 4: A reusable Hitbox module
Once you have a sword, you will want a kick, a dash attack and a boss slam. Instead of copying the swing loop each time, move it into a ModuleScript that any server script can call. If ModuleScripts are new to you, the ModuleScripts guide explains require first.
- Insert a ModuleScript into ServerScriptService and name it
Hitbox. - Paste the code below. It does not hurt anyone itself: it calls your function once for each character it finds.
-- ModuleScript in ServerScriptService named Hitbox.
-- Hitbox.run checks a box attached to a part every frame for a while and calls onHit
-- once for each character inside it. It returns a function that stops it early.
local RunService = game:GetService("RunService")
export type Options = {
size: Vector3, -- the box size in studs
offset: CFrame, -- where the box sits, relative to the part it follows
duration: number, -- seconds the hitbox stays on
exclude: { Instance }, -- things it must never hit, usually the attacker's character
showDebug: boolean?, -- draw the box in red while testing
}
local Hitbox = {}
function Hitbox.run(follow: BasePart, options: Options, onHit: (character: Model, humanoid: Humanoid) -> ()): () -> ()
local params = OverlapParams.new()
params.ExcludeInstances = options.exclude
local alreadyHit: { [Model]: boolean } = {}
local startTime = os.clock()
local debugBox: Part? = nil
if options.showDebug then
local box = Instance.new("Part")
box.Name = "HitboxDebug"
box.Anchored = true
box.CanCollide = false
box.CanTouch = false
box.CanQuery = false
box.Transparency = 0.7
box.Color = Color3.fromRGB(255, 60, 60)
box.Size = options.size
box.Parent = workspace
debugBox = box
end
local connection: RBXScriptConnection? = nil
local function stop()
if connection then
connection:Disconnect()
connection = nil
end
if debugBox then
debugBox:Destroy()
debugBox = nil
end
end
connection = RunService.Heartbeat:Connect(function()
if os.clock() - startTime > options.duration or not follow:IsDescendantOf(workspace) then
stop()
return
end
local boxCFrame = follow.CFrame * options.offset
if debugBox then
debugBox.CFrame = boxCFrame
end
for _, part in workspace:GetPartBoundsInBox(boxCFrame, options.size, params) do
local model = part:FindFirstAncestorOfClass("Model")
local humanoid = model and model:FindFirstChildOfClass("Humanoid")
if model and humanoid and humanoid.Health > 0 and not alreadyHit[model] then
alreadyHit[model] = true
task.spawn(onHit, model, humanoid)
end
end
end)
return stop
end
return Hitbox
Any server script can now make a hitbox in a few lines. This one is a ground slam for a boss NPC: a wide, flat box around the boss that hits every player nearby once.
-- Script inside a boss NPC Model, named BossSlam.
local ServerScriptService = game:GetService("ServerScriptService")
type HitboxModule = {
run: (follow: BasePart, options: {
size: Vector3,
offset: CFrame,
duration: number,
exclude: { Instance },
showDebug: boolean?,
}, onHit: (character: Model, humanoid: Humanoid) -> ()) -> () -> (),
}
local Hitbox = require(ServerScriptService:WaitForChild("Hitbox")) :: HitboxModule
local SLAM_DAMAGE = 35
local SLAM_EVERY = 6 -- seconds between slams
local boss = script.Parent :: Model
local root = boss:WaitForChild("HumanoidRootPart") :: BasePart
while true do
task.wait(SLAM_EVERY)
Hitbox.run(root, {
size = Vector3.new(18, 4, 18), -- wide and flat, around the boss
offset = CFrame.new(0, -2, 0), -- slightly below the root, at the boss's feet
duration = 0.25,
exclude = { boss },
}, function(_character: Model, humanoid: Humanoid)
humanoid:TakeDamage(SLAM_DAMAGE)
end)
end
The boss script repeats the module's types in a small type HitboxModule so strict mode knows what Hitbox.run takes. This slam hits NPCs and players alike. Add a Players:GetPlayerFromCharacter(character) check inside the function if only players should take damage.
Step 5: Test it
- Insert a dummy to hit: Avatar tab, Rig Builder, pick any rig. Place it in front of the spawn.
- Set
SHOW_HITBOX = truein MeleeHitbox and press Play. - Equip the Sword (press 1) and click near the dummy. The red box appears and the dummy loses 20 health per swing.
- Click as fast as you can: swings faster than 0.6 seconds apart do nothing.
- To test two players, open the Test tab, set the player count to 2 under Clients and Servers and click Start. Put both players on the same team in the Explorer to check that friendly fire is off.
- Set
SHOW_HITBOXback tofalsebefore you publish.
Common errors and fixes
If swings do nothing, open the Output window first. Then check these in order.
Clicking does nothing at all
Check the Tool has a part named exactly Handle, or untick the Tool's RequiresHandle property if it has none. Then check the Tool is tagged Melee (the Tool itself, not the Handle) and that MeleeHitbox is a Script in ServerScriptService.
The red box appears but nobody takes damage
The box is probably in the wrong place. Watch it while you swing and change HITBOX_DISTANCE or HITBOX_SIZE. Also check the target has CanQuery ticked on its parts: parts with CanQuery off are invisible to spatial queries.
One swing kills instantly
The alreadyHit check is missing or the table is made outside swing. It must be a new table for every swing.
Teammates still hurt each other
Both players need a Team and Neutral must be off. In Studio, players with no team count as neutral, and neutral players can always hit each other. The team system guide sets teams up.
I get "attempt to index nil" on the root
The character has no HumanoidRootPart yet or the Humanoid has no RootPart. The script returns early in that case. If you call your own code, check humanoid.RootPart before you use it: see attempt to index nil with.
Build it with RoCode
If you would rather not set this up by hand, RoCode can build it in the place you have open. RoCode is an independent AI agent for Roblox Studio, not made by Roblox: you describe the change in a web chat, and its Studio plugin creates the parts and scripts in your Explorer, so there is no code to paste.
Give my sword, axe and fists a server-side hitbox: a box in front of the player for 0.2 seconds after each click that hits each enemy once, 20 damage, 0.6 second cooldown, no friendly fire.
- Can read your place first to find the weapons you mean, then tags them and writes one script for all of them
- Writes the scripts with Create Script and is told to compile-check each one with Check Script
- Sets an undo point before and after each batch of changes, so Ctrl+Z steps back one batch at a time
A whole battlegrounds game is a few prompts, one system at a time: how building one system per prompt works. How RoCode connects to Studio.
Questions
How do I make a hitbox in Roblox Studio?
On the server, call workspace:GetPartBoundsInBox with a box in front of the attacker, exclude the attacker with OverlapParams, and damage the Humanoid of each character it finds once. Step 2 has a complete script for any Tool.
What is the best hitbox method in Roblox?
For melee, GetPartBoundsInBox run on the server for a short window is the usual choice: it is fast and catches players standing still. Use GetPartsInPart when the real shape matters more than speed, and raycasts for guns.
Should hitboxes be on the client or the server?
The server. A client-side hitbox lets a cheater report hits that never happened. Make the server box a little larger to make up for lag instead.
How do I stop a hitbox hitting the same player twice?
Keep a table of characters already hit, made fresh for each swing, and skip any character already in it. That is the alreadyHit table in Step 2.
Why does my Touched hitbox not work?
Touched fires only when parts start touching through physics, so it misses players who are standing still and fires many times for one body. Spatial queries do not have these problems.
Can I see my hitbox?
Yes. Set SHOW_HITBOX = true in Step 2. The script draws a red see-through part with CanQuery off, so it never hits itself.
Sources and further reading
- Roblox Creator Docs: WorldRoot. GetPartBoundsInBox, GetPartBoundsInRadius and GetPartsInPart
- Roblox Creator Docs: OverlapParams. ExcludeInstances, IncludeInstances and MaxParts
- Roblox Creator Docs: Tool. Activated, Handle and RequiresHandle
- Roblox Creator Docs: Humanoid. TakeDamage and RootPart
How the code was checked: every script on this page passes Luau's strict type checker against Roblox's API definitions (luau-lsp, 14 November 2026). A type check catches misspelt APIs and wrong types, not game logic, so playtest in Studio before you publish.