Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/roblox-physics

roblox-physics

Verified

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

GoalMechanism
sustained physical interactionunanchored assembly plus modern constraints or forces
one-off physical changeApplyImpulse / ApplyAngularImpulse
kinematic platform or pathscripted pivot or CFrame with an explicit passenger policy
character locomotionHumanoid or Character Controller Library (roblox-characters)
hit testserver raycast, shapecast, or overlap with explicit filters
cosmetic trail or recoillocal 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

SymptomLikely causeRemedy
welded mechanism will not moveone part anchoredinspect the whole assembly; anchor only world roots
force too strong or too weakassembly mass ignoredread AssemblyMass; size force for the intended acceleration
fast projectile missesdiscrete contact samplingswept query (Blockcast, Spherecast, Shapecast) per step; see physics-tuning
ray hits the shooter or effectsno filter or query groupreuse explicit params and a query collision group
one target damaged many timesoverlap returned several body partsdeduplicate by model; attack ID or cooldown
exploit fires impossible touchesclient owns the relevant partserver query plus context validation; deliberate ownership
invisible trigger blocks players or queries miss itthe three Can* flags conflatedset CanCollide, CanTouch, CanQuery independently
attachments pile uptemporary constraint lifecycle missingcreate and destroy constraint, attachments and connections together
collision group "does not exist" at startupgroups registered from several scriptsregister 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.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall