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
- Inspect the mechanism. In Studio, visualize assemblies, anchors, constraints, collision
groups, massless parts, and network owners. Identify the assembly root and intended authority.
- 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.
- 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.
- 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.
- Set ownership deliberately. Server-own gameplay-critical loose assemblies when required;
client ownership can improve responsiveness but never authorizes gameplay results.
- Bound cost and lifetime. Reuse query parameters, cap query frequency/result count, remove
temporary constraints/attachments, and disconnect event listeners.
- 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
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
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
1---2name: roblox-physics3description: >4 Implement Roblox physical simulation and queries with assemblies, anchoring, constraints,5 collision groups, CanCollide/CanTouch/CanQuery, raycasts and overlap queries, mass, impulses,6 forces, velocity, moving assemblies, cleanup, and network ownership. Use for Roblox collisions,7 hit detection, RaycastParams, PhysicsService, projectiles, vehicles, knockback, constraints,8 deprecated BodyMovers, unstable motion, or client-owned physics exploits.9metadata:10 source: https://skillmd.com/skills/junmystery/roblox-physics11---1213# Roblox physics1415Choose deliberately between simulation, character control, hit detection, and visual-only motion;16they are different jobs. Targets Roblox's rolling platform APIs. Pair with `physics-tuning` for17engine-neutral stability and feel.1819## When to use2021- Use for BasePart assemblies, constraints, collision/query policy, ray/overlap queries, forces,22 impulses, moving physical objects, network ownership, or physics cleanup.23- Use when `Touched` is unreliable/security-sensitive, parts tunnel or jitter, a mechanism breaks24 when anchored, or old BodyMover patterns appear.2526**When not to use:** ordinary Humanoid lifecycle/control belongs to `roblox-characters`; remote27validation belongs to `roblox-networking`; decorative UI/world motion may only need a tween.2829## Decide the system first3031| Goal | Mechanism |32|---|---|33| sustained physical interaction | unanchored assembly + modern constraints/forces |34| instantaneous physical change | `ApplyImpulse` / `ApplyAngularImpulse` |35| kinematic platform/path | controlled pivot/transform with an explicit passenger policy |36| character locomotion | Humanoid/custom character controller (`roblox-characters`) |37| authoritative hit test | server raycast/overlap with filters and gameplay validation |38| cosmetic trail/recoil | local visual motion; no gameplay authority |3940## Workflow41421. **Inspect the mechanism.** In Studio, visualize assemblies, anchors, constraints, collision43 groups, massless parts, and network owners. Identify the assembly root and intended authority.442. **Define interaction policy.** Write the collision-group matrix and separately decide45 `CanCollide`, `CanTouch`, and `CanQuery`. These flags are not interchangeable. Register groups46 in the Studio Collision Groups editor or with `Workspace:RegisterCollisionGroup()` and47 `Workspace:CollisionGroupSetCollidable()`; the `PhysicsService` collision-group methods are48 deprecated and forward to `Workspace`.493. **Choose simulation or query.** Do not use `.Touched` as a universal hit detector. Use a ray for50 a path/line, an overlap query for a volume, and simulation contacts when physical response is51 actually required.524. **Apply motion at assembly level.** Forces on a part affect its assembly. Use modern53 `LinearVelocity`, `AngularVelocity`, `VectorForce`, `AlignPosition`, and `AlignOrientation`54 constraints as appropriate; migrate deprecated BodyMovers when changing that system.555. **Set ownership deliberately.** Server-own gameplay-critical loose assemblies when required;56 client ownership can improve responsiveness but never authorizes gameplay results.576. **Bound cost and lifetime.** Reuse query parameters, cap query frequency/result count, remove58 temporary constraints/attachments, and disconnect event listeners.597. **Verify under load and multiplayer.** Test anchored/unanchored transitions, mass extremes,60 collision matrix, fast motion, multiple clients, ownership changes, streaming, and cleanup.6162## Pattern: filtered server raycast6364```lua65local Workspace = game:GetService("Workspace")6667local params = RaycastParams.new()68params.FilterType = Enum.RaycastFilterType.Exclude69params.FilterDescendantsInstances = {shooterCharacter}70params.IgnoreWater = true71params.CollisionGroup = "WeaponQuery"7273local direction = aimDirection.Unit * MAX_RANGE74local result = Workspace:Raycast(muzzlePosition, direction, params)75if result then76 local model = result.Instance:FindFirstAncestorOfClass("Model")77 local humanoid = model and model:FindFirstChildOfClass("Humanoid")78 if humanoid and serverCanDamage(shooter, model, result.Position) then79 humanoid:TakeDamage(serverWeaponDamage(shooter))80 end81end82```8384The server must validate the origin/direction against server-known character/weapon state; do not85accept an arbitrary client origin and treat the raycast itself as validation.8687## Pattern: overlap volume with explicit policy8889```lua90local params = OverlapParams.new()91params.FilterType = Enum.RaycastFilterType.Exclude92params.FilterDescendantsInstances = {sourceCharacter}93params.CollisionGroup = "DamageQuery"94params.MaxParts = 649596local seen: {[Model]: boolean} = {}97for _, part in Workspace:GetPartBoundsInBox(hitboxCFrame, hitboxSize, params) do98 local model = part:FindFirstAncestorOfClass("Model")99 if model and not seen[model] then100 seen[model] = true101 validateAndApplyHit(model)102 end103end104```105106Bounds queries use bounding boxes and can include multiple parts from one target; deduplicate and107perform exact/gameplay checks as needed. For exact geometry use `WorldRoot:GetPartsInPart(part, overlapParams)`108only when its additional cost is justified. Note `OverlapParams.RespectCanCollide` decides whether a109query honours `CanCollide` or `CanQuery` — set it deliberately, or it silently overrides the flag110policy below. `OverlapParams.Tolerance` controls contact slop.111112## Assemblies, force, and ownership113114- Welded parts form one rigid assembly; force, impulse, velocity, mass, and ownership operate on115 that assembly. Anchoring a part changes simulation/ownership and can make an assembly effectively116 infinite mass.117- Apply an impulse for a one-time change; use a force or velocity constraint for sustained control.118 Setting `AssemblyLinearVelocity` is an immediate state change, not a continuous force model.119- Prefer attachments plus modern constraints over `BodyPosition`, `BodyVelocity`, `BodyGyro`, and120 other deprecated BodyMovers when authoring or revising a mechanism.121- Automatic ownership may move nearby unanchored assemblies to clients. Use122 `SetNetworkOwner(nil)` conservatively for critical objects, then measure responsiveness/server123 cost. Visualize network owners in Studio.124- A client owner can manipulate physical results and `.Touched` observations. The server validates125 consequential hits, positions, timing, and permissions independently.126- If `Workspace.AuthorityMode` is `Server`, the server owns simulation and clients predict parts127 near their own character with rollback (`RunService:SetPredictionMode()`, client-only, overrides128 per instance). Drive129 predicted forces and constraints from `RunService:BindToSimulation()` on both sides rather than130 from `Heartbeat` or client-only scripts; custom physics scripts need adapting when a place131 switches modes. See `roblox-networking`.132133## Common failures134135| Symptom | Likely cause | Remedy |136|---|---|---|137| welded mechanism will not move | one part anchored | inspect full assembly; anchor only intentional world roots |138| force behaves too strongly/weakly | assembly mass ignored | inspect `AssemblyMass`; tune force/impulse by intended acceleration |139| hit misses fast projectile | discrete touch sampling/tunneling | swept query — `WorldRoot:Blockcast()`, `Spherecast()`, or `Shapecast()` — plus `physics-tuning`; do not rely only on `.Touched` |140| ray hits shooter/effects | filters/collision group absent | reuse explicit params and query group |141| same target damaged many times | overlap returned multiple body parts | deduplicate by target model and enforce attack ID/cooldown |142| exploit fires impossible touch | client owns relevant physics | server query/context validation; deliberate ownership |143| invisible trigger blocks or cannot query | three flags conflated | set `CanCollide`, `CanTouch`, `CanQuery` independently |144| mechanism leaks attachments | temporary constraint lifecycle missing | own and destroy constraints, attachments, and connections together |145146## Resources147148- Read `references/queries-and-ownership.md` for collision/query matrices, assembly debugging,149 ownership security, migration choices, and the physics verification matrix.150151## Related skills152153- `physics-tuning` — timestep, jitter, tunneling, mass ratios, and stability methodology.154- `roblox-characters` — Humanoid/custom movement and respawn lifecycle.155- `roblox-networking` — authoritative validation of client-requested physical actions.156- `roblox-studio-workflow` — visualization, Output, and multi-client verification.157158## Primary references159160- `https://create.roblox.com/docs/physics/assemblies`161- `https://create.roblox.com/docs/physics/network-ownership`162- `https://create.roblox.com/docs/workspace/raycasting`