EZ Hitbox - Hitbox made easy

Resources Community Resources
, ,
1

EZ Hitbox

A flexible, high-performance hitbox system for Roblox games that supports both server and client-side hit detection with advanced features like hit point detection, velocity prediction, and comprehensive debugging tools.

Github | Wally | Roblox

Core Functionality

  • :bullseye: Server and client-side hit detection - Choose the best approach for your game
  • :magnifying_glass_tilted_left: Precise hit point detection - Get exact collision positions, normals, and materials
  • :triangular_ruler: Multiple hitbox shapes - Support for box, sphere, and custom part shapes
  • :bust_in_silhouette: Flexible target detection - Detect humanoids, objects, or both
  • :rocket: Velocity prediction - Compensate for fast-moving hitboxes
  • :bug: Visual debugging - See your hitboxes in real-time

Advanced Features

  • :high_voltage: High performance - Optimized spatial queries and caching
  • :stopwatch: Configurable parameters - Debounce time, lifetime, and more
  • :prohibited: Blacklist support - Exclude specific instances from detection
  • :satellite_antenna: Signal-based events - Clean, reactive hit detection system
  • :wrench: Proper cleanup - Automatic memory management and resource cleanup
  • :video_game: Easy integration - Simple API that works with any Roblox game

Setup

  1. Place the HitboxSettings folder in ReplicatedStorage
  2. Add the following object values to the settings folder:
    • Alive Folder: Reference to the folder containing all alive characters
    • Ignore Folder: Reference to the folder where the hitbox will ignore
    • Velocity Constant: (Optional) Numeric value for velocity calculations (default: 6)

Usage Examples

Basic Hitbox

local Hitbox = require(path.to.Hitbox)

local hitbox = Hitbox.new({
    InitialCframe = character.HumanoidRootPart.CFrame,
    SizeOrPart = Vector3.new(5, 5, 5),
    Debug = true
})

hitbox.OnHit:Connect(function(hitCharacters)
    for _, character in ipairs(hitCharacters) do
        local humanoid = character:FindFirstChildOfClass("Humanoid")
        humanoid:TakeDamage(10)
    end
end)

hitbox:Start()

-- When done:
hitbox:Destroy()

Attaching Hitbox to a Moving Part

local Hitbox = require(path.to.Hitbox)

local hitbox = Hitbox.new({
    SizeOrPart = Vector3.new(5, 5, 5),
    VelocityPrediction = true
})

hitbox:Start()
hitbox:WeldTo(character.HumanoidRootPart)

-- Change offset later:
hitbox:ChangeWeldOffset(CFrame.new(0, 0, -2))

API Reference

Constructors

Hitbox.new(params: HitboxParams)

Creates a new hitbox with the specified parameters.

Parameters:

  • SizeOrPart (Vector3 | number | BasePart) — Required
    Hitbox dimensions, radius, or reference part.
  • SpatialOption ("InBox" | "InRadius" | "InPart") — Auto-detected
    Detection method.
  • InitialCFrame (CFrame) — Default: CFrame.new()
    Starting position and orientation.
  • Blacklist ({ Model }) — Default: {}
    Models to exclude.
  • DebounceTime (number) — Default: 0
    Cooldown per target.
  • DotProductRequirement (DotProductRequirement) — Default: nil
    Directional filtering.
    Enable client-side detection.
  • ID (string | number) — Default: nil
    Unique hitbox ID.
  • VelocityPrediction (boolean) — Default: false
    Adjust for target movement.
  • Debug (boolean) — Default: false
    Show visual debug output.
  • LifeTime (number) — Default: math.huge
    Duration before auto-destroy.
  • LookingFor ("Humanoid" | "Object") — Default: "Humanoid"
    Target filter type.
  • DetectHitPoints (boolean) — Default: false
    Enables hit point precision.

Simple Example

External Media

UPDATES

v4.1.0
v4.0.1
v3.0.0
v2.0.0

42 Likes
2

Nice looking, Could you add it to the marketplace/rbxm file?

1 Like
3

added the link to the installation header

2 Likes
4

Very cool, will be using in future projects :slight_smile:

2 Likes
5

Thank you king, this is super useful.

2 Likes
6

Ironic to see this was made the same day that I learned how to validate hitbox from Roblox’s FPS system properly lol

2 Likes
7

Appreciate it. Let me know if anything breaks or could be better

2 Likes
8

Amazing resource! Thanks for sharing it with the community :two_hearts:

1 Like
9

Update v2.0.0

:warning: BREAKING CHANGE: The following method names have been modernized. Update your code accordingly:

| Old Name | New Name | Change Type |

| ClearTaggedChars() | ClearTaggedCharacters() | :arrows_counterclockwise: Renamed |

| SetVelocityPrediction() | EnableVelocityPrediction() | :arrows_counterclockwise: Renamed |

| SetDebug() | EnableDebug() | :arrows_counterclockwise: Renamed |

| ChangeWeldOffset() | SetWeldOffset() | :arrows_counterclockwise: Renamed |

| ClearHitboxesWithID() | ClearHitboxesByID() | :arrows_counterclockwise: Renamed |

| ClearClientHitboxes() | ClearHitboxesForClient() | :arrows_counterclockwise: Renamed |

| SetPosition() | SetCFrame() | :arrows_counterclockwise: Renamed |

| HitSomeone() | OnHit() | :arrows_counterclockwise: Renamed |

| InitialPosition | InitialCframe | :arrows_counterclockwise: Renamed |

Migration Example


-- Old code (v1.x)

hitbox:ClearTaggedChars()

hitbox:SetDebug(true)

hitbox:ChangeWeldOffset(CFrame.new(0, 1, 0))

Hitbox.ClearHitboxesWithID("combat")

-- New code (v2.0+)

hitbox:ClearTaggedCharacters()

hitbox:EnableDebug(true)

hitbox:SetWeldOffset(CFrame.new(0, 1, 0))

Hitbox.ClearHitboxesByID("combat")
2 Likes
10

Update v2.0.1

Refactor HitboxParams to replace Debris with LifeTime and fixed automatic destruction not working

1 Like
11

Wow, this feels like this is just EXACTLY like HitboxClass…

1 Like
12

v3.0.0

:dart: Advanced Hit Point Detection

Get precise hit locations for visual effects, bullet holes, or damage zones:

local Hitbox = require(path.to.Hitbox)

local hitbox = Hitbox.new({
    SizeOrPart = Vector3.new(5, 5, 5),
    VelocityPrediction = true,
    DetectHitPoints = true, -- Enable precise hit detection
    LookingFor = "Object",
    LifeTime = 2.0,
    Debug = true
})

-- Handle hits with precise location data
hitbox.HitObjectWithPoint:Connect(function(hitData)
    for _, data in pairs(hitData) do
        print("Hit:", data.Object.Name)
        print("Position:", data.Position)
        print("Surface Normal:", data.Normal)
        print("Material:", data.Material)
        
        -- Create bullet hole decal
        createBulletHole(data.Object, data.Position, data.Normal)
        
        -- Spawn impact particles
        spawnImpactEffect(data.Position, data.Normal, data.Material)
    end
end)

hitbox:Start()

Hitbox.OnHitWithPoint: Signal<{HitPointData}>

Fires when the hitbox detects characters with precise hit data (requires DetectHitPoints = true).

Hitbox.HitObjectWithPoint: Signal<{HitPointData}>

Fires when the hitbox detects objects with precise hit data (requires DetectHitPoints = true).

3 Likes
13

How performant is this module?

I am looking to use the hitbox on the client-side for a VR game.

14

Is this HitboxClass rewrite or something?

15

Yes, with more features, updated dependencies, and optimized. You can check the GitHub and compare the changes

16

it is performant as long as you are following best pratices. e.g destroying when not being used. I do plan on simplifying the client hitbox creation as it can be a bit confusing rn

1 Like
17

I don’t know if I’m uninformed because I’m not looking at the code, but couldn’t UseClient be exploited?

UseClient (Player) — Default: nil
Enable client-side detection.

18

Aslong you are not using it to do important checks it could save some memory usage on the server

1 Like
19

Like @1lways said, depends on what you use it for

21

This EZ hitbox module saved my studio from shutting down. It cured my depression, shaved my cat, and made me more money than grow a garden on a saturday morning. I can’t recommend this modular EZ hitbox enough. I think every developer needs this as it will change the trajectory of their roblox careers