Overview

This hitbox module is a high-performance hitbox system for your games. It provides sphere, box, capsule, cone, and ray-based overlap queries with flexible filtering, multi-hit and cooldown support, status effects, knockback, animation integration, and optional velocity prediction to reduce missed collisions at high speed.

The design goal is predictable server-side hit detection with low allocations and friendly defaults so you can plug it into weapons, abilities, and NPCs.

• Shapes: Sphere, Box, Capsule, Cone, Raycast
• Filtering: Whitelist, Blacklist, Team, Tags, CustomFilter
• Utilities: Damage falloff, crits, life-steal, knockback
• Multi-hit rules and per-target cooldowns
• Animation marker integration and controller helpers
• Debug visualization with pooled parts
• Velocity prediction (Adaptive / Latency / Acceleration)

1. Put the module into ReplicatedStorage.Modules (or another shared folder).
2. Require it from server scripts: local BarbsHitbox = require(ReplicatedStorage.Modules.BarbsHitbox).
3. If using controllers or visual debug parts in Studio, run from ServerScriptService or a script with appropriate permissions.

Simple sphere hitbox example:

local Barbs = require(ReplicatedStorage.Modules.BarbsHitbox)

Barbs.Sphere(workspace.Baseplate.Position + Vector3.new(0,5,0), 6, {
  Owner = workspace.Players.LocalPlayer.Character,
  Visualize = true,
  OnHit = function(hit)
    if hit.Humanoid then
      hit.Humanoid:TakeDamage(10)
    end
  end,
})

BarbsHitbox.Sphere(origin, radius, options)

Runs a sphere overlap at origin with radius radius and the provided options. Returns a table of hit entries.

BarbsHitbox.Box(origin, size, options)

Box overlap defined by CFrame origin and size (Vector3).

BarbsHitbox.Capsule(origin, radius, height, options)

Capsule overlap using an oriented capsule centered on origin.

BarbsHitbox.Cone(origin, radius, halfAngle, options)

Cone overlap using origin CFrame, radius and half-angle in degrees.

BarbsHitbox.Raycast(origin, direction, length, radius, options)

Performs a Raycast then optionally performs a radius check around the hit position. Accepts direction Vector3 and length.

BarbsHitbox.FromAnimationMarker(animator, track, markerName, shape, params, options)

Wires hitbox triggers to animation marker events. Use this for syncing melee attacks to animation frames.

BarbsHitbox.CreateController(shape, origin, param1, param2, options)

Creates a controller object that can be started and stopped. Useful for persistent area effects or continuous sweeps.

BarbsHitbox.ApplyDamage(hitData, options)

Utility to apply damage/knockback from a previously gathered hit entry.

Common fields used in the options table:

• Owner — Character model that owns the hit (used for self-hit filtering and life-steal).
• SelfHit — allow hits on the owner when true.
• HitCooldown — per-target cooldown seconds after a hit.
• MaxCharacters — limit number of characters hit.
• MaxHits — limit total hit entries returned.
• MaxClosest — only return the N closest results.
• MultiHit — table {MaxHits = N, Interval = s} for multi-hit per character.
• DebugMode — "All" | "VolumeOnly" | "HitOnly" | nil.
• Visualize — show debug parts for the overlap volume.
• VisualizeDuration — how long the visual lasts (seconds).
• Offset and OffsetMode — shift the origin in local/world space.
• RequireTags — list of CollectionService tags required on the character.
• TargetParts — match only specific part names ("Head", "Torso").
• FilterTeam — "Enemy" or "Ally" when Owner is provided.
• Whitelist / Blacklist — explicit character lists.
• FilterDescendants — array of instances to exclude from overlap queries.
• DetectNonCharacters — allow hits against arbitrary parts.
• CustomFilter — function(char, part) -> boolean to accept/reject.
• OnHit — function(hitData) callback for each accepted hit.
• DamageFalloff — function(distance) -> damage value.
• HitDelay — delay before firing signals or callbacks.
• Lifetime — controller lifetime (seconds).
• VelocityPrediction — enable prediction (true/false)
• VelocityPredictionMode — "Adaptive" | "Latency"
• VelocityPredictionTime — base prediction time in seconds.
• VelocityUseAcceleration — include accel correction.

Returned hitData shape:

{
  Character = Model or nil,
  Humanoid = Humanoid or nil,
  Root = HumanoidRootPart or nil,
  Part = hit Part,
  Distance = number,
  Damage = optional number,
  FinalDamage = set by processDamage,
  IsCrit = boolean,
}

Prediction helps avoid tunneling when targets or origins move quickly. The module supports three behaviours:

• Adaptive: prediction time scales with speed (good default).
• Latency: adds a latency-based offset using player ping (server-side).
• Acceleration correction: uses recent velocity samples to adjust for changing acceleration.

Best practices

• Keep VelocityPredictionTime small (0.05–0.15). Larger values increase false positives.
• Enable acceleration correction only when necessary — it allocates a tiny cache per options table.
• Clamp insane velocities in gameplay code (e.g., >120 studs/s) instead of increasing prediction time.
• Predict for the part actually used as origin (Attachment or BasePart).

• Cache OverlapParams/RaycastParams using the built-in ParamCache — avoid creating new params each frame.
• Compute prediction once per origin per frame and reuse for multiple hit checks.
• Prefer MaxClosest and SortByDistance to limit heavy processing when many parts overlap.
• Use DetectNonCharacters sparingly — character filtering is cheaper.
• Run high-frequency controllers at a lower tick (e.g., every 2nd Heartbeat) if not required each frame.
• Pool debug parts like the module does to avoid GC spikes.

Controller follow + hitsignals

local controller = BarbsHitbox.CreateController("Sphere", hrp, 8, nil, {Owner = char, Visualize = true})
controller.Hit:Connect(function(hit)
  if hit.Humanoid then
    hit.Humanoid:TakeDamage(12)
  end
end)
controller:Start()

Animation marker

BarbsHitbox.FromAnimationMarker(animator, track, "hit", "Capsule", {origin = rightArm, param1 = 2, param2 = 4}, {Owner = char})

Status effect example

local opts = {StatusEffect = {Name = "Burn", Duration = 5, TickDamage = 2, TickRate = 1}}
BarbsHitbox.Sphere(origin, 6, opts)

No hits registering

Check:

• Are you providing the correct origin (Attachment or part)?
• Is SelfHit blocking your owner?
• Are filters/whitelist/blacklist excluding targets?
• Try enabling Visualize = true in Studio to see the volume.

Prediction seems jittery

Reduce VelocityPredictionTime, disable acceleration correction, or clamp velocities.

• v2.1 — Improved prediction stability, cleaned API docs, performance tuning.
• v2.0 — Added Cone, Raycast radius, controller API, visualization pooling.