scenario-roblox-gameplay — Claude Code skill: install
The scenario-roblox-gameplay Claude Code skill covers Roblox gameplay systems, from NPC AI and combat to projectiles and vehicles. It activates for gameplay implementation and troubleshooting pathfinding, hit detection, or vehicle physics.
MIT 357 installs ★ 3,964 updated 2026-10-23
npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a claude-codeWhat scenario-roblox-gameplay does
The skill gives procedures for Roblox gameplay code, including NPC patrols and pursuit, server-side hit checks, projectiles, stuns, knockback, and vehicles with suspension. NPC guidance uses a shared scheduler and limits path computation to a budget.
The procedures include modules in scripts/agentkit/gameplay/ and the Python script scripts/rbx_gameplay.py. The scenario-roblox-expert skill and its toolkit are required; installation and checks use an open place in Roblox Studio, while Lune tests pure rules. The described test status does not include two-player combat, a touch device, or routes using pathfinding modifiers or links.
What it helps with
- build NPC logic for patrol and pursuit
- debug an NPC that gets stuck finding a path
- make the server validate combat hits
- add combos, stun, and knockback to combat
- configure vehicle suspension and network ownership
Example prompts for the agent
- Set up an NPC that patrols, spots a player, and gives chase.
- Find why hits on an enemy are registering twice.
- Build a car with suspension and check network ownership when the driver exits.
How to install scenario-roblox-gameplay
1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a claude-code2Manually: put the files in place
~/.claude/skills/scenario-roblox-gameplay/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/scenario-roblox-gameplay/
1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a codex2Manually: put the files in place
.agents/skills/scenario-roblox-gameplay/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a cursor2Manually: put the files in place
.cursor/skills/scenario-roblox-gameplay/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install scenario-labs/skills skills/game-engines/roblox/scenario-roblox-gameplay2Manually: put the files in place
.github/skills/scenario-roblox-gameplay/SKILL.md1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a gemini-cli2Platform CLI
gemini skills install https://github.com/scenario-labs/skills --path skills/game-engines/roblox/scenario-roblox-gameplayManually: put the files in place
.devin/skills/scenario-roblox-gameplay/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about scenario-roblox-gameplay
How do I install scenario-roblox-gameplay in Claude Code?
Run npx skills add scenario-labs/skills --skill scenario-roblox-gameplay -a claude-code. The skill file is available at ~/.claude/skills/scenario-roblox-gameplay/SKILL.md.
What does scenario-roblox-gameplay do?
It supports Roblox gameplay work, including NPC AI, combat, projectiles, and vehicles. Its procedures also cover server-side hit checks and testing.
What does scenario-roblox-gameplay need to work?
It requires the scenario-roblox-expert skill and toolkit. Roblox Studio is used for installation and checks, and Lune is used to test pure rules.
Source text
SKILL.md · MIT
--- name: scenario-roblox-gameplay description: "Use when building Roblox gameplay systems: NPC or enemy AI that patrols, chases and attacks, state machines or behavior trees, 'NPC pathfinding stuck', 100 zombies lag the server, hitboxes, melee combos, M1 combat, 'hits register twice', raycasts, Spherecast, Shapecast, guns and projectiles, 'bullets go through walls', knockback and stun, LinearVelocity, VectorForce or AlignPosition movers, replacing BodyVelocity, cars and vehicles with suspension, 'car flips', VehicleSeat, network ownership of NPCs and vehicles, round loops, BindToSimulation logic." license: MIT --- # Roblox gameplay systems (gameplay systems programmer) Target line: Roblox Studio (October 2026 build) on macOS, driven through the scenario-roblox-expert toolkit. At expert level, a gameplay system is a pure rule tested in Lune, wired to the engine by one server scheduler, and proven in a playtest with measured server cost. The core stance: the client sends intent, the server decides every hit with a spatial query, and no number ships unmeasured. If a sibling skill named here is missing from your available skills, load it with `skill_get` (Scenario MCP) or ask the user to install it (https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas and flag the gap. **REQUIRED BACKGROUND:** scenario-roblox-expert (channels, review loop, toolkit, current-Roblox traps). **Status (2026-10-19):** 23 live tests pass in Studio 0.743 (Edit probes, NPC bench, hunt, debug drawings, combo, remote flood, car and its exit with the throttle held, movers, every doc snippet in the playtest Server); 6 offline checks pass (23 Lune specs, luau-lsp on both type solvers over 15 kit files and 12 snippets). Not yet run: two-player combat (each test client opens a Studio window), a touch device, a route through a pathfinding modifier and link. ## Stance (the expert delta) 1. **Intent up, hits decided on the server.** The client fires `Attack` with no arguments; the server picks the combo step from its own clock and queries a box in front of the root. Spatial queries replace `Touched` (Ludius, gmz904QpfxU 00:01:15): a client-owned part can fire `Touched` on the server anywhere (Network ownership doc). Validation and rate limits: scenario-roblox-networking. 2. **Know what a query skips.** Spherecast, Blockcast and Shapecast ignore parts they start inside (veraktt, GtqFcyFgIXQ 00:19:33). Check the start with an overlap query. A Shapecast's final position is `origin + direction.Unit * Distance`; `Position` is the contact point (Crusherfire, EIOwGMZYidw 00:07:12). Use `ExcludeInstances` or `IncludeInstances`, never `FilterDescendantsInstances`, and build the list per shot (BrawlDev, u6I17z6ggUg 00:28:41). 3. **Sweep, then move; step by dt.** Cast the whole step before committing it (veraktt 00:12:22). Trapezoid displacement makes the path independent of frame rate (BrawlDev, 0Dt-Ab8czPw 00:33:08); measured in Lune: 30, 60 and 240 Hz agree within 0.001 studs, Euler drifts 0.5. 4. **One scheduler for every NPC, measured at the target count.** One Heartbeat thinks one bucket per frame, one worker computes paths on a budget, perception is distance first and one raycast against static geometry [added]. Measured with 100 R15 NPCs: server 60 fps, frame p95 17.6 ms, AI 0.14 ms per frame patrolling and 0.26 ms chasing; the physics step grew to 1.8 ms. Humanoid physics costs more than the brain, so measure at your count with the AgentKit `Stats`, and cut the per-Humanoid cost: unused states disabled, `BreakJointsOnDeath` false, no state machine on static NPCs, models pooled across waves ([P5](references/procedures.md)). 5. **Pin NPC roots to the server.** An unanchored NPC near a player is simulated, and movable, by that client (measured: an unpinned NPC 6 studs away belonged to the player); `SetNetworkOwner(nil)` after parenting (Network ownership doc). Purely decorative crowds can run as client Humanoids fed by one attribute per NPC every 5 s (Suphi Kaner, JyMxrcqEzu8 00:13:50). 6. **The brain is data with hysteresis.** States with `onEnter`, `onStay`, `onExit` and transitions as a list (Miller, Roblox Learn, nlVpAZEkxgo 00:00:57). Enter Attack at 5 studs, leave above 6.5, give up 4 s after losing sight [added]. Pathfinding success is `pcall` AND `Status == Success` (BrawlDev, ckA4fVkAjIA 00:15:48); recompute on `Blocked` only when the index is at or after the next waypoint (Pathfinding doc). Re-issue `MoveTo`, because it gives up after 8 s. Price routes in one `Costs` table (materials, `PathfindingModifier` and `PathfindingLink` labels) instead of special-case code; compute only on the ground, in a loaded world, under 3,000 studs; a failed move snaps to that waypoint, never the goal ([P12](references/procedures.md)). 7. **Stun cancels pending hits.** A hit victim's queued swing is dropped and its requests refused for a bounded stun (ArTheDev, Aoc9HkGHu_8 00:02:57). One hit per character per swing, never per limb (Ludius 00:04:06). Knock a Humanoid back with a `LinearVelocity` held 0.2 s: one `ApplyImpulse` moved a standing dummy 1.2 studs, the `LinearVelocity` 10.5 [measured]. 8. **Cars are constraints plus ownership.** Per wheel one CylindricalConstraint and one SpringConstraint on the same attachments, upper limit below 0 (Suphi Kaner, FVOowr2DXbM 00:10:19). The driver owns the car while seated (Network ownership doc) and the server keeps a speed check; competitive racing goes to Server Authority. Check the steer sign live: this kit's first build turned left on D. Keep the center of mass low: dense low chassis, light body, seat low and central (FVOowr2DXbM 00:54:05). On exit, release the motors, give loose parts the same owner, leave through the highest exit point ([P9, P14](references/procedures.md)). ## Establish first - NPC count, and whether NPCs deal or take damage (server) or only decorate (client crowd). - Hit model: melee box, hitscan ray, or projectile with travel time and drop (Weapons kit doc). - Competitive or casual: competitive movement and vehicles go to Server Authority (scenario-roblox-networking). - Platforms: phones are the most common device, so every combat action gets a key, a gamepad button and an on-screen touch button bound through `InputBinding.UIButton` ([P7](references/procedures.md)). Defaults when unanswered: NPCs on the server, 6 buckets, 30 paths per second; melee box 5 by 5 by 5 studs at 3.5 studs; a 0.25-stud sphere sweep for projectiles; the car numbers below. ## Procedure Full code and test results: [procedures.md](references/procedures.md). Modules: [scripts/agentkit/gameplay/](scripts/agentkit/gameplay/); Python: [scripts/rbx_gameplay.py](scripts/rbx_gameplay.py). 1. **Install.** Goal: kit, boot scripts and Input Action instances in the open place. How: `rbx_gameplay.install(studio)` writes `Source` in Edit (P1). GATE: the playtest Server sees the hook and remotes; the Client sees `GameplayInputs.Combat.Attack`; no boot error in the console. 2. **Probe the queries.** Goal: facts for this build. How: the Edit probes (P2). GATE: Spherecast from inside returns the far part; Shapecast distance within 0.05 studs of the expected travel. 3. **Brain in Lune.** Goal: a readable, tested decision table. How: `StateMachine` plus `NpcBrain` (P4). GATE: `lune run lune_unit.luau` passes. 4. **Crowd and cost.** Goal: a known server cost. How: `NpcService` and the bench (P5). GATE: 0 of 100 roots client-owned; server fps and p95 recorded at each count; budget agreed with scenario-roblox-performance. 5. **Hunt.** Goal: perception, path and melee together. How: `walk_to` drives the player in sight, then behind a wall (P6); path failure rules and route pricing (P12). GATE: the NPC reaches the player behind the wall and lands a hit; capture. 6. **Combat.** Goal: a combo that resists spam and stun. How: Input Action, intent remote, `Combo` and `Hitbox.box` (P7); projectiles with `Projectile` (P8). GATE: two front dummies at 58 health, the one behind untouched; under spam, no accepted swing closer than 0.24 s to the previous one; a 0.2-stud wall stops every projectile. `user_keyboard_input` delivers presses 0.13 to 0.20 s apart whatever the waits: flood tests fire the remote from a client script (P7). 7. **Vehicle.** Goal: drives, steers, stays upright. How: `Car.build`, `Car.serve`, `Car.controller` (P9). GATE: driver owns the chassis; W for 3 s moves it forward more than 30 studs; W plus D turns right more than 20 degrees; `UpVector.Y` stays above 0.8; ownership returns to automatic on exit; leaving with the throttle held stops the car (P14); capture before and after. 8. **Audit and review.** How: `GameplayAudit` plus the lead's `Audit` (P3), the [critique](references/critique.md), one contact sheet. GATE: 0 errors. ## Numbers | Value | Default | Relative to | | --------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Think rate | 10 per NPC per second | 6 buckets at 60 fps | | Path budget | 30 per second | whole server | | Detect, attack, leave range | 60, 5, 6.5 studs | target root; chase range 1.5 times detect | | Lose sight | 4 s | last time seen | | Humanoid `MoveTo` timeout | 8 s | re-issue every think | | Path limits | 3,000 studs, 20,000 nodes; both fail as a bad `Status` | start to goal (P12) | | Route costs | 1 default, 20 to 1,000 last resort, `math.huge` never | `Costs` keys: materials, modifier and link labels (P12) | | Touch button | 72 px, bottom right, clear of jump | shown only while `PreferredInput` is Touch; layout check: scenario-roblox-ui (P7) | | Combo damage | 10, 12, 20 | steps 1 to 3 | | Combo gaps | 0.30, 0.30, 0.45 s with 0.8 tolerance | previous accepted swing | | Finisher knockback | `LinearVelocity` 45 studs/s for 0.2 s, `MaxForce` mass times gravity times 20 | away from the attacker | | Chain window, finisher lock, stun | 0.9, 0.6, 0.35 s | last swing or hit | | Cast reach | 1,024 studs (shape casts), 15,000 (ray) | per call | | Suspension | Stiffness 3500, Damping 200, FreeLength 2.8 | Suphi Kaner | | Slide limits | upper -1, lower -2 | along Attachment0 X (up) | | Drive | `MaxSpeed / radius`, torque 5000, idle 2000 | rear wheels | | Steer | 30 degrees over 0.4 s | front body attachments | | Car speed check | 1.5 times `MaxSpeed`, twice in 1 s | server, while a driver owns it | | 100 NPCs, measured | 60 fps, p95 17.6 ms, heartbeat 0.27 ms, physics 1.8 ms, 21.5 kbps sent | patrolling, server, Studio 0.743 | | One path, measured | 65 ms wall time (yields), 0 failures | `ComputeAsync`, open baseplate | | Casts, measured | Spherecast 0.46, Raycast 0.30 microseconds | 50 studs, small include list | | Car, measured | 177.9 studs in 3 s, top 51.0 studs/s; 112 degrees in 2.5 s | W, then W plus D | ## Quality gates - Measurable: Lune specs; `rbx_check` 0 errors; `GameplayAudit` 0 errors; `NpcService.stats()` (states, client-owned roots, AI ms, paths); AgentKit `Stats` in the Server; dummy health and hit counts; car samples (distance, heading, `UpVector.Y`). - Visual: captures of the crowd, the hunt behind the wall, dummies after the finisher, the car before and after a drive, read through `rbx_review.contact_sheet` (1,600 px or less). Turn on Navigation mesh or Network owners in Visualization Options, and draw waypoints and query boxes with `DebugDraw` adornments, depth-tested so captures show them (P13). - Key tests record client input and rerun when it differs from the keys sent (P7). ## Common mistakes | Mistake | Symptom | Fix | | --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------- | | `Touched` deals damage | hits through walls, exploit damage | box query on the server | | One result per limb | 3 to 5 hits per swing | key results by character model | | Projectile starts inside a wall | shot passes through | overlap query before the first sweep | | Teleport by `Position` per frame | tunneling at speed | sweep, then move | | `FilterDescendantsInstances` | superseded API in new code | `ExcludeInstances`, `IncludeInstances` | | Debug parts queryable | casts stop at your own markers | `CanQuery` false (Crusherfire 00:10:42) | | `MoveToFinished:Wait()` | NPC freezes after 8 s | re-issue `MoveTo`; handle `reached == false` | | Path computed mid-air or before the map loads | bad `Status`, NPC stands still | wait for `FloorMaterial`, gate on load (P12) | | Snap to the goal after a failed move | NPCs pop through walls | snap to that waypoint (P12) | | Hazards avoided in code | brittle special cases | modifier label priced in `Costs` (P12) | | Every Humanoid fully enabled | physics step grows per NPC | trim states, pool, no state machine when static (P5) | | `ComputeAsync` without `pcall` | script dies on a bad path | `pcall` plus `Status` | | NPC root unpinned | the nearest client moves NPCs | `SetNetworkOwner(nil)` | | One loop per NPC | cost grows with scripts | one scheduler, buckets | | BodyVelocity | deprecated mover | LinearVelocity, VectorForce, AlignPosition | | Constraint without `Attachment0` | nothing moves, no error | GameplayAudit `constraint-no-attachment` | | Suspension upper limit 0 | spring bottoms out, car bounces | upper -1 | | Reading `Throttle` | no analog gamepad or touch | `ThrottleFloat`, `SteerFloat` | | Passenger owns the car | lag for the driver | reassign on `Occupant` change | | One fixed exit side | a flipped car drops the player under the map | highest exit point (P14) | | Motor values left on exit | the empty car drives on | release the motors on exit (P14) | | Keyboard-only combat | phones cannot attack | touch `UIButton` binding (P7) | ## Handoffs - Receives from scenario-roblox-architecture: the RoundMachine round loop, the Binder for tagged weapons and hazards, the DamageService slot. - Delivers to scenario-roblox-networking: hitbox, projectile and ability rules to validate (`HitCheck` with rewind), the car speed flag for the suspicion score, Server Authority settings. - Delivers to scenario-roblox-animation: NPC `State` and `Action` attributes and combo steps to drive tracks; under Server Authority, no cached tracks. - Delivers to scenario-roblox-vfx-audio: hit position, normal and step for impact effects. - Delivers to scenario-roblox-ui: the `GameplayInputs` contexts and actions for prompts and remapping. - Delivers to scenario-roblox-performance: the NPC bench numbers and budgets. - Shares with scenario-roblox-luau: fixed-step code (`BindToSimulation`) and Deferred event rules. ## Current Roblox notes - `RaycastParams` and `OverlapParams`: `ExcludeInstances` and `IncludeInstances` supersede `FilterDescendantsInstances` and `FilterType` (2026-04-07). `RaycastParams.Margin` and `SizeGradient` are in the reference, but setting either raises "not enabled yet" in 0.743 (P2): keep `Spherecast` for thick rays. - Collision groups live on `workspace` (`RegisterCollisionGroup`, `CollisionGroupSetCollidable`); the `PhysicsService` methods are deprecated. - `PathfindingService:CreatePath` plus `Path:ComputeAsync`; `FindPathAsync` and `ComputeRawPathAsync` are deprecated. PathfindingModifier and PathfindingLink need no beta. - `RunService:BindToSimulation` is documented as needing `Workspace.UseFixedSimulation`. In 0.743 it ran in Edit and Play on a place that never set it (P11); scripts cannot read the property from the Studio MCP context, so set it explicitly in the Rojo project. - Creator Store models are sandboxed (2026-05-13): vendor libraries such as FastCast as source. ## References - [references/expert-notes.md](references/expert-notes.md): principles by expert, with timestamps. - [references/procedures.md](references/procedures.md): P1 to P14 with full code and test results. - [references/critique.md](references/critique.md): the self-review rubric. - [references/gui-paths.md](references/gui-paths.md): Studio menus and the scripted substitutes. - [references/sources.md](references/sources.md): every source and the live measurement setup. - [scripts/rbx_gameplay.py](scripts/rbx_gameplay.py): install, fixtures, hook, keyboard sequences, audits. - [scripts/agentkit/gameplay/](scripts/agentkit/gameplay/): the Luau modules and Lune runners.
© scenario-labs · MIT · scenario-labs/skills