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
- Inspect the mechanism. In Studio, turn on the assembly, constraint and network-owner
visualizations; or read
part.AssemblyRootPart,part.AssemblyMass,part.Anchoredandpart:GetNetworkOwner()from code. Identify the assembly root and who should own it. - Write the interaction policy. A collision-group matrix, then
CanCollide,CanTouchandCanQuerydecided separately per role. Register groups once withWorkspace:RegisterCollisionGroup()andCollisionGroupSetCollidable()(or the Collision Groups editor), from a single script so assignment never races registration. - 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.
.Touchedis neither reliable nor secure as a hit detector. - Apply motion at assembly level. Forces on any part act on the whole assembly. Use
LinearVelocity,AngularVelocity,VectorForce,AlignPositionandAlignOrientation; migrate BodyMovers when you touch that system. - Set ownership deliberately. Server-own gameplay-critical loose assemblies when needed; client ownership improves response but never authorizes results.
- Bound cost and lifetime. Reuse query params, cap query frequency and result counts, and destroy temporary constraints, attachments and connections together.
- Check from code. With the Studio MCP server connected, start play and use
execute_luauon theServerdatamodel to print the facts the change depends on:AssemblyRootPart,AssemblyMass,GetNetworkOwner(),workspace:CollisionGroupsAreCollidable(a, b), and the result of one test query; then readget_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
endmuzzlePosition 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
endBounds 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
.Touchedevents. The server validates consequential hits, positions, timing and permissions independently. - If
Workspace.AuthorityModeisServer, the server owns simulation and clients predict nearby assemblies with rollback. Drive predicted forces and constraints fromRunService:BindToSimulation()on both sides, not fromHeartbeator 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.mdwhen 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
Workspaceor aWorldModel(WorldRootmethods); thePhysicsServicecollision-group methods are deprecated. AWorldModelkeeps its own matrix unlessUseWorkspaceCollisionGroupsis on. - BodyMovers (
BodyPosition,BodyVelocity,BodyGyroand others) are deprecated in favour of the constraint-based movers. - Server Authority reached full release in July 2026; see
roblox-networkingfor its rules. - To re-check an API: append
.mdto its Creator Hub URL, or start fromhttps://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.