roblox-physics

interface:
  display_name: "Roblox Physics"
  short_description: "Build secure Roblox physics and queries"
  default_prompt: "Use $roblox-physics to implement and verify this Roblox physics system."

# Roblox physics queries, collision policy, and ownership

Read this when designing collision groups, query filters, a physical gameplay object, or a
multiplayer ownership/security test.

## Separate the three flags

`CanCollide` controls physical response, `CanTouch` controls touch event participation, and
`CanQuery` controls spatial-query eligibility (subject to query parameters). Define each by role.
Typical sensor parts do not collide but may touch/query; visual-only geometry may do neither. Use
named collision groups registered on the world (`Workspace:RegisterCollisionGroup()`,
`CollisionGroupSetCollidable()`; a `WorldModel` keeps its own matrix unless
`UseWorkspaceCollisionGroups` is on) and verify the actual matrix in Studio. Registration has a
cost proportional to part count, so register groups at edit time or once at startup. The
`PhysicsService` versions are deprecated.

## Query selection

- `Workspace:Raycast(origin, direction, params)` for the first surface along a segment. Direction
  magnitude is range.
- sphere/block radius/bounds overlap methods for broad volume candidates. Deduplicate assemblies or
  target models and refine if bounding-box false positives matter.
- configure `RaycastParams`/`OverlapParams` with include/exclude instances, collision group, water,
  and result bounds. Reuse params where the filter is stable; update it when character generations
  or streamed containers change.

Query results are evidence, not a whole gameplay authorization. Also validate actor state, team,
cooldown, origin, target membership, and permissions on the server.

## Assembly and ownership debugging

In Studio, inspect `AssemblyRootPart`, `AssemblyMass`, center of mass, anchors, constraints, and the
Network Owners visualization. Test automatic ownership before forcing it. Server ownership protects
simulation authority but can increase server work and latency; client ownership improves response
but requires server validation of consequences.

When a mechanism changes anchor state, re-check ownership because prior ownership state may not be
retained. For vehicles, explicitly decide which occupant should own the assembly and what happens
on seat changes, death, or disconnect.

## Modern motion migration

Map sustained linear control to `LinearVelocity` or `VectorForce`, rotational control to
`AngularVelocity`/`Torque`, and pose following to `AlignPosition`/`AlignOrientation`. Preserve the
old system's coordinate space, force/torque limits, attachment geometry, reaction force, and
ownership behavior; do not replace class names without measuring behavior.

## Verification matrix

Test one part and a welded multi-part assembly; anchored/unanchored transitions; intended collision
group pairs; each Can* flag; fast and slow movers; low/high mass; ray miss/hit/filter edge; overlap
deduplication and max-result behavior; client approaching/leaving automatic ownership; explicit
owner disconnect/death; two clients interacting simultaneously; streaming absence; and complete
temporary-object cleanup. Use server-observed results for gameplay assertions.

## Primary references

- `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/reference/engine/datatypes/RaycastParams`

---
name: roblox-physics
description: >
  Implement Roblox physical simulation and queries with assemblies, anchoring, constraints,
  collision groups, CanCollide/CanTouch/CanQuery, raycasts and overlap queries, mass, impulses,
  forces, velocity, moving assemblies, cleanup, and network ownership. Use for Roblox collisions,
  hit detection, RaycastParams, PhysicsService, projectiles, vehicles, knockback, constraints,
  deprecated BodyMovers, unstable motion, or client-owned physics exploits.
---

# Roblox physics

Choose deliberately between simulation, character control, hit detection, and visual-only motion;
they are different jobs. Targets Roblox's rolling platform APIs. Pair with `physics-tuning` for
engine-neutral stability and feel.

## When to use

- Use for BasePart assemblies, constraints, collision/query policy, ray/overlap queries, forces,
  impulses, moving physical objects, network ownership, or physics cleanup.
- Use when `Touched` is unreliable/security-sensitive, parts tunnel or jitter, a mechanism breaks
  when anchored, or old BodyMover patterns appear.

**When not to use:** ordinary Humanoid lifecycle/control belongs to `roblox-characters`; remote
validation belongs to `roblox-networking`; decorative UI/world motion may only need a tween.

## Decide the system first

| Goal | Mechanism |
|---|---|
| sustained physical interaction | unanchored assembly + modern constraints/forces |
| instantaneous physical change | `ApplyImpulse` / `ApplyAngularImpulse` |
| kinematic platform/path | controlled pivot/transform with an explicit passenger policy |
| character locomotion | Humanoid/custom character controller (`roblox-characters`) |
| authoritative hit test | server raycast/overlap with filters and gameplay validation |
| cosmetic trail/recoil | local visual motion; no gameplay authority |

## Workflow

1. **Inspect the mechanism.** In Studio, visualize assemblies, anchors, constraints, collision
   groups, massless parts, and network owners. Identify the assembly root and intended authority.
2. **Define interaction policy.** Write the collision-group matrix and separately decide
   `CanCollide`, `CanTouch`, and `CanQuery`. These flags are not interchangeable. Register groups
   in the Studio Collision Groups editor or with `Workspace:RegisterCollisionGroup()` and
   `Workspace:CollisionGroupSetCollidable()`; the `PhysicsService` collision-group methods are
   deprecated and forward to `Workspace`.
3. **Choose simulation or query.** Do not use `.Touched` as a universal hit detector. Use a ray for
   a path/line, an overlap query for a volume, and simulation contacts when physical response is
   actually required.
4. **Apply motion at assembly level.** Forces on a part affect its assembly. Use modern
   `LinearVelocity`, `AngularVelocity`, `VectorForce`, `AlignPosition`, and `AlignOrientation`
   constraints as appropriate; migrate deprecated BodyMovers when changing that system.
5. **Set ownership deliberately.** Server-own gameplay-critical loose assemblies when required;
   client ownership can improve responsiveness but never authorizes gameplay results.
6. **Bound cost and lifetime.** Reuse query parameters, cap query frequency/result count, remove
   temporary constraints/attachments, and disconnect event listeners.
7. **Verify under load and multiplayer.** Test anchored/unanchored transitions, mass extremes,
   collision matrix, fast motion, multiple clients, ownership changes, streaming, and cleanup.

## Pattern: filtered server raycast

```lua
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
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
```

The server must validate the origin/direction against server-known character/weapon state; do not
accept an arbitrary client origin and treat the raycast itself as validation.

## Pattern: overlap volume with explicit policy

```lua
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 use bounding boxes and can include multiple parts from one target; deduplicate and
perform exact/gameplay checks as needed. For exact geometry use `WorldRoot:GetPartsInPart(part, overlapParams)`
only when its additional cost is justified. Note `OverlapParams.RespectCanCollide` decides whether a
query honours `CanCollide` or `CanQuery` — set it deliberately, or it silently overrides the flag
policy below. `OverlapParams.Tolerance` controls contact slop.

## Assemblies, force, and ownership

- Welded parts form one rigid assembly; force, impulse, velocity, mass, and ownership operate on
  that assembly. Anchoring a part changes simulation/ownership and can make an assembly effectively
  infinite mass.
- Apply an impulse for a one-time change; use a force or velocity constraint for sustained control.
  Setting `AssemblyLinearVelocity` is an immediate state change, not a continuous force model.
- Prefer attachments plus modern constraints over `BodyPosition`, `BodyVelocity`, `BodyGyro`, and
  other deprecated BodyMovers when authoring or revising a mechanism.
- Automatic ownership may move nearby unanchored assemblies to clients. Use
  `SetNetworkOwner(nil)` conservatively for critical objects, then measure responsiveness/server
  cost. Visualize network owners in Studio.
- A client owner can manipulate physical results and `.Touched` observations. The server validates
  consequential hits, positions, timing, and permissions independently.
- If `Workspace.AuthorityMode` is `Server`, the server owns simulation and clients predict parts
  near their own character with rollback (`RunService:SetPredictionMode()`, client-only, overrides
  per instance). Drive
  predicted forces and constraints from `RunService:BindToSimulation()` on both sides rather than
  from `Heartbeat` or client-only scripts; custom physics scripts need adapting when a place
  switches modes. See `roblox-networking`.

## Common failures

| Symptom | Likely cause | Remedy |
|---|---|---|
| welded mechanism will not move | one part anchored | inspect full assembly; anchor only intentional world roots |
| force behaves too strongly/weakly | assembly mass ignored | inspect `AssemblyMass`; tune force/impulse by intended acceleration |
| hit misses fast projectile | discrete touch sampling/tunneling | swept query — `WorldRoot:Blockcast()`, `Spherecast()`, or `Shapecast()` — plus `physics-tuning`; do not rely only on `.Touched` |
| ray hits shooter/effects | filters/collision group absent | reuse explicit params and query group |
| same target damaged many times | overlap returned multiple body parts | deduplicate by target model and enforce attack ID/cooldown |
| exploit fires impossible touch | client owns relevant physics | server query/context validation; deliberate ownership |
| invisible trigger blocks or cannot query | three flags conflated | set `CanCollide`, `CanTouch`, `CanQuery` independently |
| mechanism leaks attachments | temporary constraint lifecycle missing | own and destroy constraints, attachments, and connections together |

## Resources

- Read `references/queries-and-ownership.md` for collision/query matrices, assembly debugging,
  ownership security, migration choices, and the physics verification matrix.

## Related skills

- `physics-tuning` — timestep, jitter, tunneling, mass ratios, and stability methodology.
- `roblox-characters` — Humanoid/custom movement and respawn lifecycle.
- `roblox-networking` — authoritative validation of client-requested physical actions.
- `roblox-studio-workflow` — visualization, Output, and multi-client verification.

## Primary references

- `https://create.roblox.com/docs/physics/assemblies`
- `https://create.roblox.com/docs/physics/network-ownership`
- `https://create.roblox.com/docs/workspace/raycasting`