> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Give creations physical properties

> Tune rigid bodies, compound collision shapes, sensors, joints and human interaction.

Spatial creations use local Rapier physics. [Figments](/spatial/figments) preserve those settings when published or copied. People can adjust them in **Objects → Physics**; agents use `ar_figment_physics` or validated `ar_world apply` operations.

## Adjust a body

```json theme={"theme":"github-light-default"}
{
  "name": "ar_figment_physics",
  "arguments": {
    "command": "physics",
    "payload": {
      "id": "lantern",
      "physics": {
        "mode": "dynamic",
        "mass": 0.6,
        "gravity": [0, -9.81, 0],
        "friction": 0.6,
        "restitution": 0.2,
        "linearDamping": 0.3,
        "angularDamping": 0.5,
        "translations": [true, true, true],
        "rotations": [true, true, true]
      }
    }
  }
}
```

This updates an existing object. Omitted physics fields keep their previous values; `physics: null` removes its body unless a joint still requires it. Bodies must be world roots. Use a grabbable group with a compound body for a rigid assembly, or separate root bodies connected by joints for moving parts.

| Property         | Meaning and range                                                                   |
| ---------------- | ----------------------------------------------------------------------------------- |
| `mode`           | `dynamic` responds to forces; `fixed` stays put; `kinematic` is positioned directly |
| `mass`           | Total mass in kilograms, `0.001–1000`                                               |
| `gravity`        | Per-body acceleration XYZ, each `-100–100` m/s²; `[0,0,0]` gives zero gravity       |
| `friction`       | Contact friction, `0–10`                                                            |
| `restitution`    | Bounce, `0–1`                                                                       |
| `linearDamping`  | Translational damping, `0–100`                                                      |
| `angularDamping` | Rotational damping, `0–100`                                                         |
| `translations`   | Enabled X/Y/Z translation axes                                                      |
| `rotations`      | Enabled X/Y/Z rotation axes                                                         |
| `colliders`      | Up to 16 named collision shapes attached to this body                               |

The older `damping` field sets both linear and angular damping unless you explicitly supply either value. A physics update preserves the current pose and velocity, with velocity removed from newly locked axes. A loaded model stays visible while its physical properties change.

## Compound collision shapes

Basic boxes, spheres, cylinders, and cones can derive a collider from their geometry. Blender models, groups, and custom shapes need explicit colliders. Keep their shapes simpler than the visible mesh.

```json theme={"theme":"github-light-default"}
{
  "colliders": [
    {
      "id": "body",
      "shape": "box",
      "size": [0.18, 0.3, 0.18],
      "position": [0, 0, 0],
      "rotation": [0, 0, 0]
    },
    {
      "id": "proximity",
      "shape": "sphere",
      "size": [0.8, 0.8, 0.8],
      "sensor": true
    }
  ]
}
```

Pass this object as `physics` to replace the body's collider array. Supported shapes are `box`, `sphere`, `capsule`, `cylinder`, `cone`, and `convex`. `size` uses full XYZ dimensions; positions are object-local metres and rotations are Euler XYZ radians. Capsules run along Y. Convex shapes take a flat `vertices` array containing 4–256 XYZ points that span a volume.

The renderer applies the object's scale to collision geometry, including nonuniform scale. Total mass is divided among solid colliders; sensors add no collision mass. A sensor-only dynamic body still receives the configured mass.

Optional `groups` is Rapier's unsigned 32-bit interaction mask: the high 16 bits describe membership, the low 16 bits describe accepted groups. Its default is `4294967295`, which interacts with all groups. A sensor reports overlap without producing a contact response.

## Joints and constraints

Use `ar_world apply` to create a `joint.create` operation between two physical root entities. Supported types are `hinge`, `slider`, `ball`, `rope`, and `spring`. Joint anchors use body-local coordinates; connected bodies do not collide with each other.

Hinges and sliders expose motor `velocity`, `strength`, and optional `[min,max]` limits. Rope and spring constraints use `length`; springs also use `stiffness` and `damping`. Named Figment joints are mapped in `definition.joints`, allowing behavior to call `api.motor("motor", speed, strength)` after importing a copy.

**Objects → Physics → Connections & constraints** exposes the relevant motor, limit, length and spring controls for an existing connection. Build the connection through the agent's world tools first.

## Impacts and sensors

Collision and sensor events are delivered to local programs for both participating creation objects. Ground contacts use `other: "ground"`. Other legacy scene colliders may have `other: null`.

| Event           | Data                                                                                |
| --------------- | ----------------------------------------------------------------------------------- |
| `collision`     | `other`, `collider`, `otherCollider`, `point`, `normal`, `impulse`, `relativeSpeed` |
| `collision.end` | The collider pair leaving contact                                                   |
| `sensor.enter`  | The collider pair entering overlap                                                  |
| `sensor.exit`   | The collider pair leaving overlap                                                   |

`point` and `normal` come from available solver contacts; they can be null. `impulse` is the summed reported contact impulse. `relativeSpeed` is the measured relative linear speed at event delivery, not a reconstructed pre-impact speed. Compound bodies can generate separate events for different collider pairs.

Use these values to drive glow, machines, counters, game rules or other local behavior. Human grabs take ownership of physical pose; release restores the configured body mode and bounded throw velocity. Pausing creations freezes their physics and programs. Room-mesh collision is not currently implemented: the desktop ground plane is not a scanned room.