{"id":"chroma-hade/hitbox","name":"hitbox","scope":"chroma-hade","platform":"roblox","description":"Hitboxes for Lunora. Run them on the server, or on the attacker's client with the server checking every hit.","version":"1.0.2","latest":"1.0.2","versions":["1.0.0","1.0.1","1.0.2"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"chroma-hade/lunora":{"version":"^1.0.3","alias":"Lunora"}},"integrity":"b19099c13a5fda1a055ec811a1a027e3896507768228384d746301b2cb4ac2f3","likes":0,"downloads":0,"install":"forest install chroma-hade/hitbox","url":"https://forest.dev/p/roblox/chroma-hade/hitbox","files":"https://api.forest.dev/ai/package/roblox/chroma-hade/hitbox/files","readme":"# Hitbox\n\nHitboxes for [Lunora](https://github.com/chroma-hade/Lunora)! Run them on the server, or on the attacker's client with the server checking every hit.\n\nServer hitboxes are the plain kind: the server looks for overlaps every frame. Client hitboxes let the attacker's own screen decide what got hit, so hits feel instant, and the server checks each report so nobody lands a punch from across the map. Set `IsClient = true` on a player's hitbox to get the client kind. NPCs always run on the server.\n\n## Getting it\n\nYou need Lunora at `ReplicatedStorage.Packages.Lunora`.\n\nGrab `Hitbox.rbxm` from the [releases page](https://github.com/chroma-hade/Hitbox/releases) and put it in `ReplicatedStorage.Packages` too.\n\nIf you use Wally, add both to your `wally.toml`:\n\n```toml\n[dependencies]\nLunora = \"chroma-hade/lunora@1.0.3\"\nHitbox = \"chroma-hade/hitbox@1.0.2\"\n```\n\n## Setting it up\n\nHitbox comes with a service and a controller. Hand them to Lunora next to your own modules.\n\n```lua\n-- server\nLunora.AddModules(ReplicatedStorage.Packages.Hitbox.Server)\nLunora.AddModules(ServerStorage.Services)\n\nLunora.Start()\n```\n\n```lua\n-- client\nLunora.AddModules(ReplicatedStorage.Packages.Hitbox.Client)\nLunora.AddModules(script.Parent.Controllers)\n\nLunora.Start()\n```\n\nWith Wally, `Packages.Hitbox` is just a link, so the folders sit in `_Index` instead:\n\n```lua\nlocal HitboxFolder = ReplicatedStorage.Packages._Index[\"chroma-hade_hitbox@1.0.2\"].hitbox\nLunora.AddModules(HitboxFolder.Server)\n```\n\n## Using it\n\n```lua\nlocal Hitbox = require(ReplicatedStorage.Packages.Hitbox)\n\nlocal Punch = Hitbox.new({\n    User = Character,\n    Size = Vector3.new(6, 5, 6),\n    PlaceData = { Offset = CFrame.new(0, 0, -3), Linger = true },\n    LifeTime = 0.1,\n    IsClient = true,\n})\n\nPunch:OnHit(function(Victim)\n    Victim.Humanoid:TakeDamage(10)\nend)\n```\n\nEach victim gets hit once per hitbox. Anything with a `Humanoid` counts as a victim.\n\n- `Size` is a `Vector3` for a box, or a number for a ball (that's the diameter).\n- `PlaceData.Offset` places it in front of the user's `HumanoidRootPart`, and `Linger` keeps it following them. Use `PlaceData.CFrame` instead for a fixed spot.\n- Leave out `LifeTime` and it stays until you call `Punch:Destroy()`.\n\n## Your rules\n\nHitbox doesn't know what blocking or ragdolls mean in your game, so you tell it. Set these once, in some module's `Init`.\n\n```lua\nHitbox.SetResolver(function(Data, Victim, HitboxCFrame)\n    if Victim:GetAttribute(\"Blocking\") and Data.Blockable then\n        return \"Blocked\"\n    end\n    return \"Hit\"\nend)\n\nHitbox.SetFilter({ workspace.Characters })\n```\n\n`Data` is the exact table you passed to `Hitbox.new`, so you can stick your own fields in there, like `Blockable` above. Return `\"Hit\"`, `\"Blocked\"` or `\"Ignore\"`. `\"Blocked\"` runs `:OnBlocked` instead of `:OnHit`, and `\"Ignore\"` lets the victim get hit later in the same swing.\n\n`SetFilter` limits hitboxes to those folders. Leave it out and everything counts.\n\n## How the server checks\n\nThe client tells the server who it hit and where the attacker was standing. The server only believes that spot if the attacker could have gotten there in time, based on their `WalkSpeed` and the ping. Nobody gets to swing from a spot they couldn't have walked to!\n\nIf your game moves characters some other way, like a dash, tell Hitbox how fast:\n\n```lua\nHitbox.SetSpeedProvider(function(Character)\n    return Character:GetAttribute(\"DashSpeed\") or 0\nend)\n```\n\nReports that still don't add up wait a moment to see if the server catches up, then get thrown out☆\n\n## Seeing them\n\nSet a `VisualHitbox` attribute to `true` on `ReplicatedStorage`. Client hitboxes show up blue, server ones red.\n\n## Everything\n\n| | |\n|---|---|\n| `Hitbox.new(Data)` | Makes a hitbox and starts it |\n| `hitbox:OnHit(Function)` | Runs for each victim that got hit |\n| `hitbox:OnBlocked(Function)` | Runs for each victim your resolver blocked |\n| `hitbox:ResetVictims()` | Lets everyone it already hit get hit again |\n| `hitbox:Destroy()` | Stops it early |\n| `Hitbox.SetResolver(Function)` | Decides hit, blocked or ignored |\n| `Hitbox.SetFilter(Folders)` | Only check inside these folders |\n| `Hitbox.SetSpeedProvider(Function)` | Extra speed a character can have, on top of `WalkSpeed` |\n\n## License\n\nMIT, so go wild☆ Just keep the license file around.\n","readmeTruncated":false}