roblox-physics · el4cteo — Claude Code skill: what it does, how to install
The roblox-physics skill for Claude Code manages physics simulations and spatial queries. Use it when setting up raycasts, collisions, and vehicle mechanics.
MIT 1,200 installs ★ 131 updated 2026-11-03
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a claude-codeWhat roblox-physics does
The agent applies this skill when writing Luau code for raycasting, overlap queries, collision groups, and impact detection in Roblox. It covers workspace:Raycast, Spherecast, Blockcast, and BindToCollisionSummaries as a replacement for the Touched event. The instructions detail assembly management, mechanical constraints, network ownership, and CFrame math.
Spatial queries handle hit detection and zone checks reliably without the overhead or spoofing risks of Touched. Filtering relies on reusable RaycastParams and OverlapParams objects.
Client queries only inspect streamed-in parts, while authoritative checks run on the server. Mesh parts use specific CollisionFidelity settings to balance performance and precision.
What it helps with
- cast rays and swept volumes with Raycast and Shapecasts
- configure collision groups and filtering rules
- manage assemblies, welds, and mechanical constraints
- track impact points and relative velocities on collision
Example prompts for the agent
- Calculate raycasts and spatial queries using roblox-physics
- Set up collision groups for players and ghosts
- Optimize vehicle physics and collision summaries
How to install roblox-physics
1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a claude-code2Manually: put the files in place
~/.claude/skills/roblox-physics/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/roblox-physics/
1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a codex2Manually: put the files in place
.agents/skills/roblox-physics/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a cursor2Manually: put the files in place
.cursor/skills/roblox-physics/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install EL4CTEO/roblox-skills skills/roblox-physics2Manually: put the files in place
.github/skills/roblox-physics/SKILL.md1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a gemini-cli2Platform CLI
gemini skills install https://github.com/EL4CTEO/roblox-skills --path skills/roblox-physicsManually: put the files in place
.devin/skills/roblox-physics/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -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 roblox-physics
How to install roblox-physics in Claude Code?
Run npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a claude-code, then reference ~/.claude/skills/roblox-physics/SKILL.md.
What does roblox-physics do?
It provides AI coding guidance for Roblox physics, covering spatial queries, collision summaries, constraints, and network ownership.
Why avoid Touched for gameplay decisions?
The skill recommends spatial queries and BindToCollisionSummaries because Touched fires from the physics engine and can be spoofed or suppressed by clients.
Source text
SKILL.md · MIT
---
name: roblox-physics
description: Physics and spatial queries - Raycast/Blockcast/Spherecast, overlap queries, collision groups, Touched pitfalls, collision summaries (impact point/normal/speed), assemblies and welds, mover constraints replacing BodyMovers, mechanical constraints, network ownership, CFrame math, vehicles/projectiles, and server authority (BindToSimulation, prediction, rollback). Use when moving parts, detecting hits, building vehicles or projectiles, or fixing jitter, flinging, or ownership bugs.
---
# Roblox physics and spatial queries
## Spatial queries (use these, not Touched, for gameplay decisions)
```luau
--!strict
local params = RaycastParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {} -- e.g. { character } of the shooter
params.IgnoreWater = true
local function castRay(origin: Vector3, direction: Vector3): RaycastResult?
-- direction's length is the max distance
return workspace:Raycast(origin, direction, params)
end
local result = castRay(Vector3.new(0, 50, 0), Vector3.new(0, -100, 0))
if result then
print(result.Instance, result.Position, result.Normal, result.Material, result.Distance)
end
-- Swept volumes: thick bullets, melee arcs, ground checks with width.
local sphereHit = workspace:Spherecast(Vector3.new(0, 10, 0), 2, Vector3.new(0, 0, 50), params)
local boxHit = workspace:Blockcast(CFrame.new(0, 10, 0), Vector3.new(4, 4, 4), Vector3.new(0, 0, 50), params)
-- Volume overlap: explosions, hitboxes, zone checks.
local overlap = OverlapParams.new()
overlap.FilterType = Enum.RaycastFilterType.Exclude
overlap.MaxParts = 50
local partsInBox = workspace:GetPartBoundsInBox(CFrame.new(0, 5, 0), Vector3.new(10, 10, 10), overlap)
local partsInSphere = workspace:GetPartBoundsInRadius(Vector3.zero, 15, overlap)
print(sphereHit, boxHit, #partsInBox, #partsInSphere)
```
- **Reuse** params objects; update `FilterDescendantsInstances` (or `params:AddToFilter(instance)`) instead
of allocating per call.
- Newer filters: `params.ExcludeInstances` / `IncludeInstances` (can be combined; exclude wins) supersede
`FilterType` + `FilterDescendantsInstances` for new code.
- `RespectCanCollide = true` to ignore non-collidable parts; `CollisionGroup = "Name"` to query as a group.
- Shapecasts (October 2026): `params.Margin` inflates/rounds the cast shape (a `Raycast` with a margin acts
as a spherecast — use a thin one where rays slip through seams); `params.SizeGradient` grows/shrinks it
along the cast (`0.5` ends 50% larger, `-1` shrinks to nothing) for cones and funnels;
`workspace:Shapecast(part, direction, params, cframeOverride?, sizeOverride?)` casts a part from any
pose/size without moving it (placement previews). Debug: Studio Visualization Modes → Physics → Shapecasts.
- `GetPartsInPart(part, params)` does exact geometry overlap (costlier); `GetPartBoundsIn*` use bounding boxes.
- Deprecated: `FindPartOnRay*`, `Ray.new`, `FindPartsInRegion3*` → use the APIs above.
- Client queries only see streamed-in parts; authoritative checks run on the server.
## Touched: know its limits
`Touched` fires from the physics engine, only for parts that physically contact, is fired by whoever
simulates the part (clients can spoof or suppress it for parts they own), and can fire many times per
contact. Use it for triggers (pads, pickups) with a debounce and server-side validation; use spatial
queries for hit detection and zones.
```luau
--!strict
local Players = game:GetService("Players")
local pad = Instance.new("Part")
pad.Anchored = true
pad.Parent = workspace
local recently: { [Player]: boolean } = {}
pad.Touched:Connect(function(hit)
local character = hit:FindFirstAncestorOfClass("Model")
local player = character and Players:GetPlayerFromCharacter(character)
if not player or recently[player] then
return
end
recently[player] = true
print(`{player.Name} stepped on the pad`)
task.delay(1, function()
recently[player] = nil
end)
end)
```
## Collision summaries (impact data)
For *how* parts hit (impact FX, impact audio, damage by impact speed), use
`BasePart:BindToCollisionSummaries(callback)` instead of `Touched`. Once per frame after the physics step,
the callback gets every contact of that part: `Part0` (the bound part), `Part1`, `Point`, `Normal` (points
away from `Part0`), `RelativeVelocity` (before the solver resolves the hit), `Area`, and `Time`.
- Fires only where the part is simulated (its network owner); nothing replicates. Send what others need
through your own remote, validated on the server.
- No summaries for `CanCollide = false` parts or between two sleeping parts; non-convex parts can produce
several summaries per pair. Cost scales with bound parts, not total collisions.
```luau
--!strict
local function bindImpacts(part: BasePart, onImpact: (point: Vector3, speed: number) -> ()): RBXScriptConnection
return part:BindToCollisionSummaries(function(summaries: { any })
for _, summary in summaries do
local speed = math.abs(summary.RelativeVelocity:Dot(summary.Normal)) -- head-on impact speed
if speed > 10 then
onImpact(summary.Point, speed)
end
end
end)
end
return bindImpacts
```
## Collision groups
```luau
--!strict
-- Collision group APIs now live on WorldRoot (workspace); the PhysicsService versions are superseded.
workspace:RegisterCollisionGroup("Players")
workspace:RegisterCollisionGroup("Ghosts")
workspace:CollisionGroupSetCollidable("Players", "Ghosts", false)
local ghost = Instance.new("Part")
ghost.CollisionGroup = "Ghosts" -- assign by name (CollisionGroupId/SetPartCollisionGroup are deprecated)
ghost.Parent = workspace
```
Register groups once at server start (max 32, see `workspace:GetMaxCollisionGroups()`). `CanCollide = false` removes all collisions;
`CanQuery = false` hides a part from raycasts; `CanTouch = false` disables `Touched` (saves CPU);
`NoCollisionConstraint` disables collision between two specific parts.
`MeshPart` collision shape: `CollisionFidelity` `Box`/`Hull` (cheap), `Default`, `PreciseConvexDecomposition`
(costly), or `Tunable` with a `CollisionPrecision` slider (set in Studio; scripts can't write it) to trade
precision for performance per mesh.
## Assemblies and joints
- An **assembly** = parts rigidly connected (welds, `WeldConstraint`, `Motor6D`, rigid constraints). It
simulates as one body; the root part (`part.AssemblyRootPart`) determines network ownership.
- Anchor static geometry. Unanchored + welded to an anchored part = anchored assembly.
- Weld at edit time with `WeldConstraint` (keeps current offset); in code set `Part0`/`Part1` and parent.
- Move whole models with `model:PivotTo(cframe)`. Moving many parts at once: `workspace:BulkMoveTo`.
- Read/set physics via `AssemblyLinearVelocity`/`AssemblyAngularVelocity`, `part:ApplyImpulse()`,
`ApplyAngularImpulse()`, `AssemblyMass`. `Velocity`/`RotVelocity` are deprecated.
- `CustomPhysicalProperties = PhysicalProperties.new(density, friction, elasticity, frictionWeight, elasticityWeight)`.
- Units: 1 stud ≈ 0.28 m, `workspace.Gravity` default 196.2 studs/s².
## Mover constraints (replace BodyMovers)
| Goal | Constraint | Replaces |
| --- | --- | --- |
| Hold/drive a velocity | `LinearVelocity` (`VelocityConstraintMode` Vector/Plane/Line) | `BodyVelocity` |
| Move toward a position | `AlignPosition` (`Mode = OneAttachment` + `Position`, `Responsiveness`, `MaxForce`) | `BodyPosition` |
| Rotate toward an orientation | `AlignOrientation` (`CFrame`/`LookAtPosition`) | `BodyGyro` |
| Constant force | `VectorForce` (`RelativeTo = World`) | `BodyForce`, `BodyThrust` |
| Spin | `AngularVelocity` | `BodyAngularVelocity` |
| Pull toward point | `LineForce` | `RocketPropulsion` |
| Torque | `Torque` | — |
All need an `Attachment` (`Attachment0`). Set `MaxForce`/`MaxTorque` realistically (not `math.huge`
unless intended) or objects fling. Mechanical constraints: `HingeConstraint` (Motor/Servo actuators for
wheels, doors), `PrismaticConstraint` (sliders, elevators), `SpringConstraint` (suspension),
`RopeConstraint`, `RodConstraint`, `BallSocketConstraint`, `CylindricalConstraint` (wheel + steering),
`UniversalConstraint`, `RigidConstraint`.
Vehicle and projectile recipes, CFrame cookbook: [references/recipes.md](references/recipes.md).
## Network ownership
- The server auto-assigns ownership of unanchored assemblies to a nearby client (smooth for that client,
exploitable by it). Characters are owned by their player.
- `part:SetNetworkOwner(nil)` = server simulates (secure, laggier for players); `SetNetworkOwner(player)`
for a vehicle driver; `SetNetworkOwnershipAuto()` to restore. Call on the root part, server-side, after
the assembly is in `Workspace`. Anchored parts have no owner.
- Ownership changes cause hitches; don't flip it every frame. Visualize with the viewport's
**Visualization options → Network owners** toggle.
## Server authority (competitive games)
Workspace `AuthorityMode = Server` makes the server simulate everything while clients **predict** a few
frames ahead and **roll back/resimulate** on mispredictions. Requirements: `NextGenerationReplication`,
`PlayerScriptsUseInputActionSystem`, `SignalBehavior = Deferred`, `UseFixedSimulation`, `StreamingEnabled`
(setting `AuthorityMode` sets these). Core rules:
- Game logic lives in functions bound with `RunService:BindToSimulation(fn)` inside a ModuleScript required
by both server and client.
- Clients affect the game only through **Input Actions** (InputContexts parented under the `Player`),
not `UserInputService` events.
- Sync custom state through **attributes** on predicted instances, written only inside simulation callbacks.
- Don't cache `AnimationTrack`s; query `Animator:GetTrackByAnimationId()` each step.
- Read a player's camera on the server with `player:GetCameraState()` (`CFrame`, `FieldOfView`,
`ViewportSize`); the old camera `InputAction` replication no longer syncs.
Fully released (opt-in) since July 2026. Details and patterns: [references/server-authority.md](references/server-authority.md).
## Stability tips
- Jitter: conflicting ownership, constraints fighting, huge mass ratios (> 1:100), or setting CFrame on
unanchored parts every frame (use constraints instead).
- Flinging: `MaxForce = math.huge` on light parts, overlapping collisions at spawn, NaN/huge velocities.
- Sleeping assemblies stop simulating until disturbed — wake with a small impulse if needed.
- Adaptive timestepping (`Workspace.PhysicsSteppingMethod = Adaptive`) saves CPU; use fixed for precise mechanisms.
## Related skills
`roblox-security` (ownership exploits), `roblox-characters-animation`, `roblox-networking`,
`roblox-performance`, `roblox-input`.
© EL4CTEO · MIT · EL4CTEO/roblox-skills
Similar skills
All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →roblox-physics by other authors comes first.