Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add EL4CTEO/roblox-skills --skill roblox-physics -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/roblox-physics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/roblox-physics/

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.

roblox-physics gamedev-skills Claude Code skill for Roblox physics and spatial queries, managing assemblies, constraints, and network ownership. CX Codex +1 9,100installs roblox-physics TabooHarmony Guides Roblox physics setups for vehicles, ragdolls, constraints, network ownership, and projectiles while troubleshooting simulation glitches. CX Codex +1 3,200installs roblox-physics nonlooped roblox-physics guides agents on building and debugging Roblox assemblies, vehicles, mover constraints, and network ownership. CX Codex +1 521installs roblox-luau gamedev-skills This Claude Code skill helps write Roblox Luau and run project checks. It activates for a LocalScript that will not run, a client-side nil after joining, or legacy wait() calls. CX Codex +1 12,300installs roblox-datastores sentinelcore A Claude Code skill covering Roblox DataStoreService for player data persistence. Kicks in when a server script needs to save stats, load inventory, or build a leaderboard. CX Codex +1 680installs roblox-rojo nonlooped roblox-rojo sets up Rojo 7 to sync local filesystem code with Roblox Studio, build place files, and export places back to disk. CX Codex +1 519installs roblox-luau-types TabooHarmony roblox-luau-types — a skill for Luau type annotations: generics, unions, narrowing, strict mode, module type exports. Useful when migrating to --!strict. CX Codex +1 3,400installs scenario-roblox-tooling scenario-labs scenario-roblox-tooling — a skill for Claude Code that sets up Roblox build pipelines, synchronizes code, and runs tests outside Studio. CX Codex +1 350installs roblox-ui gamedev-skills roblox-ui — a Claude Code skill for building Roblox interfaces that scale across phones and handle gamepads. CX Codex +1 9,900installs

From the same set22

The whole set →
roblox-testing The roblox-testing Claude Code skill covers testing Roblox code and checking gameplay changes. It applies when adding tests, configuring a runner, or setting up CI. CX Codex +1 1,300installs roblox-open-cloud This Claude Code skill covers Roblox Open Cloud APIs and HttpService. It applies to external tools, bots, CI/CD, and web requests from a game. CX Codex +1 1,200installs roblox-text-chat roblox-text-chat is a Claude Code and Cursor skill that configures TextChatService and text filtering in Roblox for adding chat, commands, or player-authored signs. CX Codex +1 1,200installs roblox-monetization This Claude Code skill covers Roblox monetization and purchase troubleshooting. It activates for work on shops, passes, subscriptions, rewarded ads, or paid random items. CX Codex +1 1,200installs roblox-npc-ai The roblox-npc-ai Claude Code skill helps build AI for Roblox enemies, pets, and other NPCs. It covers pathfinding, chasing, attacks, and fixes for NPCs that get stuck or jitter. CX Codex +1 1,200installs roblox-teleport-matchmaking roblox-teleport-matchmaking — a skill for Claude Code handles player teleports and matchmaking flows in Roblox via TeleportService. CX Codex +1 1,200installs roblox-input roblox-input — a Claude Code skill for Roblox player controls and cameras. It comes into play when adding keybinds, abilities, vehicle controls, touch buttons, or a custom camera. CX Codex +1 1,200installs roblox-analytics-liveops roblox-analytics-liveops — a skill for Claude Code sets up game analytics, funnels, economy, and live ops for Roblox. Runs when instrumenting gameplay, economy tuning, or setting up A/B tests. CX Codex +1 1,200installs

Project sponsors

Companies that keep this analytics open