# RIGIDBODY

> The RIGIDBODY engine component — body type, mass, friction, restitution, damping, weld, and why Static is what keeps a triangle-mesh collider.

- Source: https://diceytable.com/docs/editor/inspector/rigidbody
- Last verified: 2026-08-04

`RIGIDBODY` is an **Engine component** section (`tone="engine"`), intrinsic to every table
Entity. Unlike `RENDER`, it carries a **real enable checkbox** in its header, backed by
`physics.rigidbodyEnabled`.

Source: the `RIGIDBODY` `EmCollapsible` in `TableEditModeShell.tsx`'s `object` Inspector
branch; schema in `packages/shared/src/tableObjects.ts` (`objectPhysicsSchema`).

## The enable checkbox

| Control | Type | Default | Runtime effect | Replicates |
|---|---|---|---|---|
| **Header checkbox** | boolean | `true` (absent = enabled) | Disabling it takes the body **out of the physics simulation entirely without discarding its authored mass/friction/shape** — the settings below stay in the document, just unapplied. This is the "prefer disabling to removing" pattern PlayCanvas recommends for intrinsic components. | Yes — `physics.rigidbodyEnabled`, part of `TableObjectState.physics` |

## Weld children — shown only when this entity has parented children

| Field | Type | Default | Runtime effect | Replicates |
|---|---|---|---|---|
| **Weld children** | boolean | `false` | Off (default, `attached` mode): every parented child is held kinematic — the assembly shoves loose pieces but is never pushed back, and each child keeps its own authored body type, restored on unparent. On: the parent's collider becomes `compound`, children lose their own `rigidbody`, and the whole assembly becomes one dynamic body with combined mass — a thrown die bounces off it and nudges it. Welded children cannot be grabbed individually. | Yes — `physics.weldChildren`, part of `TableObjectState.physics` |

This field is set on the **parent**, not the child, and only appears when at least one other
object has `parentId` pointing at this one. The full weld/attached/joint decision tree —
including the rejection case for welding a member of an already-welded assembly, and the
explicit note that compound-rebuild cost in this Ammo build is unmeasured — is
`working/welding.md`'s to document (not this page); this section only covers the field as it
appears here.

## Body fields

| Field | Type | Range / units | Default | Runtime effect | Replicates |
|---|---|---|---|---|---|
| **Type** | select | `Static`, `Dynamic`, `Kinematic` | per-kind (`dynamic` for card/token/die/deck/bag/custom; `static` for board/card-holder) | **Static**: never moves, infinite mass (furniture, boards). **Dynamic**: fully simulated, responds to gravity and forces (cards, dice, tokens). **Kinematic**: moved by code, pushes dynamic bodies but is not itself pushed — the effective type a parented child is held at regardless of what is authored here. | Yes — `physics.bodyType` |
| **Mass** | number | > 0, kg | per-kind (0.02–0.3 depending on kind; absent for static kinds) | Only meaningful for dynamic bodies. Affects how the body responds to collisions and forces. | Yes — `physics.mass` |
| **Friction** | number | 0–1 | per-kind (0.5–0.8) | Coulomb friction coefficient — how much the surface resists sliding. | Yes — `physics.friction` |
| **Restitution** | number | 0–1 | per-kind (0.0–0.3) | Bounciness / coefficient of restitution. | Yes — `physics.restitution` |
| **Linear Damping** | number | 0–1 | per-kind (0.05–0.2) | Velocity damping applied over time — higher values settle a moving body faster. | Yes — `physics.linearDamping` |
| **Angular Damping** | number | 0–1 | per-kind (0.05–0.3) | Same, for rotational velocity. | Yes — `physics.angularDamping` |

Every field above is **optional on the schema**, and an absent value leaves the runtime to
pick. Setting a field always writes an explicit override; there is no separate "reset to
default" control for these six fields individually (contrast `DIE SETTINGS`'s explicit Reset
button).

⚠ **The `Default` column is the Inspector's placeholder, not the runtime's value, and the two
are not the same numbers.** The placeholders come from `defaultObjectPhysicsForKind`
(`packages/shared/src/tableObjects.ts`), whose own comment calls its output "an editable
*suggestion* — never written onto object state". What the table actually builds a body from is
`createRigidbodyConfig` and the `massForKind` / `frictionForKind` family
(`apps/web/src/playcanvas/physics/`), and they disagree — a `deck` is suggested at 0.3 kg and
simulated at 1.6. Two differences are worth knowing before you tune anything:

- **Type.** `createRigidbodyConfig` returns `static` when the entity is **locked** and
  `dynamic` otherwise, for every kind. Nothing makes a `board` or a `card-holder` static on the
  strength of its kind; only the lock does, and a parented child is held kinematic regardless.
- **Mass.** The suggestion is scaled by the surface material's density and by the entity's
  volume; the runtime's `massForKind` is a flat per-kind number.

The runtime figures are tabulated in [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds). Read
this panel's placeholders as a starting point to edit from, and that table for what the
simulation does with an entity you never touched.

### Type decides whether a triangle-mesh collider survives

**Type** is not only a physics setting: it is the one field on this panel that changes what
[`COLLISION`](https://diceytable.com/docs/editor/inspector/collision) is allowed to build.

Ammo's triangle-mesh shape (`btBvhTriangleMeshShape`) is valid **only for a static body**. So a
`Mesh` collision shape on a `Dynamic` or `Kinematic` Entity is not built as authored — the runtime
downgrades it to a **convex hull**, silently, with nothing on the table saying so. A hull is the
model's outer shell: every dent, hole and interior cavity is filled in, which is precisely the
property somebody choosing `Mesh` was trying to avoid. The symptom is a piece that will not drop
through an arch, will not sit inside a bowl, or bounces off thin air across a concave gap.

| What you want | Set **Type** to | Set `COLLISION` **Shape** to |
|---|---|---|
| Exact concave geometry, and the object never moves on its own | `Static` | `Mesh` |
| Concave-ish geometry on a piece that must move | `Dynamic` | a multi-entry collider list of primitives, authored on the model asset |
| Convex geometry on a piece that must move | `Dynamic` | `Convex Hull` |

Note the second row: the way to have a moving piece with a non-convex collider is several primitive
shapes assembled into one compound collider, authored on the **model asset** rather than here. See
[COLLISION § More than one shape per model](https://diceytable.com/docs/editor/inspector/collision#more-than-one-shape-per-model-the-authored-collider-list)
and [Sidecars](https://diceytable.com/docs/mods/files/sidecars).

⚠ **Lock changes the effective type.** `createRigidbodyConfig` returns `static` when the Entity is
locked and `dynamic` otherwise, whatever this select says — so locking a piece can make a `Mesh`
collider start working, and unlocking it can silently swap that collider for a hull. If a collider
seems to change behaviour when nothing about the collider changed, check the lock.

Two other conditions can refuse a mesh-derived collider outright, both of them about the model rather
than the body: they are documented in
[COLLISION § The two refusals](https://diceytable.com/docs/editor/inspector/collision#the-two-refusals-when-a-mesh-derived-collider-does-not-happen).

**You do not have to discover this by watching a piece behave oddly.** The Model tab's
`COLLISION` panel renders the downgrade as a warning while you are authoring, naming `static` as
the fix — see [Item editors: Model](https://diceytable.com/docs/editor/item-editors/model#the-three-warnings-this-panel-renders).
It is still worth knowing here, because **Type** is edited on *this* panel and the consequence
lands on that one.

## From surface — custom/imported pieces only

| Field | Type | Runtime effect |
|---|---|---|
| **From surface** | read-only text | Shows the mass/friction/restitution that `defaultObjectPhysicsForKind` would compute from this piece's current [`PIECE`](https://diceytable.com/docs/editor/inspector/piece) `Surface` and scale — purely informational. The editable fields above stay authoritative; this readout never writes anything. |

## See also

- [collision.md](https://diceytable.com/docs/editor/inspector/collision) — the paired intrinsic component, right
  below `RIGIDBODY`.
- [Item editors: Model](https://diceytable.com/docs/editor/item-editors/model#collision) — where a model's collider
  list is authored, and where the dynamic/triangle-mesh warning is shown.
- [piece.md](https://diceytable.com/docs/editor/inspector/piece) — where `Surface` (the input to "From surface")
  lives.
- `working/welding.md` and `working/parenting.md` (not this task) — the full weld/parenting
  behavior this section's **Weld children** checkbox triggers.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — `TableObjectState.physics` and `TableJointState`, the read-only mod view of these settings.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — `lock` and `unlock`, the script equivalent of the lock toggle.
