Index of every page on this site: llms.txt
All skills
Run it yourself

Roblox physics and spatial queries: assemblies, constraints, collision groups, Raycast and Shapecast, and network ownership. Use when parts fall through or jitter, Touched is unreliable, a ray hits the shooter, or BodyMovers need replacing. Not for hit legitimacy (`roblox-networking`), Humanoid movement (`roblox-characters`) or engine-neutral tuning (`physics-tuning`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/roblox-physics

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈97 tokens for metadata: the name and description. ≈2.1k when used: this file. ≈908 more on demand in 2 files.

Description uses 4.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈388 characters, or 4.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Roblox physics

Simulation, character control, hit detection and visual-only motion are different jobs. Pick the mechanism first, then the API. Whether a hit counts is a server validation decision owned by roblox-networking; this skill supplies the queries it uses.

Decide the mechanism

Goal Mechanism
sustained physical interaction unanchored assembly plus modern constraints or forces
one-off physical change ApplyImpulse / ApplyAngularImpulse
kinematic platform or path scripted pivot or CFrame with an explicit passenger policy
character locomotion Humanoid or Character Controller Library (roblox-characters)
hit test server raycast, shapecast, or overlap with explicit filters
cosmetic trail or recoil local visual motion; no gameplay authority

Workflow

  1. Inspect the mechanism. In Studio, turn on the assembly, constraint and network-owner visualizations; or read part.AssemblyRootPart, part.AssemblyMass, part.Anchored and part:GetNetworkOwner() from code. Identify the assembly root and who should own it.
  2. Write the interaction policy. A collision-group matrix, then CanCollide, CanTouch and CanQuery decided separately per role. Register groups once with Workspace:RegisterCollisionGroup() and CollisionGroupSetCollidable() (or the Collision Groups editor), from a single script so assignment never races registration.
  3. Choose simulation or query. A ray for a line, a shapecast for a moving volume, an overlap for a static volume, and simulation contacts only when a physical response is wanted. .Touched is neither reliable nor secure as a hit detector.
  4. Apply motion at assembly level. Forces on any part act on the whole assembly. Use LinearVelocity, AngularVelocity, VectorForce, AlignPosition and AlignOrientation; migrate BodyMovers when you touch that system.
  5. Set ownership deliberately. Server-own gameplay-critical loose assemblies when needed; client ownership improves response but never authorizes results.
  6. Bound cost and lifetime. Reuse query params, cap query frequency and result counts, and destroy temporary constraints, attachments and connections together.
  7. Check from code. With the Studio MCP server connected, start play and use execute_luau on the Server datamodel to print the facts the change depends on: AssemblyRootPart, AssemblyMass, GetNetworkOwner(), workspace:CollisionGroupsAreCollidable(a, b), and the result of one test query; then read get_console_output. Without MCP, ask the user to run the same snippet from the Command Bar during play and paste the Output. Fast movers, ownership hand-off and two-client interaction need a Server & Clients run.

Pattern: filtered server raycast

local Workspace = game:GetService("Workspace")

local params = RaycastParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {shooterCharacter}
params.IgnoreWater = true
params.CollisionGroup = "WeaponQuery"

local direction = aimDirection.Unit * MAX_RANGE   -- direction length is the range
local result = Workspace:Raycast(muzzlePosition, direction, params)
if result then
    local model = result.Instance:FindFirstAncestorOfClass("Model")
    local humanoid = model and model:FindFirstChildOfClass("Humanoid")
    if humanoid and serverCanDamage(shooter, model, result.Position) then
        humanoid:TakeDamage(serverWeaponDamage(shooter))
    end
end

muzzlePosition and aimDirection must come from server-known character and weapon state. A raycast from a client-supplied origin is not validation (see roblox-networking).

Pattern: overlap volume with explicit policy

local params = OverlapParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {sourceCharacter}
params.CollisionGroup = "DamageQuery"
params.MaxParts = 64

local seen: {[Model]: boolean} = {}
for _, part in Workspace:GetPartBoundsInBox(hitboxCFrame, hitboxSize, params) do
    local model = part:FindFirstAncestorOfClass("Model")
    if model and not seen[model] then
        seen[model] = true
        validateAndApplyHit(model)
    end
end

Bounds queries test bounding boxes and return several parts per target, so deduplicate by model. WorldRoot:GetPartsInPart() is exact but costs more. OverlapParams.RespectCanCollide switches the query from CanQuery to CanCollide; set it on purpose or it silently overrides the flag policy.

Assemblies, force, and ownership

  • Welded parts form one rigid assembly; force, impulse, velocity, mass and ownership act on the assembly. One anchored part anchors the whole assembly.
  • Tune forces and impulses from intended acceleration times AssemblyMass, not by trial values.
  • Automatic ownership moves nearby unanchored assemblies to clients. Call SetNetworkOwner(nil) for critical objects, then measure the server cost and responsiveness. Re-check ownership after anchoring changes; it is not always kept.
  • A client owner can fake physical results and .Touched events. The server validates consequential hits, positions, timing and permissions independently.
  • If Workspace.AuthorityMode is Server, the server owns simulation and clients predict nearby assemblies with rollback. Drive predicted forces and constraints from RunService:BindToSimulation() on both sides, not from Heartbeat or client-only scripts, and expect custom physics scripts to need changes when a place switches modes.

Gotchas

Symptom Likely cause Remedy
welded mechanism will not move one part anchored inspect the whole assembly; anchor only world roots
force too strong or too weak assembly mass ignored read AssemblyMass; size force for the intended acceleration
fast projectile misses discrete contact sampling swept query (Blockcast, Spherecast, Shapecast) per step; see physics-tuning
ray hits the shooter or effects no filter or query group reuse explicit params and a query collision group
one target damaged many times overlap returned several body parts deduplicate by model; attack ID or cooldown
exploit fires impossible touches client owns the relevant part server query plus context validation; deliberate ownership
invisible trigger blocks players or queries miss it the three Can* flags conflated set CanCollide, CanTouch, CanQuery independently
attachments pile up temporary constraint lifecycle missing create and destroy constraint, attachments and connections together
collision group "does not exist" at startup groups registered from several scripts register in one script before assigning

Resources

  • Read references/queries-and-ownership.md when designing collision groups, query filters, a vehicle or other ownership-sensitive object, or a BodyMover migration; it has the flag roles, query choice, ownership debugging, and the physics test matrix.

Related skills

  • physics-tuning: timestep, jitter, tunnelling, mass ratios, and feel.
  • roblox-characters: Humanoid and custom movement across respawns.
  • roblox-networking: authoritative validation of client-requested physical actions.
  • roblox-studio-workflow: visualization, Output, and multi-client verification.

Version notes

Last verified: 2026-11-11.

  • Collision groups are registered on Workspace or a WorldModel (WorldRoot methods); the PhysicsService collision-group methods are deprecated. A WorldModel keeps its own matrix unless UseWorkspaceCollisionGroups is on.
  • BodyMovers (BodyPosition, BodyVelocity, BodyGyro and others) are deprecated in favour of the constraint-based movers.
  • Server Authority reached full release in July 2026; see roblox-networking for its rules.
  • To re-check an API: append .md to its Creator Hub URL, or start from https://create.roblox.com/docs/llms.txt.

Sources: https://create.roblox.com/docs/physics/assemblies, https://create.roblox.com/docs/physics/network-ownership, https://create.roblox.com/docs/workspace/raycasting, https://create.roblox.com/docs/workspace/collisions, https://create.roblox.com/docs/projects/server-authority.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill provides instructions and best practices for managing physics, spatial queries, and network ownership within the Roblox engine. It emphasizes server-side validation and secure development patterns.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/roblox-physics