Appearance
Physics: rigid bodies & forces
Galatrix runs a real rigid-body simulation in every runtime — the editor play-test, standalone builds, and the multiplayer server all step the same physics. This guide is the scripting side: how to make things fall, push, bounce, and — the part everyone gets wrong first — how to move a body correctly from a script.
New to scripts? Read Scripting basics first. Physics code lives in specific lifecycle hooks, and putting it in the wrong one is the single most common mistake (covered below).
What is this.entity.id?
this.entity is the GameObject the script is attached to (this.gameObject), and this.entity.id is its unique handle. The physics.* functions take that id string, not the object — so you always pass something.id. To act on a different object, get its id from this.game.findEntity('Name')?.id, a collision's other.id, or an Inspector reference field (this.target.id). findEntity returns null when nothing matches — guard it.
The one rule: physics owns dynamic bodies
Give an entity a RigidBody component and choose a type:
| Type | Who moves it | Use for |
|---|---|---|
| static | nobody — it never moves, but it still collides | floors, walls, terrain, fixed props |
| dynamic | the simulation — gravity, forces, collisions | crates, balls, ragdolls, debris |
| kinematic | you (script or animation) — it shoves dynamic bodies but ignores forces itself | moving platforms, doors, elevators |
(A walking player usually uses a Character Controller instead — a different component with its own guide: Scripting your own player.)
Here's the thing worth knowing up front:
On a dynamic body, the simulation drives the transform
Between your writes, a dynamic body's position and rotation belong to the solver — gravity, contacts and forces decide where it ends up. Writing entity.position = … still works and teleports the body, but it fights the sim if you do it every frame. To steer a dynamic body, use forces and velocity; to place one, write the transform or warpBody (all below).
On static, kinematic, and script-moved entities there is nothing to fight: you write the transform and the collider follows. (The same split governs rotation — see Rotations → Physics owns dynamic bodies.)
Moving a body: forces vs impulses vs velocity
Three ways to move a dynamic body, from gentlest to bluntest:
Force — a continuous push. Apply it every physics step and it builds up like a rocket; stop applying and it stops. Measured in Newtons, scaled by the body's mass.
js
onFixedUpdate() {
// steady lift while held — a jetpack
if (this.input.getKey('space')) this.physics.applyForce(this.entity.id, [0, 200, 0])
}Impulse — an instant kick: one call, one change in velocity. A jump, a hit, a launch.
js
this.physics.applyImpulse(this.entity.id, [0, 8, 0]) // pop straight up, onceVelocity — set the speed directly, ignoring mass and momentum. Precise but overrides the sim; reach for it when you want tight arcade control. Read-modify-write to change one axis and let gravity keep working:
js
const v = this.physics.getVelocity(this.entity.id)
this.physics.setVelocity(this.entity.id, [5, v[1], v[2]]) // drive X, keep the body's own fallEach has a spin counterpart — applyTorque / applyTorqueImpulse / setAngularVelocity (radians/s) — and an at-a-point variant, applyForceAtPoint / applyImpulseAtPoint, that pushes at a world point instead of the centre of mass, so it also tilts and spins the body. (That off-centre push is the primitive a scripted vehicle's suspension is built on — a spring force at each wheel contact IS the suspension. See Vehicles.)
Forces belong in onFixedUpdate
onUpdate runs once per rendered frame — 60, 144, however many the machine manages — so a force applied there hits a different number of times per second on every device. onFixedUpdate runs exactly once per physics step (20 Hz by default), everywhere. Rule of thumb: if you're calling physics, you're in onFixedUpdate.
Component style: the RigidBody handle
Everything above addresses a body by id — physics.setVelocity(this.entity.id, v). The same operations also hang off the Rigidbody component, and Galatrix accepts that spelling too:
js
const rb = this.entity.getComponent('rigidBody')
rb.velocity = [0, 10, 0] // same as physics.setVelocity(this.entity.id, [0, 10, 0])
const speed = rb.velocity.y // reads the running bodyThe two are the same call — the handle just already knows which entity it belongs to. Use whichever reads better; physics.* is still the way to touch a body that isn't the one you're holding.
What the handle carries:
| Member | Notes |
|---|---|
velocity, linearVelocity | get + set. Both names work — velocity is also spelled linearVelocity |
angularVelocity | get + set, radians/sec |
worldCenterOfMass | read-only |
AddForce(f, mode?) | see ForceMode below |
AddForceAtPosition(f, pos, mode?) | pushes off-centre, so it tilts and spins |
AddTorque(t, mode?) | spin |
GetPointVelocity(worldPoint) | how fast a point on the body is really moving |
AddRelativeForce(f, mode?), AddRelativeTorque(t, mode?) | the vector is in the body's local axes |
GetRelativePointVelocity(localPoint) | the local-space twin of GetPointVelocity |
AddExplosionForce(force, pos, radius, upwards?, mode?) | see below |
friction, restitution | get + set, live on the collider |
ccd, collisionDetectionMode | continuous collision — see Fast bodies |
linearDamping, angularDamping | drag, live |
gravityScale, useGravity | 1 normal, 0 weightless, negative floats up |
mass | exact target mass, independent of collider size/density |
freezePosition, freezeRotation | RigidbodyConstraints; a bare true freezes all three axes |
isKinematic, bodyType, type | swap dynamic / kinematic / static mid-play |
detectCollisions | colliders off, body still falling — no-clip / ghost / phase-through |
position, rotation, MovePosition(p), MoveRotation(r), Move(p, r?) | move the real body — see below |
Sleep(), WakeUp(), IsSleeping() | see Sleeping bodies |
Every method also has a camelCase twin — addForce, getPointVelocity, wakeUp — so both house styles work.
AddExplosionForce acts on this body only (a common misreading is that it hits everything nearby — to blast a crowd, loop over physics.overlapSphere). Force falls off linearly to zero at the rim, bodies outside the radius get nothing, and upwardsModifier sinks the blast origin by that many units so debris lifts instead of skidding.
The pose members keep momentum
position, MovePosition and friends move the real body and leave its velocity alone, matching rb.position. When you want the opposite — a body that arrives stopped and upright — call physics.warpBody, which is the reset.
ForceMode
AddForce and AddTorque take a ForceMode as an optional second argument:
js
rb.AddForce([0, 500, 0]) // ForceMode.Force — continuous, call every step
rb.AddForce([0, 8, 0], ForceMode.Impulse) // instant kick, scaled by mass
rb.AddForce([0, 8, 0], ForceMode.VelocityChange) // instant, IGNORES mass — +8 m/s whatever it weighs
rb.AddForce([0, 20, 0], ForceMode.Acceleration) // continuous, ignores massVelocityChange and Acceleration are the mass-independent pair: a 1 kg crate and a 5 kg crate given the same VelocityChange end up at the same speed.
Torque ignores the mass-independent modes
AddTorque(t, ForceMode.VelocityChange) needs the body's inertia tensor, which no runtime exposes. On torque, VelocityChange behaves as Impulse and Acceleration as Force.
Tuning a body mid-play
Authored rigidBody fields are baked into the physics body when it is built, and nothing re-applies them afterwards. Writing one at runtime used to change the JSON and leave the simulation exactly as it was — setting gravityScale = 0 mid-fall didn't slow the fall by a single unit. Now they're wired to real runtime verbs, so they mean what they say:
js
const rb = this.entity.getComponent('rigidBody')
rb.linearDamping = 4 // drag, live
rb.angularDamping = 2
rb.gravityScale = 0 // weightless; negative floats it up
rb.useGravity = false // the on/off face of the same thing
rb.mass = 50 // exact, whatever the collider's size or density
rb.freezeRotation = true // all three axes at once
rb.freezePosition = [true, false, true] // or per-axis
rb.isKinematic = true // solver stops moving it — drive it with MovePosition
rb.detectCollisions = false // keeps falling, but phases through everything
rb.friction = 0 // ice
rb.restitution = 0.9 // bouncy
rb.ccd = truedetectCollisions vs isKinematic
They sound similar and do opposite halves. detectCollisions = false leaves the body falling but stops it touching anything (a ghost). isKinematic = true stops the body moving but it still shoves things (a platform). Turning a body's collisions off does not freeze it.
Each has a namespace twin (physics.setDamping, setGravityScale, setMass, setFreeze, setBodyType…) if you'd rather address a body by id.
isKinematic is how a ragdoll wakes up
Flipping a body to kinematic freezes it under script control; flipping it back to dynamic hands it to the solver with no leftover momentum. That's the switch behind ragdoll activation, a carried prop going inert, and freezing an enemy mid-charge.
Five fields have no live verb: startAsleep, collisionGroups, frictionCombine, restitutionCombine, and autoCollider. Writing one (rb.frictionCombine = 'min', or the same through setComponent) rebuilds the entity's body with the new value, and the body keeps its velocity. To put a running body to sleep, call rb.Sleep() rather than writing startAsleep.
Writing a read-only member (rb.worldCenterOfMass = …) throws, rather than quietly storing a dead field.
freezePosition / freezeRotation read back what you wrote
The physics engine can set the axis locks but not report them, so those two getters return the last value written through the handle (which is also mirrored into the component, so multiplayer clients see it). Every other live member reads straight off the body.
Cross-entity works too
The handle binds the id of the entity it came from, not the script's own: game.findEntity('Crate').getComponent('rigidBody').velocity = [0, 5, 0].
Teleporting
Writing the transform moves a dynamic body, and the body keeps whatever momentum it had — a crate teleported mid-fall is still falling when it lands:
js
this.entity.position = [0, 5, 0] // moves the real body; velocity survivesFor a respawn you usually want the opposite: arrive stopped, and the right way up. That is warpBody, which teleports and resets — velocity zeroed, and an omitted rotation meaning upright, which is what rights a flipped vehicle:
js
this.physics.warpBody(this.entity.id, [0, 5, 0]) // drop it at a spawn point, stopped + upright
this.physics.warpBody(this.entity.id, [0, 5, 0], [0, 90, 0]) // …facing 90° (3 values = Euler degrees)So: transform writes to move something, warpBody to reset it.
Sleeping bodies
A body at rest eventually sleeps — it stops simulating (free performance) until a contact or force disturbs it. You can drive that directly with Rigidbody.Sleep/WakeUp/IsSleeping:
js
this.physics.sleep(this.entity.id) // stop simulating now
this.physics.wakeUp(this.entity.id) // resume
if (this.physics.isSleeping(this.entity.id)) { /* it has settled */ }To spawn a pile of props that stays frozen until the player touches it, check Start Asleep on the RigidBody component — the bodies sleep from the first frame and wake on the first contact or impulse.
Fast bodies: continuous collision (CCD)
The simulation advances in fixed steps, 20 a second by default. Between two steps a body just teleports from its old position to its new one — so a body moving faster than its own thickness per step can jump clean over a thin wall and never register the hit. Classic case: a bullet, a launched prop, a fast car.
The fix is continuous collision detection (CCD) — instead of testing only the end position, the engine sweeps the body's whole path that step and stops it at the first surface. Turn it on where you need it:
Authored: tick Continuous Collision (CCD) on the entity's RigidBody component (the
rigidBody.ccdfield). Best for anything born fast — projectiles, vehicles at speed.At runtime, through
Rigidbody.collisionDetectionMode:jsthis.physics.setCcd(bulletId, true) // this body now can't tunnel if (this.physics.isCcdEnabled(bulletId)) { /* … */ }A common pattern is to enable it on a projectile the moment you spawn/launch it:
jsconst b = this.game.spawnEntity('Bullet', 'sphere', muzzle) this.physics.setCcd(b.id, true) this.physics.setVelocity(b.id, [dir[0] * 80, dir[1] * 80, dir[2] * 80])
CCD costs a little CPU per body, so it's off by default — reserve it for the handful of bodies that actually move fast, not every crate. (Physics Rate in Game Settings ▸ Physics can raise the step to 40 or 60 Hz in the editor play-test and standalone builds; the multiplayer server always steps at 20 Hz. CCD, not a smaller timestep, is the right remedy for tunnelling.)
For almost every map the default is enough. If you have several extremely fast bodies that must resolve against each other in a single step, raise CCD Substeps in Game Settings ▸ Physics (project-wide, 1–8, default 1). Each substep re-runs the swept CCD pass, so higher is more accurate but more CPU — leave it at 1 unless you actually see fast bodies passing through each other (a single body vs. the world is already handled at 1).
Surface material: friction & bounce
Every collider carries two surface properties:
- Friction — grip.
0is ice; higher is stickier. Default0.5. - Restitution — bounciness,
0–1.0is a dead thud;1is a superball. Default0.
For a fixed value, set friction / restitution in the RigidBody component's Surface group in the Inspector — they bake in when the map loads, and they matter on static bodies too (an ice floor is static).
To change it live from a script — flip a floor to ice mid-game, make a power-up ball extra bouncy:
js
this.physics.setFriction(this.entity.id, 0) // this surface is now ice
this.physics.setFriction(this.entity.id, 3) // …now grippy
this.physics.setRestitution(this.entity.id, 0.9) // …and bouncy
const f = this.physics.getFriction(this.entity.id)One friction coefficient
The engine uses a single friction value per collider — there's no separate static vs dynamic friction. Friction and bounce are the two coefficients; the combine rule below decides how they mix when two surfaces touch.
When two bodies touch, their two frictions (and restitutions) combine — by default they average, so friction 0 against a 0.5 crate still leaves ~0.25 grip. That's what the combine rule is for (frictionCombine/restitutionCombine, the Friction Combine / Bounce Combine dropdowns in the Surface group): average (default), min, multiply, or max — when the two surfaces disagree, the higher-priority rule wins (max > multiply > min > average).
- True ice: friction
0+ combineminon the floor → slippery against anything that steps on it. - Trampoline: restitution
1+ combinemax→ bouncy no matter how dead the thing that lands is.
Gravity
The world pulls down at -50 on Y by default — deliberately strong, for snappy jumps rather than floaty ones. Don't hard-code that number; a map can change it, so read it:
js
const g = this.physics.getGravity() // e.g. [0, -50, 0] — reflects THIS map's setting
this.physics.setGravity([0, -20, 0]) // low-gravity moon levelPer body, the RigidBody's gravityScale multiplies world gravity: 1 is normal, 0 floats (weightless), 2 is heavy, a negative value falls up. Air resistance is linearDamping (a feather drifts down with high damping); spin resistance is angularDamping.
Colliders & collision events
The Collider component gives an entity its physical shape — box, sphere, capsule, cylinder, convex, or trimesh. It has two modes:
- Solid (default) — bodies bounce off it, and contacts fire
onCollisionEnter/onCollisionStay/onCollisionExit. - Trigger (
isTrigger, a sensor) — no physical response; overlaps fireonTriggerEnter/onTriggerStay/onTriggerExitinstead. This is how you build pickups, checkpoints, and damage zones.
js
class Target extends Behaviour {
onCollisionEnter(other) { // something physically hit me
if (other.compareTag('Bullet')) this.hp -= 10
}
onTriggerEnter(other) { // something entered my sensor volume
const door = this.game.findEntity('Door')
if (other.compareTag('Player') && door) door.active = false
}
}other says who touched — its id, name and tag, with compareTag for the tag check (the player is tagged 'Player'). It is not a live entity: this.game.getEntity(other.id) gives you an object's position and components, and for the player other.id is their player id, so this.players.getPosition(other.id). For the common "a player stepped in this zone" case there's also onPlayerEnter(player) / onPlayerLeave(player). For a worked example — a trigger pad that rewards the player who steps on it — see Scripting basics.
Sensing the world: raycasts & overlaps
Ask the physics world what's out there — line-of-sight, ground checks, shooting, proximity:
js
// clear line of sight from me to the target?
const from = this.entity.position
const target = this.game.findEntity('Target')
if (target) {
const to = target.position
const dir = [to[0] - from[0], to[1] - from[1], to[2] - from[2]]
const hit = this.physics.raycast(from, dir, Math.hypot(dir[0], dir[1], dir[2]), -1, [this.entity.id])
if (hit && hit.entityId === target.id) this.shoot() // nothing in between → fire
}raycast returns the nearest hit — a RaycastHit of { entityId, entityName, point, normal, distance } — or null. The family:
| Query | Returns |
|---|---|
raycast(origin, dir, maxDist?, layerMask?, ignoreEntities?, triggers?) | the nearest hit, or null |
raycastAll(origin, dir, maxDist?, layerMask?, ignoreEntities?, triggers?) | every hit along the ray, nearest-first |
sphereCast(origin, radius, dir, maxDist?, layerMask?, ignoreEntities?, triggers?) | the first entity a swept sphere would touch — the thick ray |
overlapSphere(center, radius, layerMask?) | entities within a radius — an explosion's blast list |
overlapBox(center, halfExtents, orientation?, layerMask?) | entities inside a box |
The trailing options on the ray/sweep queries — layerMask (which collision layers to see), ignoreEntities (specific entity ids to pass through) and triggers — are all optional; skip them, or pass -1 for layerMask to mean "all layers", when you only want one after it. triggers says whether trigger colliders count as hits: 'useGlobal' (the default) follows Raycasts Hit Triggers in Game Settings, which is on unless the map turns it off; 'ignore' flies through every trigger, which is what a shot wants; 'collide' hits them even when that setting is off.
sphereCast is the reliable ground check (Physics.SphereCast is the same cast, returning only true or false): a thin ray slips through a crack or off the edge of a ledge your character is half-standing on; a swept sphere the size of the body doesn't. Its distance is how far the sphere's center travelled before touching; point/normal are on the surface it hit.
Notes that save debugging time:
A ray starting at an entity's own
positioncan hit its own collider first. The clean fix is theignoreEntitieslist —this.physics.raycast(from, dir, 20, -1, [this.entity.id])passes straight through you (see below). You can also offset the origin past yourself — e.g. start a ground-check just below the feet:[x, y - 0.6, z]casting[0, -1, 0].sphereCastreportsdistance: 0when the sphere already overlaps a collider atorigin(it's a shape sweep — a shape starting inside geometry contacts at once), and the returned hit setsoverlapping: trueso you can detect exactly that case instead of guessing why the distance is 0:tsconst hit = this.physics.sphereCast(origin, 0.4, [0, -1, 0], 5) if (hit && hit.overlapping) { /* already touching it — distance 0 is contact, not a gap */ } else if (hit) { /* hit.distance is the real gap to the surface */ } else { /* nothing within maxDistance */ }So a
sphereCastthat begins touching the thing you're measuring is contact-at-start (overlapping), and itsdistanceis a real gap only when the cast starts clear of everything (overlappingis falsy). For a true gap-to-surface from inside contact, start the sphere back from the surface (offsetoriginalong-direction) or use a thinraycast, whosedistanceis the straightorigin → pointlength. (overlappingis asphereCast-only field — the cast returnsdistance 0on contact-at-start no matter what, so this flag is the honest way to tell it apart from a genuine zero gap.)The optional layerMask limits which collision layers a query sees:
1 << 3hits only layer 3; omit (or-1) for all layers.ignoreEntitiescomes AFTERlayerMask—sphereCast(origin, radius, dir, maxDist, layerMask, ignoreEntities). To skip only yourself, passundefinedfor the mask:sphereCast(o, r, dir, 5, undefined, [this.entity.id]). Putting the id list in thelayerMaskslot is the classic slip; the engine now detects an array there, treats it asignoreEntities, and warns in the console — but write it in the right slot and the warning goes away.The optional
ignoreEntitiesarray (trailing arg onraycast,raycastAll,sphereCast) lists entity ids the cast passes straight through, as if they weren't there — so the hit you get back is the first thing that isn't on the list:js// A hitscan shot from the shooter that never hits the shooter or the gun it's holding: const hit = this.physics.raycast(muzzle, aimDir, 100, -1, [this.entity.id, this.gunId]) if (hit) this.events.send(hit.entityId, 'damage', 25)Where
layerMaskfilters broad categories (all Enemies, all Terrain…),ignoreEntitiesskips a few specific objects — most often yourself ([this.entity.id]) or the thing you're carrying/riding. They combine: a collider is skipped ifignoreEntitiesnames it orlayerMaskexcludes its layer. A plain layer-mask query has no such parameter (you filter the results in code); this is a convenience on top oflayerMask. Pass entity ids (e.g.this.entity.id, or anentityIdfrom another hit) — not names.Aim with a direction the entity already gives you —
this.entity.forwardis its −Z in world space (for a child, in its parent's frame, except in a room's client scripts, where a drawn child's is world). A model faces +Z, so aim out of its front with the negatedforward(see Rotations).To see a ray while tuning it,
Debug.DrawRay(origin, dir)draws it in the editor viewport. A standalone build, and a client script in a room, draw it only while Debug Mode is on in Game Settings; a server script's line is not drawn.
Recipes
Explosion — everything nearby gets kicked away from the blast, harder the closer it is:
js
explode(center, radius, power) {
for (const e of this.physics.overlapSphere(center, radius)) {
const p = e.position
const d = [p[0] - center[0], p[1] - center[1] + 1, p[2] - center[2]] // +1 biases the kick upward
const len = Math.hypot(d[0], d[1], d[2]) || 1
const falloff = Math.max(0, 1 - len / radius) * power
this.physics.applyImpulse(e.id, [d[0] / len * falloff, d[1] / len * falloff, d[2] / len * falloff])
}
}Ice-patch trap — a trigger zone that makes the floor slick while a player is on it, then restores grip:
js
class IcePatch extends Behaviour {
// [Entity]
floor = null // an entity-reference field, set in the Inspector
onPlayerEnter() { this.physics.setFriction(this.floor.id, 0) }
onPlayerLeave() { this.physics.setFriction(this.floor.id, 0.5) }
}Grounded double-jump — sweep a sphere down to check for floor before allowing a jump (a thick check never misses the edge of a platform the way a thin ray does):
js
class Jumper extends Behaviour {
jumps = 0
_wantJump = false
onUpdate() {
if (this.input.getKeyDown('space')) this._wantJump = true // a press is per frame: read it here
}
onFixedUpdate() {
const p = this.entity.position
const grounded = !!this.physics.sphereCast([p[0], p[1], p[2]], 0.4, [0, -1, 0], 0.75, undefined, [this.entity.id])
if (grounded) this.jumps = 0
if (this._wantJump && this.jumps < 2) {
this.physics.applyImpulse(this.entity.id, [0, 9, 0])
this.jumps++
}
this._wantJump = false
}
}Changing a layer while the game runs
A script can change an entity's layer at any time (this.entity.layer = 5). Every script sees the new layer at once: entity.layer reads it, and so do overlapSphere and overlapBox with a layerMask. In a room, a server script's change reaches the scripts on every player's machine.
Collisions, raycasts and camera culling masks keep using the layer the entity had when it was built, in the play-test and in a published game. In a room this has three consequences:
- A player who joins after the change builds the entity on the new layer. On their machine its collisions, raycasts and culling use the new layer, while players who were already there keep the old one.
- The server switches to the new layer when it rebuilds the entity's collider, which happens when a script changes the entity's scale or one of its physics components (
collider,rigidBodyand the like). Players who were already there keep the old layer. - A client script's change stays on that player's machine until a server script changes the same entity's layer.
To change what an entity collides with during a game, change or remove its collider instead, or replace the entity with one spawned from a prefab on the other layer.
Editor & multiplayer
Everything here behaves identically in the editor play-test and a standalone build. In multiplayer the simulation is server-authoritative: forces, velocities, friction, and gravity are applied on the server and the result streams to every client. So physics.* calls only affect bodies the server actually simulates — a purely cosmetic client-side entity, or a character-controller-driven player, won't respond to them. (Character-controller players are the deliberate, client-authoritative exception — see Scripting your own player.)
See also
- Scripting basics — the
onUpdate/onFixedUpdatelifecycle this code runs in. - Rotations — orienting and spinning bodies through physics.
- Vehicles & driving — a full controller built on
applyForceAtPoint. physicsin the Script API reference — every method, with signatures.