Give creations physical properties

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

Spatial creations use local Rapier physics. 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

{
  "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.

{
  "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.