/roblox-physics

name: roblox-physics
description: >
  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`).

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 cha