{"id":"kkultdeeri/hitboxplus","name":"hitboxplus","scope":"kkultdeeri","platform":"roblox","description":"A flexible hitbox and projectile detection library for Roblox","version":"1.0.6","latest":"1.0.6","versions":["1.0.0","1.0.1","1.0.2","1.0.3","1.0.4","1.0.5","1.0.6"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"c7f1c36a089f9b50ed917a0eb257408eb80605f16f76c7deed6f2b1b09b100fd","likes":0,"downloads":0,"install":"forest install kkultdeeri/hitboxplus","url":"https://forest.dev/p/roblox/kkultdeeri/hitboxplus","files":"https://api.forest.dev/ai/package/roblox/kkultdeeri/hitboxplus/files","readme":"# HitboxPlus\r\n\r\nA flexible and type-safe hitbox library for Roblox with support for box, radius, part, and projectile-based hitboxes.\r\n\r\nHitboxPlus is designed for combat systems, abilities, projectiles, melee attacks, detection zones, and other systems that need reusable hit detection.\r\n\r\n## Features\r\n\r\n- Box, radius, and part detection\r\n- Humanoid, part, or combined detection\r\n- Entry and continuous trigger behavior\r\n- Trigger cooldowns\r\n- Re-entry cooldowns\r\n- Target following\r\n- Target offsets\r\n- Velocity prediction\r\n- Runtime configuration\r\n- Debug visualization\r\n- Ignore lists\r\n- Projectile hitboxes\r\n- Typed signals\r\n- Luau type support\r\n- No external Wally dependencies\r\n\r\n## Installation\r\n\r\n### Wally\r\n\r\nAdd HitboxPlus to your `wally.toml`:\r\n\r\n```toml\r\n[dependencies]\r\nHitboxPlus = \"kkultdeeri/hitboxplus@1.0.5\"\r\n```\r\n\r\nThen run:\r\n\r\n```sh\r\nwally install\r\n```\r\n\r\nRequire it from your Packages folder:\r\n\r\n```lua\r\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\r\n\r\nlocal HitboxPlus = require(ReplicatedStorage.Packages.HitboxPlus)\r\n```\r\n\r\n## Basic Usage\r\n\r\n```lua\r\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\r\n\r\nlocal HitboxPlus = require(ReplicatedStorage.Packages.HitboxPlus)\r\n\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\tDebugging = true,\r\n}))\r\n\r\nHitbox.Triggered:Connect(function(Character)\r\n\tprint(Character.Name .. \" entered the hitbox!\")\r\nend)\r\n\r\nHitbox.TriggerEnded:Connect(function(Character)\r\n\tprint(Character.Name .. \" left the hitbox!\")\r\nend)\r\n\r\nHitbox:Start()\r\n```\r\n\r\nWhen you're finished with the hitbox:\r\n\r\n```lua\r\nHitbox:Destroy()\r\n```\r\n\r\n## Detection Modes\r\n\r\nHitboxPlus supports three detection modes:\r\n\r\n```lua\r\nDetectionMode = \"InBox\"\r\nDetectionMode = \"InRadius\"\r\nDetectionMode = \"InPart\"\r\n```\r\n\r\n### Box\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tDetectionMode = \"InBox\",\r\n\tHitboxSize = Vector3.new(10, 6, 10),\r\n}))\r\n```\r\n\r\n### Radius\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tDetectionMode = \"InRadius\",\r\n\tHitboxRadius = 10,\r\n}))\r\n```\r\n\r\n### Part\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\tDetectionMode = \"InPart\",\r\n}))\r\n```\r\n\r\n## Detection Targets\r\n\r\nChoose what the hitbox should detect:\r\n\r\n```lua\r\nDetectionTarget = \"Humanoid\"\r\nDetectionTarget = \"Part\"\r\nDetectionTarget = \"Both\"\r\n```\r\n\r\nExample:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\tDetectionTarget = \"Humanoid\",\r\n}))\r\n```\r\n\r\n## Signals\r\n\r\n### Humanoid Signals\r\n\r\n```lua\r\nHitbox.Triggered:Connect(function(Character)\r\n\tprint(\"Entered:\", Character)\r\nend)\r\n\r\nHitbox.TriggerEnded:Connect(function(Character)\r\n\tprint(\"Left:\", Character)\r\nend)\r\n```\r\n\r\n### Part Signals\r\n\r\n```lua\r\nHitbox.PartTriggered:Connect(function(Part)\r\n\tprint(\"Part entered:\", Part)\r\nend)\r\n\r\nHitbox.PartTriggerEnded:Connect(function(Part)\r\n\tprint(\"Part left:\", Part)\r\nend)\r\n```\r\n\r\n## Trigger Behavior\r\n\r\n### Continuous\r\n\r\nRepeatedly triggers while the target remains inside.\r\n\r\n```lua\r\nTriggerBehavior = \"Continuous\"\r\n```\r\n\r\n### On Entry\r\n\r\nTriggers only when the target first enters.\r\n\r\n```lua\r\nTriggerBehavior = \"OnEntry\"\r\n```\r\n\r\nExample:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tTriggerBehavior = \"OnEntry\",\r\n}))\r\n```\r\n\r\n## Cooldowns\r\n\r\nHitboxPlus supports trigger and re-entry cooldowns.\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tTriggerCooldown = 0.25,\r\n\tReEntryCooldown = 0.5,\r\n}))\r\n```\r\n\r\n## Responsiveness\r\n\r\nControl how frequently the hitbox updates:\r\n\r\n```lua\r\nResponsiveness = \"High\"\r\nResponsiveness = \"Balanced\"\r\nResponsiveness = \"Low\"\r\n```\r\n\r\nExample:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\tResponsiveness = \"High\",\r\n}))\r\n```\r\n\r\n## Following Targets\r\n\r\nA hitbox can follow a moving BasePart:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = Character.HumanoidRootPart,\r\n\tFollowTarget = true,\r\n}))\r\n```\r\n\r\nYou can also apply an offset:\r\n\r\n```lua\r\nTargetOffset = CFrame.new(0, 0, -4)\r\n```\r\n\r\nExample:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = Character.HumanoidRootPart,\r\n\tFollowTarget = true,\r\n\r\n\tTargetOffset = CFrame.new(0, 0, -4),\r\n\tHitboxSize = Vector3.new(6, 6, 8),\r\n}))\r\n```\r\n\r\n## Velocity Prediction\r\n\r\nVelocity prediction can help fast-moving hitboxes track their target more accurately.\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = Character.HumanoidRootPart,\r\n\r\n\tFollowTarget = true,\r\n\r\n\tUseVelocityPrediction = true,\r\n\tVelocityPredictionTime = 0.1,\r\n}))\r\n```\r\n\r\n## Ignore Lists\r\n\r\nIgnore specific models:\r\n\r\n```lua\r\nIgnoreModels = {\r\n\tCharacter,\r\n\tAnotherCharacter,\r\n}\r\n```\r\n\r\nOr specific parts:\r\n\r\n```lua\r\nIgnoreParts = {\r\n\tworkspace.Part,\r\n\tworkspace.OtherPart,\r\n}\r\n```\r\n\r\nExample:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tIgnoreModels = {\r\n\t\tCharacter,\r\n\t},\r\n}))\r\n```\r\n\r\n## Runtime Configuration\r\n\r\nMost hitbox settings can be changed after creation.\r\n\r\n```lua\r\nHitbox:SetTarget(workspace.NewTarget)\r\n\r\nHitbox:SetFollowTarget(true)\r\nHitbox:SetTargetOffset(CFrame.new(0, 0, -5))\r\n\r\nHitbox:SetSize(Vector3.new(10, 5, 10))\r\nHitbox:SetRadius(15)\r\n\r\nHitbox:SetDetectionTarget(\"Humanoid\")\r\nHitbox:SetDetectionMode(\"InBox\")\r\nHitbox:SetTriggerBehavior(\"OnEntry\")\r\n\r\nHitbox:SetTriggerCooldown(0.25)\r\nHitbox:SetReEntryCooldown(0.5)\r\n\r\nHitbox:SetResponsiveness(\"High\")\r\n\r\nHitbox:SetDebugging(true)\r\nHitbox:SetDebugColor(Color3.new(1, 0, 0))\r\nHitbox:SetDebugTransparency(0.8)\r\n```\r\n\r\n## Lifecycle\r\n\r\n```lua\r\nHitbox:Start()\r\n\r\nHitbox:Pause()\r\nHitbox:Resume()\r\n\r\nHitbox:Stop()\r\n\r\nHitbox:Clear()\r\n\r\nHitbox:Destroy()\r\n```\r\n\r\n## Queries\r\n\r\n```lua\r\nprint(Hitbox:IsRunning())\r\nprint(Hitbox:IsPaused())\r\nprint(Hitbox:IsDestroyed())\r\n\r\nprint(Hitbox:GetTarget())\r\nprint(Hitbox:GetDetectionMode())\r\nprint(Hitbox:GetDetectionTarget())\r\nprint(Hitbox:GetResponsiveness())\r\n\r\nlocal TriggeredModels = Hitbox:GetTriggeredModels()\r\nlocal TriggeredParts = Hitbox:GetTriggeredParts()\r\n```\r\n\r\n## Projectiles\r\n\r\nHitboxPlus includes a projectile hitbox system for fast-moving BaseParts.\r\n\r\nCreate projectile information:\r\n\r\n```lua\r\nlocal ProjectileInfo = HitboxPlus.Projectile.ProjectileInfo.new({\r\n\tTarget = ProjectilePart,\r\n\r\n\tLifetime = 5,\r\n\r\n\tHitboxInterval = 0.05,\r\n\tHitboxLifetime = 0.1,\r\n\r\n\tUniqueHits = true,\r\n\r\n\tHitboxInfo = {\r\n\t\tDetectionMode = \"InBox\",\r\n\t\tHitboxSize = Vector3.new(4, 4, 4),\r\n\r\n\t\tDetectionTarget = \"Humanoid\",\r\n\t\tDebugging = true,\r\n\t},\r\n})\r\n```\r\n\r\nCreate and start the projectile:\r\n\r\n```lua\r\nlocal Projectile = HitboxPlus.newProjectile(ProjectileInfo)\r\n\r\nProjectile.Triggered:Connect(function(Character)\r\n\tprint(\"Projectile hit:\", Character)\r\nend)\r\n\r\nProjectile.PartTriggered:Connect(function(Part)\r\n\tprint(\"Projectile hit part:\", Part)\r\nend)\r\n\r\nProjectile.Ended:Connect(function(Reason)\r\n\tprint(\"Projectile ended:\", Reason)\r\nend)\r\n\r\nProjectile:Start()\r\n```\r\n\r\nProjectile settings can also be changed at runtime:\r\n\r\n```lua\r\nProjectile:SetTarget(NewPart)\r\n\r\nProjectile:SetSize(Vector3.new(6, 6, 6))\r\nProjectile:SetRadius(8)\r\n\r\nProjectile:SetDetectionTarget(\"Humanoid\")\r\nProjectile:SetResponsiveness(\"High\")\r\n\r\nProjectile:SetDebugging(true)\r\n```\r\n\r\n## Debugging\r\n\r\nEnable debug visualization:\r\n\r\n```lua\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tDebugging = true,\r\n\tDebugColor = Color3.fromRGB(255, 0, 0),\r\n\tDebugTransparency = 0.8,\r\n}))\r\n```\r\n\r\n## Type Support\r\n\r\nHitboxPlus is written with Luau types and exposes types for hitboxes, configuration, projectiles, detection modes, signals, and more.\r\n\r\nExample:\r\n\r\n```lua\r\ntype Hitbox = HitboxPlus.Hitbox\r\n```\r\n\r\nSignals are also typed:\r\n\r\n```lua\r\nHitbox.Triggered:Connect(function(Character)\r\n\t-- Character is inferred as Model\r\n\tprint(Character.Name)\r\nend)\r\n```\r\n\r\nProjectile signals are typed as well:\r\n\r\n```lua\r\nProjectile.Triggered:Connect(function(Character)\r\n\t-- Character is inferred as Model\r\n\tprint(Character.Name)\r\nend)\r\n\r\nProjectile.Ended:Connect(function(Reason)\r\n\t-- Reason is inferred as string\r\n\tprint(Reason)\r\nend)\r\n```\r\n\r\nHitboxPlus bundles its internal utilities directly, so no additional Wally packages or type-patching tools are required.\r\n\r\nIf your editor reports an unknown Wally require after installing or updating packages, make sure Luau LSP sourcemap generation is enabled for your Rojo project.\r\n\r\n## Example\r\n\r\n```lua\r\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\r\n\r\nlocal HitboxPlus = require(ReplicatedStorage.Packages.HitboxPlus)\r\n\r\nlocal Hitbox = HitboxPlus.new(HitboxPlus.HitboxPlusInfo.new({\r\n\tTarget = workspace.HitboxPart,\r\n\r\n\tDetectionTarget = \"Humanoid\",\r\n\tDetectionMode = \"InBox\",\r\n\r\n\tHitboxSize = Vector3.new(10, 5, 10),\r\n\r\n\tTriggerBehavior = \"OnEntry\",\r\n\r\n\tDebugging = true,\r\n}))\r\n\r\nHitbox.Triggered:Connect(function(Character)\r\n\tprint(Character.Name .. \" was hit!\")\r\nend)\r\n\r\nHitbox:Start()\r\n\r\ntask.delay(5, function()\r\n\tHitbox:Destroy()\r\nend)\r\n```\r\n\r\n## Bundled Utilities\r\n\r\nHitboxPlus includes the following utilities directly:\r\n\r\n- Signal from `Sleitnick/RbxUtil`\r\n- `t` from `osyrisrblx/t`\r\n\r\nThese are bundled with HitboxPlus, so they do not need to be added separately to your `wally.toml`.\r\n\r\nTheir original license notices are included in `THIRD_PARTY_LICENSES.md`.\r\n\r\n## License\r\n\r\nHitboxPlus is licensed under the MIT License.\r\n\r\nSee `LICENSE` for details.\r\n\r\nThird-party license notices can be found in `THIRD_PARTY_LICENSES.md`.","readmeTruncated":false}