5.1.5 Hit detection

Why Hit Detection Matters

Hit detection is the system that decides if an attack actually connects with a target. In Roblox combat games this turns animations and effects into real gameplay. Without reliable hit detection, players feel cheated, because what they see on screen does not match what the game decides.

In this chapter you focus on how to detect hits in Roblox for both melee and ranged attacks, and how to turn those hits into useful information for your damage and health systems. You do not design the damage rules here, you only make sure you know exactly when and what was hit.

Common Approaches to Hit Detection

There are several practical patterns for hit detection in Roblox. Each has different tradeoffs between accuracy, performance, and ease of implementation.

Hitboxes are a very common approach. A hitbox is usually an invisible Part or a small collection of Parts that roughly match a weapon or part of a character. During an attack, you move or enable these hitboxes and listen for physics events such as Touched to know when they intersect another character.

Raycasts are another central technique. A raycast is a virtual line that you cast from one point to another. The Roblox physics engine tells you which object the ray first hits, along with the hit position and surface normal. This is especially useful for ranged weapons and precise melee stabs.

Overlap checks, also called region checks or area checks, test which objects are inside a certain area at a given moment. Instead of waiting for collisions to happen, you ask the engine what is currently inside a box, sphere, or capsule around a weapon or character. This is well suited for wide swings or area of effect attacks.

Finally, projectile hit detection uses physical objects such as bullets or magic projectiles that move through the world. You then combine Touched events or raycasts between frames of movement to find out when they collide with something.

Each method can be combined. It is common to use hitboxes for melee, raycasts for hitscan guns, and projectiles for visible bullets and spells.

Using `Touched` for Simple Hitboxes

The Touched event is often the first tool you use for hit detection. Any BasePart in Roblox can connect to Touched and TouchEnded. When that part comes into contact with another part, the event fires with the other part as a parameter.

For a melee weapon that uses a hitbox, you might create an invisible Part attached to the weapon model. During a swing animation, you enable this hitbox, and a Script on the server listens like this:

local hitbox = script.Parent.Hitbox
local function onTouched(otherPart)
    local character = otherPart:FindFirstAncestorOfClass("Model")
    if character and character:FindFirstChild("Humanoid") then
        print("Hit character:", character.Name)
        -- Apply damage here or call a combat function
    end
end
hitbox.Touched:Connect(onTouched)

You usually disable the hitbox when the attack is not active to avoid random hits during idle time. This can be done by setting CanTouch or CanCollide or by simply moving the hitbox out of the way, as long as you are consistent.

To reduce duplicate hits inside a single swing, you keep track of which characters were already hit this attack, for example with a table that records humanoids until the attack ends.

Raycasting for Precise Hits

Raycasting lets you perform instant hit detection along a line. In Roblox, you use Workspace:Raycast(origin, direction, raycastParams) and receive a RaycastResult when something is hit.

A typical ranged weapon might create a ray from the gun barrel toward the mouse hit position. You are not implementing the firing logic here, only the detection pattern.

Example of a server side raycast:

local workspace = game:GetService("Workspace")
local function castShot(origin, direction)
    local raycastParams = RaycastParams.new()
    raycastParams.FilterType = Enum.RaycastFilterType.Blacklist
    raycastParams.FilterDescendantsInstances = {script.Parent} -- ignore the shooter
    local result = workspace:Raycast(origin, direction, raycastParams)
    if result then
        local hitPart = result.Instance
        local hitPosition = result.Position
        local normal = result.Normal
        local character = hitPart:FindFirstAncestorOfClass("Model")
        if character and character:FindFirstChild("Humanoid") then
            print("Shot hit:", character.Name, "at", hitPosition)
            -- Apply damage or notify combat system
        else
            print("Shot hit environment at", hitPosition)
        end
    end
end

Note that direction should be a vector that already includes range. If you want a maximum distance of maxDistance, you usually use something like

$$\text{direction} = \text{unitDirection} \times \text{maxDistance}.$$

Raycasting is also useful for melee thrusts, for example from the weapon handle forward by a small distance, to check if someone is directly in front of the weapon when the swing passes a certain animation frame.

Overlap Checks and Area Hits

Overlap checks give you all parts inside a region at once. Roblox provides functions such as Workspace:GetPartsInPart or Workspace:GetPartBoundsInBox. You can use these to detect hits when a weapon is in a certain pose.

For a wide sword swing, you can position a temporary invisible part in the area that the sword passes through, then query which parts are inside it exactly at the moment you want to register hits.

Example using GetPartsInPart on the server:

local workspace = game:GetService("Workspace")
local regionPart = script.Parent.RegionPart -- invisible, non colliding
local function checkSwingHits(attackerCharacter)
    local params = OverlapParams.new()
    params.FilterType = Enum.OverlapFilterType.Blacklist
    params.FilterDescendantsInstances = {attackerCharacter}
    local parts = workspace:GetPartsInPart(regionPart, params)
    local alreadyHit = {}
    for _, part in ipairs(parts) do
        local character = part:FindFirstAncestorOfClass("Model")
        if character and character:FindFirstChild("Humanoid") and not alreadyHit[character] then
            alreadyHit[character] = true
            print("Swing hit:", character.Name)
            -- Handle hit
        end
    end
end

You often call such a function at a specific moment in the animation, for example at the arc peak of a sword swing.

Overlap checks can also handle area of effect attacks such as explosions. You place a region where the effect happens and collect all humanoids inside to treat them as hit.

Handling Projectiles

Projectiles can move as physical parts in the world. If you use real moving bullets, you might attach a server side Script to each projectile part. It listens to Touched and checks what was hit.

A simple pattern is:

local bullet = script.Parent
local function onTouched(otherPart)
    if not bullet:IsDescendantOf(game) then
        return
    end
    local character = otherPart:FindFirstAncestorOfClass("Model")
    if character and character:FindFirstChild("Humanoid") then
        print("Projectile hit:", character.Name)
        -- Apply damage
    end
    bullet:Destroy()
end
bullet.Touched:Connect(onTouched)

Fast projectiles can sometimes tunnel through targets between frames. To avoid this, designers often combine Touched with raycasts from the previous position to the new position every frame. This method, called continuous collision detection, reduces missed hits by checking the whole path, not just the final position.

Controlling Who Can Be Hit

Hit detection is not only about knowing that something was hit, but also deciding whether that hit should count. You often need to ignore certain targets or apply different logic based on teams, ownership, or previous hits.

You might check for a team system, skip friendly targets, or limit each attack to hit a specific enemy only once.

A common approach is to include a filtering function. For example:

local function isValidTarget(attacker, targetCharacter)
    if attacker == targetCharacter then
        return false
    end
    local attackerPlayer = game.Players:GetPlayerFromCharacter(attacker)
    local targetPlayer = game.Players:GetPlayerFromCharacter(targetCharacter)
    if attackerPlayer and targetPlayer then
        if attackerPlayer.Team == targetPlayer.Team then
            return false
        end
    end
    return true
end

You then call isValidTarget before applying any damage. This keeps hit detection logic separate from team and rule logic.

Timing Hits with Animations

Hit detection must line up with animations so that attacks feel responsive. If the sword clearly passes through an enemy, players expect the hit to register at that exact moment.

One approach uses animation events. In Roblox you can place animation events inside an animation track. When the animation reaches a certain frame, it fires a named event to your script. At that point you can enable a hitbox, perform a raycast, or run an overlap check.

For example, an animation for a sword slash might include an event called "HitFrame". Your script could listen for that event:

local humanoid = script.Parent:WaitForChild("Humanoid")
local animator = humanoid:WaitForChild("Animator")
local animation = Instance.new("Animation")
animation.AnimationId = "rbxassetid://123456"
local track = animator:LoadAnimation(animation)
track:GetMarkerReachedSignal("HitFrame"):Connect(function(param)
    -- Perform hit detection here
end)
track:Play()

This approach gives you fine control of when hits happen inside the animation, instead of applying damage at the start or end of the attack.

Client and Server Responsibilities

Visual feedback such as hit sparks, sound effects, and screen shake can happen on the client for responsiveness. The actual decision that a hit occurred and the damage result must stay on the server.

A typical flow is that the client detects that the player attempted an attack, then sends a request to the server. The server performs the actual hit detection with raycasts or hitboxes and returns the result or directly applies damage. After that, the server can inform nearby clients about hit effects through RemoteEvents.

You should avoid trusting the client when it tells the server what it hit. It is safer for the client to say that the player tried to fire in a certain direction or at a certain time, and for the server to confirm exact hit information.

Avoiding Common Hit Detection Problems

There are recurring problems that appear in hit detection systems. One is multiple hits from a single attack because Touched fires several times while parts overlap. You can prevent this by storing a set of already hit characters for each attack and clearing it when the attack ends.

Another problem is hits registering when an attack is not active. This often happens if you never disable hitboxes outside the swing animation. Make sure hitboxes are only active for a short window and inactive the rest of the time.

Sometimes hits feel delayed, for example when you only perform detection at the end of the animation. Moving hit detection closer to the actual swing motion and using animation markers improves this.

Finally, players may experience unfair misses. This can be caused by using only the weapon handle position for raycasts, or by using very small hitboxes that do not match the visual weapon. Slightly larger hitboxes or overlap regions that cover the whole motion can help make hits feel cleaner and more consistent with what the player sees.

By combining hitboxes, raycasts, overlap checks, and solid client server separation, you can build reliable hit detection that supports the combat systems you create in your Roblox games.