{"id":"nsawill1405/hitbox-plus","name":"hitbox-plus","scope":"nsawill1405","platform":"roblox","description":"Spatial query-based hitbox system with lag compensation hooks and hit validation helpers.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":["The package archive does not include its license text; the license is declared in its manifest metadata."],"licenseVerified":false,"dependencies":{},"integrity":"8f1e06708901482a27d0cd8ba27d254414b513c8e3c637362318a22f1530efb6","likes":0,"downloads":0,"install":"forest install nsawill1405/hitbox-plus","url":"https://forest.dev/p/roblox/nsawill1405/hitbox-plus","files":"https://api.forest.dev/ai/package/roblox/nsawill1405/hitbox-plus/files","readme":"# Hitbox Plus\n\nHitbox Plus is a Wally-first Roblox community library for spatial query-based hit detection with snapshot-backed lag compensation hooks and built-in hit validation helpers.\n\n## Features\n\n- `HitboxPlus.Server.create(config)` for authoritative hit resolution\n- `HitboxPlus.Client.create(config)` for client request building, prediction hooks, and debug traces\n- box, radius, and cast-oriented query support\n- snapshot history and rewind lookup for lag compensation\n- default validation rules for latency, team checks, max distance, duplicate attacks, cooldowns, and optional line-of-sight\n- structured hit/rejection results for gameplay code and debugging\n\n## Install\n\n```toml\n[dependencies]\nHitboxPlus = \"nsawill1405/hitbox-plus@0.1.0\"\n```\n\n## Quick Start\n\n```luau\nlocal Packages = game:GetService('ReplicatedStorage'):WaitForChild('Packages')\nlocal HitboxPlus = require(Packages:WaitForChild('HitboxPlus'))\n\nlocal server = HitboxPlus.Server.create({\n\thistory = {\n\t\tretentionSeconds = 0.25,\n\t},\n\tvalidation = {\n\t\tmaxLatencySeconds = 0.2,\n\t\tmaxDistance = 14,\n\t},\n})\n\nserver:pushSnapshot({\n\ttimestamp = 12.0,\n\tentities = {\n\t\t{ id = 'enemy-a', position = Vector3.new(4, 0, 0), radius = 2, team = 'Red' },\n\t},\n})\n\nlocal client = HitboxPlus.Client.create({})\nlocal request = client:buildRequest({\n\tattackId = 'slash-1',\n\tattackerId = 'player-a',\n\tattackerPosition = Vector3.new(0, 0, 0),\n\tattackerTeam = 'Blue',\n\tquery = {\n\t\ttype = 'radius',\n\t\tposition = Vector3.new(0, 0, 0),\n\t\tradius = 6,\n\t},\n})\n\nlocal result = server:resolve(request)\nfor _, hit in result.hits do\n\tprint('accepted', hit.id)\nend\n```\n\n## Config Notes\n\n- `history.retentionSeconds`: how long snapshots remain available for rewind lookup\n- `validation.maxLatencySeconds`: rejects requests that arrive too far past their client timestamp\n- `validation.maxDistance`: caps how far away accepted targets can be from the attacker\n- `validation.allowFriendlyFire`: allows same-team hits when set to `true`\n- `validation.duplicateWindowSeconds`: rejects repeated `attackId` values inside the configured window\n- `validation.targetCooldownSeconds`: rejects rapid repeat hits on the same target for the same attacker\n- `validation.lineOfSight`: checks `snapshot.occluders` against the attacker-to-target segment\n\n## Extending\n\n- Replace query backends by passing `queryBackends = { box = fn, radius = fn, cast = fn }` into `HitboxPlus.Server.create`.\n- Replace history storage by passing `historyStore` into `HitboxPlus.Server.create`.\n- Replace the default validator state machine by passing `validators` into `HitboxPlus.Server.create`.\n- Supply `predictor` or `debug.sink` in `HitboxPlus.Client.create` for client-side hooks.\n\n## Studio Sandbox\n\n- `examples/SandboxServer.luau` is the source of truth for the server sandbox flow, including sandbox dummy setup, one auto-run attack, and the `TriggerAttack` retrigger path.\n- `examples/SandboxClient.luau` is the source of truth for local debug rendering and the `F` key retrigger input.\n- The Studio mirror should install those scripts at `game.ServerScriptService.HitboxPlusSandbox` and `game.StarterPlayer.StarterPlayerScripts.HitboxPlusClientExample`.\n- The matching remotes live under `game.ReplicatedStorage.HitboxPlusSandboxRemotes` with `DebugPayload` and `TriggerAttack`.\n\n## Local Development\n\n```bash\naftman install\nlune run test/run.luau\nstylua src test examples\nselene src test examples\n```\n","readmeTruncated":false}