Skip to content

Hitbox

The main Hitbox class returned by Module.newHitbox(Fields).

Module.newHitbox(Fields: {string: any})

local hitbox = Module.newHitbox({
    Attachment = attachment or nil,
    Shape = ("Box" or "Sphere") or "Box",
    Position = Vector3 or Vector3.new(0, 0, 0),
    Debounce = number or 5,
    Pierce = number or 1,
    LifeTime = number or 1,
    Orientation = Vector3 or nil,
    CopyCFrame = BasePart or nil,
    CopyCFrameProperties = {CFrame = boolean?, Position = boolean?, Size = boolean?, Orientation = boolean?} or {CFrame = true, Size = true}
    Radius = number or 3,
    Size = Vector3 or Vector3.new(3, 3, 3),
    FilterType = Enum.RaycastFilterType or Enum.RaycastFilterType.Exclude,
    FilterDescendantsInstances = {Instance} or {},
    RespectCanCollide = boolean or false,
    MaxParts = number or 0
}) -> Hitbox
Create a new Hitbox object. Fields are optional.

Public

Hitbox.ShapeEnum

Hitbox.ShapeEnum -- {string: string}
An immutable copy of enum.Shape. Includes ShapeEnum.Box and ShapeEnum.Sphere.

Hitbox.ModeEnum

Hitbox.ModeEnum -- {string: string}
An immutable copy of enum.HitboxMode. Includes ModeEnum.None, ModeEnum.Attachment, ModeEnum.Linear, ModeEnum.Bezier, ModeEnum.Orientation and ModeEnum.Copying

Hitbox.StateEnum

Hitbox.StateEnum -- {string: string}
An immutable copy of enum.StateEnum. Includes StateEnum.Paused, StateEnum.Active and StateEnum.Dead.

Hitbox.ConstructionEnum

Hitbox.ConstructionEnum -- {string: string}
An immutable copy of enum.ConstructionMode. Includes ConstructionEnum.None, ConstructionEnum.Linear and ConstructionEnum.Bezier.

Hitbox.BezierEnum

Hitbox.BezierEnum -- {string: string}
An immutable copy of enum.BezierMode. Includes BezierEnum.Quadratic and BezierEnum.Cubic.

Hitbox.Serial

Hitbox.Serial -- number
A readonly number that is the Hitbox's unique serial. WARNING: Do NOT change under any circumstance.

Hitbox.Shape

Hitbox.Shape -- string
The current shape of the Hitbox. Can be Box or Sphere.

Hitbox.Position

Hitbox.Position -- Vector3
The current center position of the Hitbox. Note: Any changes will be prevented if the Hitbox is currently using a bezier path.

Hitbox.Pierce

Hitbox.Pierce -- number
How many Humanoids can the Hitbox hit in total.

Hitbox.Debounce

Hitbox.Debounce -- number
How many seconds have to pass before the Hitbox can hit the same Humanoid again.

Hitbox.LifeTime

Hitbox.LifeTime -- number
How many seconds the Hitbox has left before it automatically cleans and garbage collects itself. Only counts down while the Hitbox is activated. Note: This property does not countdown if the Hitbox is currently using a bezier path. The Hitbox will clean itself when it reaches the end of the bezier path instead.

Hitbox.Orientation

Hitbox.Orientation -- Vector3
The orientation of the Hitbox. Note: CopyCFrame overrides this property.

Hitbox.CopyCFrame

Hitbox.CopyCFrame -- BasePart
A part which the Hitbox will copy Position, Size and Orientation from. WARNING: Overrides all constructed paths if not nil. Overrides Orientation, Position and Size by default (See Hitbox.CopyCFrameProperties). Does NOT override Hitbox.Shape

Hitbox.CopyCFrameProperties

Hitbox.CopyCFrameProperties -- {CFrame = boolean, Size = boolean, Position = boolean, Orientation = boolean}
A table which determines what properties are copied over from Hitbox.CopyCFrame. Properties with nil or false are ignored and not changed by CopyCFrame. Default {CFrame = true, Size = true} Note: If CFrame is true, Position and Size can be left as nil or false and those properties will be copied over regardless. Same for the other way around.

Hitbox.OverlapParams

Hitbox.OverlapParams -- OverlapParams
The OverlapParams that's used for spatial query.

Hitbox.Active

Hitbox.Active -- boolean
A readonly boolean that displays whether the Hitbox is currently active or not. Note: You should change this with Hitbox:Activate() and Hitbox:Deactivate() instead.

Hitbox.Radius

Hitbox.Radius -- number
The radius of the Hitbox. Used if Hitbox.Shape is Sphere. Note: CopyCFrame overrides this property.

Hitbox.Size

Hitbox.Size -- Vector3
The size of the Hitbox. Used if Hitbox.Shape is Box. Note: CopyCFrame overrides this property.

Hitbox.Trajectory

Hitbox.Trajectory -- Trajectory
The child Trajectory class of the Hitbox. Used for path construction.

Hitbox.Hit

Hitbox.Hit -- ScriptSignal
Hitbox.Hit:Connect(function(Humanoid, HitPart, HitboxDataBundle)
    ...
end)
A ScriptSignal which is fired whenever the Hitbox hits a Humanoid that is not on Debounce and is not dead while the Hitbox is active.

Hitbox.PartEntered

Hitbox.PartEntered -- ScriptSignal
Hitbox.PartEntered:Connect(function(BasePart)
    ...
end)
A ScriptSignal which is fired when any part enters the Hitbox while the Hitbox is active.

Hitbox.PartLeft

Hitbox.PartLeft
Hitbox.PartLeft:Connect(function(BasePart)
    ...
end)
A ScriptSignal which is fired when any part leaves the Hitbox while the Hitbox is active.

Hitbox:Activate()

Hitbox:Activate()
Activates the Hitbox. Note: When a new Hitbox is created, it is deactivated by default. You need to activate it after configuration.

Hitbox:Deactivate()

Hitbox:Deactivate()
Deactivates the Hitbox, pausing all operations.

Hitbox:AddIgnore(object: Instance)

local success = Hitbox:AddIgnore(game.Players.Player1.Character) -> boolean
Add object to FilterDescendentsInstances table of OverlapParams. Returns boolean Success.

Hitbox:RemoveIgnore(object: Instance)

local numOfItemsRemoved = Hitbox:RemoveIgnore(game.Players.Player1.Character) -> number
Remove object from FilterDescendentsInstances table of OverlapParams. Returns number NumberOfItemsRemoved. **Note: The returned number is 0 on an unsuccessful remove, 1 or more on a successful remove.

Hitbox:GetVelocity()

local velocity = Hitbox:GetVelocity() -> number
Returns the Velocity of the Hitbox's constructed path.

Hitbox:SetVelocity()

Hitbox:SetVelocity(velocity: number)
Sets the Velocity of the Hitbox's constructed path to velocity.

Hitbox:ChangeAttachment(attachment: Attachment?)

Hitbox:ChangeAttachment(attachment)
Changes the Hitbox's Attachment to attachment. If attachment is nil, remove Attachment from Hitbox.

Hitbox:IsHitboxBackstab(Part: BasePart, DataBundle: HitboxDataBundle, Margin: number?)

local isBackstab = Hitbox:IsHitboxBackstab(HitPart, HitboxDataBundle, 0.2) -> boolean
Determine if the data described by HitboxDataBundle is a backstab on HitPart. Returns boolean. Margin is an optional number ranging from 0 to 0.5, which determines how lenient the backstab detection is. 0.5 would allow for side-stabs to count as backstabs while 0.1 would require basically perfect alignment. Defaults to 0.32. Note: The detection position originates from the Hitbox's recorded center position.

Hitbox:IsBackstab(Part: BasePart, Character: Model, Margin: number?)

local isBackstab = Hitbox:IsBackstab(Part, Character, 0.4) -> boolean
Determine if Character backstabs Part. Returns boolean. Margin is an optional number ranging from 0 to 0.5, which determines how lenient the backstab detection is. 0.5 would allow for side-stabs to count as backstabs while 0.1 would require basically perfect alignment. Defaults to 0.32. Note: The detection position originates from the provided character's root. Recommended to use this over Hitbox:IsHitboxBackstab() if used in tools of a character.

Hitbox:GetCurrentSerial()

local highestSerial = Hitbox:GetCurrentSerial() -> number
Get the currently highest serial. Returns number.

Hitbox:GetConstructionMode()

local mode = Hitbox:GetConstructionMode() -> string
Returns the Hitbox's Trajectory's ConstructionMode.

Hitbox:GetCurrentMode()

local mode = Hitbox:GetCurrentMode() -> string
Get the current behavior of the Hitbox. See Hitbox.ModeEnum.

Hitbox:Visualize()

local part = Hitbox:Visualize() -> BasePart or nil
Visualizes the Hitbox and returns the visualization part if the Hitbox wasn't already visualizing. WARNING: The visualization only updates once every 5 frames and is UNOPTIMIZED. This should only be used for testing purposes.

Hitbox:Unvisualize(doNotWarn: boolean?)

Hitbox:Unvisualize()
Unvisualizes the Hitbox. Throws a warn if doNotWarn isn't true and the Hitbox wasn't visualizing.

Hitbox:Destroy()

Hitbox:Destroy()
Immediately clean and garbage collect Hitbox and all its children. Hitbox should be dereferenced after this operation.

Private

Note: Private variables, methods and functions should not be used unless you know what you're doing.

Hitbox._Attachment

Hitbox._Attachment -- Attachment or nil
Internal store for the Hitbox's Attachment, if one exists. Note: You should use Hitbox:ChangeAttachment(attachment) instead.

Hitbox._CurrentFrame

Hitbox._CurrentFrame -- number
The current frame of the Hitbox in the Hitbox's frame cycle. Note: Not strictly readonly, but it's a good idea to keep this readonly.

Hitbox._CanWarn

Hitbox._CanWarn -- boolean
An internal variable that acts as throttle to prevent console spam.

Hitbox._Visual

Hitbox._Visual -- BasePart
The part used for the Hitbox's visualization. WARNING: STRICTLY readonly. Use Hitbox:Visualize() and Hitbox:Unvisualize() instead.

Hitbox._Destroying

Hitbox._Destroying -- boolean
Whether the Hitbox is being garbage collected currently or not. WARNINNG: Readonly. The Hitbox should be dereferenced if this value is true.

The main enum is intended to be completely private. You are not meant to access it.