HitboxPlus

A flexible and type-safe hitbox library for Roblox with support for box, radius, part, and projectile-based hitboxes.

HitboxPlus is designed for combat systems, abilities, projectiles, melee attacks, detection zones, and other systems that need reusable hit detection.

Features

• Box, radius, and part detection
• Humanoid, part, or combined detection
• Entry and continuous trigger behavior
• Trigger cooldowns
• Re-entry cooldowns
• Target following
• Target offsets
• Velocity prediction
• Runtime configuration
• Debug visualization
• Ignore lists
• Projectile hitboxes
• Typed signals
• Luau type support
• No external Wally dependencies

Installation

Wally

Add HitboxPlus to your wally.toml:

[dependencies]
HitboxPlus = "kkultdeeri/hitboxplus@1.0.5"

Then run:

wally install

Require it from your Packages folder:

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local HitboxPlus = require(ReplicatedStorage.Packages.HitboxPlus)

Basic Usage

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local HitboxPlus = require(ReplicatedStorage.Packages.HitboxPlus)

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,
	Debugging = true,
}))

Hitbox.Triggered:Connect(function(Character)
	print(Character.Name .. " entered the hitbox!")
end)

Hitbox.TriggerEnded:Connect(function(Character)
	print(Character.Name .. " left the hitbox!")
end)

Hitbox:Start()

When you're finished with the hitbox:

Hitbox:Destroy()

Detection Modes

HitboxPlus supports three detection modes:

DetectionMode = "InBox"
DetectionMode = "InRadius"
DetectionMode = "InPart"

Box

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	DetectionMode = "InBox",
	HitboxSize = Vector3.new(10, 6, 10),
}))

Radius

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	DetectionMode = "InRadius",
	HitboxRadius = 10,
}))

Part

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,
	DetectionMode = "InPart",
}))

Detection Targets

Choose what the hitbox should detect:

DetectionTarget = "Humanoid"
DetectionTarget = "Part"
DetectionTarget = "Both"

Example:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,
	DetectionTarget = "Humanoid",
}))

Signals

Humanoid Signals

Hitbox.Triggered:Connect(function(Character)
	print("Entered:", Character)
end)

Hitbox.TriggerEnded:Connect(function(Character)
	print("Left:", Character)
end)

Part Signals

Hitbox.PartTriggered:Connect(function(Part)
	print("Part entered:", Part)
end)

Hitbox.PartTriggerEnded:Connect(function(Part)
	print("Part left:", Part)
end)

Trigger Behavior

Continuous

Repeatedly triggers while the target remains inside.

TriggerBehavior = "Continuous"

On Entry

Triggers only when the target first enters.

TriggerBehavior = "OnEntry"

Example:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	TriggerBehavior = "OnEntry",
}))

Cooldowns

HitboxPlus supports trigger and re-entry cooldowns.

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	TriggerCooldown = 0.25,
	ReEntryCooldown = 0.5,
}))

Responsiveness

Control how frequently the hitbox updates:

Responsiveness = "High"
Responsiveness = "Balanced"
Responsiveness = "Low"

Example:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,
	Responsiveness = "High",
}))

Following Targets

A hitbox can follow a moving BasePart:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = Character.HumanoidRootPart,
	FollowTarget = true,
}))

You can also apply an offset:

TargetOffset = CFrame.new(0, 0, -4)

Example:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = Character.HumanoidRootPart,
	FollowTarget = true,

	TargetOffset = CFrame.new(0, 0, -4),
	HitboxSize = Vector3.new(6, 6, 8),
}))

Velocity Prediction

Velocity prediction can help fast-moving hitboxes track their target more accurately.

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = Character.HumanoidRootPart,

	FollowTarget = true,

	UseVelocityPrediction = true,
	VelocityPredictionTime = 0.1,
}))

Ignore Lists

Ignore specific models:

IgnoreModels = {
	Character,
	AnotherCharacter,
}

Or specific parts:

IgnoreParts = {
	workspace.Part,
	workspace.OtherPart,
}

Example:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	IgnoreModels = {
		Character,
	},
}))

Runtime Configuration

Most hitbox settings can be changed after creation.

Hitbox:SetTarget(workspace.NewTarget)

Hitbox:SetFollowTarget(true)
Hitbox:SetTargetOffset(CFrame.new(0, 0, -5))

Hitbox:SetSize(Vector3.new(10, 5, 10))
Hitbox:SetRadius(15)

Hitbox:SetDetectionTarget("Humanoid")
Hitbox:SetDetectionMode("InBox")
Hitbox:SetTriggerBehavior("OnEntry")

Hitbox:SetTriggerCooldown(0.25)
Hitbox:SetReEntryCooldown(0.5)

Hitbox:SetResponsiveness("High")

Hitbox:SetDebugging(true)
Hitbox:SetDebugColor(Color3.new(1, 0, 0))
Hitbox:SetDebugTransparency(0.8)

Lifecycle

Hitbox:Start()

Hitbox:Pause()
Hitbox:Resume()

Hitbox:Stop()

Hitbox:Clear()

Hitbox:Destroy()

Queries

print(Hitbox:IsRunning())
print(Hitbox:IsPaused())
print(Hitbox:IsDestroyed())

print(Hitbox:GetTarget())
print(Hitbox:GetDetectionMode())
print(Hitbox:GetDetectionTarget())
print(Hitbox:GetResponsiveness())

local TriggeredModels = Hitbox:GetTriggeredModels()
local TriggeredParts = Hitbox:GetTriggeredParts()

Projectiles

HitboxPlus includes a projectile hitbox system for fast-moving BaseParts.

Create projectile information:

local ProjectileInfo = HitboxPlus.Projectile.ProjectileInfo.new({
	Target = ProjectilePart,

	Lifetime = 5,

	HitboxInterval = 0.05,
	HitboxLifetime = 0.1,

	UniqueHits = true,

	HitboxInfo = {
		DetectionMode = "InBox",
		HitboxSize = Vector3.new(4, 4, 4),

		DetectionTarget = "Humanoid",
		Debugging = true,
	},
})

Create and start the projectile:

local Projectile = HitboxPlus.newProjectile(ProjectileInfo)

Projectile.Triggered:Connect(function(Character)
	print("Projectile hit:", Character)
end)

Projectile.PartTriggered:Connect(function(Part)
	print("Projectile hit part:", Part)
end)

Projectile.Ended:Connect(function(Reason)
	print("Projectile ended:", Reason)
end)

Projectile:Start()

Projectile settings can also be changed at runtime:

Projectile:SetTarget(NewPart)

Projectile:SetSize(Vector3.new(6, 6, 6))
Projectile:SetRadius(8)

Projectile:SetDetectionTarget("Humanoid")
Projectile:SetResponsiveness("High")

Projectile:SetDebugging(true)

Debugging

Enable debug visualization:

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	Debugging = true,
	DebugColor = Color3.fromRGB(255, 0, 0),
	DebugTransparency = 0.8,
}))

Type Support

HitboxPlus is written with Luau types and exposes types for hitboxes, configuration, projectiles, detection modes, signals, and more.

Example:

type Hitbox = HitboxPlus.Hitbox

Signals are also typed:

Hitbox.Triggered:Connect(function(Character)
	-- Character is inferred as Model
	print(Character.Name)
end)

Projectile signals are typed as well:

Projectile.Triggered:Connect(function(Character)
	-- Character is inferred as Model
	print(Character.Name)
end)

Projectile.Ended:Connect(function(Reason)
	-- Reason is inferred as string
	print(Reason)
end)

HitboxPlus bundles its internal utilities directly, so no additional Wally packages or type-patching tools are required.

If your editor reports an unknown Wally require after installing or updating packages, make sure Luau LSP sourcemap generation is enabled for your Rojo project.

Example

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local HitboxPlus = require(ReplicatedStorage.Packages.HitboxPlus)

local Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({
	Target = workspace.HitboxPart,

	DetectionTarget = "Humanoid",
	DetectionMode = "InBox",

	HitboxSize = Vector3.new(10, 5, 10),

	TriggerBehavior = "OnEntry",

	Debugging = true,
}))

Hitbox.Triggered:Connect(function(Character)
	print(Character.Name .. " was hit!")
end)

Hitbox:Start()

task.delay(5, function()
	Hitbox:Destroy()
end)

Bundled Utilities

HitboxPlus includes the following utilities directly:

• Signal from Sleitnick/RbxUtil
• t from osyrisrblx/t

These are bundled with HitboxPlus, so they do not need to be added separately to your wally.toml.

Their original license notices are included in THIRD_PARTY_LICENSES.md.

License

HitboxPlus is licensed under the MIT License.

See LICENSE for details.

Third-party license notices can be found in THIRD_PARTY_LICENSES.md.