lecodes-sdk 2.4.1 → 2.4.2

package/src/gl/animation/IK.ts

@@ -79,8 +79,6 @@ abstract class Chain<Name extends string> extends Aspect<Name, Node> {
     this._ik = 0
     this._rig = undefined
   }
-  onReconfigure(): void { this.push() }
-
   protected params(): Float32Array {
     const p = new Float32Array(P.COUNT)
     p[P.WEIGHT] = this._weight

package/src/gl/nav/NavAgent.ts

@@ -74,26 +74,26 @@ export class NavAgent extends Aspect<"agent", Node, NavAgentEvents> {
 
   /** Agent radius (metres). Defaults to the navmesh's. */
   get radius(): number { return this._radius }
-  set radius(v: number) { this._radius = v; this._dirty = true }
+  set radius(v: number) { this._radius = v; this.dirty() }
   get height(): number { return this._height }
-  set height(v: number) { this._height = v; this._dirty = true }
+  set height(v: number) { this._height = v; this.dirty() }
   /** Top speed (m/s). */
   get speed(): number { return this._speed }
-  set speed(v: number) { this._speed = v; this._dirty = true }
+  set speed(v: number) { this._speed = v; this.dirty() }
   get acceleration(): number { return this._acceleration }
-  set acceleration(v: number) { this._acceleration = v; this._dirty = true }
+  set acceleration(v: number) { this._acceleration = v; this.dirty() }
   /** Local (agent-vs-agent) avoidance quality. */
   get avoidance(): NavAgentAvoidance { return this._avoidance }
-  set avoidance(v: NavAgentAvoidance) { this._avoidance = v; this._dirty = true }
+  set avoidance(v: NavAgentAvoidance) { this._avoidance = v; this.dirty() }
   /** Separation force weight (0 = none). */
   get separation(): number { return this._separation }
-  set separation(v: number) { this._separation = v; this._dirty = true }
+  set separation(v: number) { this._separation = v; this.dirty() }
   /** Area names this agent may walk (default: all). */
   get include(): string[] | undefined { return this._include }
-  set include(v: string[] | undefined) { this._include = v; this._dirty = true }
+  set include(v: string[] | undefined) { this._include = v; this.dirty() }
   /** Area names this agent never enters. */
   get exclude(): string[] | undefined { return this._exclude }
-  set exclude(v: string[] | undefined) { this._exclude = v; this._dirty = true }
+  set exclude(v: string[] | undefined) { this._exclude = v; this.dirty() }
 
   state: NavAgentState = "idle"
   /** The current velocity after avoidance (m/s). */
@@ -111,7 +111,6 @@ export class NavAgent extends Aspect<"agent", Node, NavAgentEvents> {
   private _target: Vec3 | null = null
   /** velocity-driven (`move`) rather than target-driven */
   private _steering = false
-  private _dirty = false
   private _faceX = 0
   private _faceZ = -1
   private _retryAt = 0
@@ -125,7 +124,12 @@ export class NavAgent extends Aspect<"agent", Node, NavAgentEvents> {
     this._join()
   }
 
-  onReconfigure(): void { this._dirty = true }
+  /** A parameter changed: push the agent's params to the crowd (a no-op until it has a slot —
+   *  `_join` sends them with the add). */
+  protected flush(): void {
+    const crowd = this._crowd
+    if (crowd && this._slot >= 0 && crowd._mesh === NavMesh.active) _creatorNav.crowdSetParams(crowd._id, this._slot, this.params())
+  }
 
   onDetach(): void {
     this._leave()
@@ -216,7 +220,6 @@ export class NavAgent extends Aspect<"agent", Node, NavAgentEvents> {
     if (slot < 0) { this._retryAt = crowd._step + JOIN_RETRY_STEPS; return false }
     this._crowd = crowd
     this._slot = slot
-    this._dirty = false
     this._lastSeen = -1
     crowd._agents.add(this)
     if (this._target && !_creatorNav.crowdSetTarget(crowd._id, slot, this._target.x, this._target.y, this._target.z)) this._target = null
@@ -253,7 +256,6 @@ export class NavAgent extends Aspect<"agent", Node, NavAgentEvents> {
     }
     const crowd = this._crowd!
     if (crowd._mesh !== NavMesh.active) { this._leave(); return }
-    if (this._dirty) { this._dirty = false; _creatorNav.crowdSetParams(crowd._id, this._slot, this.params()) }
     if (crowd._step === this._lastSeen) return   // the crowd has not advanced since (a frame with no step)
     this._lastSeen = crowd._step
     const b = crowd._buf

package/src/gl/physics/Physics.ts

@@ -72,11 +72,10 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
    * `1`, ice `0.02`. A Vehicle's tires read the GROUND body's value, so this is the single number
    * that decides how well a car corners.
    *
-   * Change it at runtime by re-configuring — `floor.aspect(Physics, { friction: 0.02 })` (an ice
-   * patch) — or by assigning `floor.physics.friction = 0.02`; either way the setter pushes the new
-   * surface to the live body at once. (chisel keeps an instance setter whose name appears as an
-   * object-literal key anywhere in the bundle, so the config-object route survives tree-shaking
-   * even when no code reads `.friction`.)
+   * Live: `floor.physics.friction = 0.02` (an ice patch) pushes the new surface to the body at
+   * once. (chisel keeps an instance setter whose name appears as an object-literal key anywhere in
+   * the bundle, so `aspect(Physics, { friction })` at build survives tree-shaking even when no code
+   * reads `.friction`.)
    */
   get friction(): number { return this._friction }
   set friction(v: number) {

package/src/gl/physics/Shape.ts

@@ -18,6 +18,7 @@
 // (which follows the sim), rather than relying on the pick body.
 
 import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
 import { cx, cy, cz, type Vec3Like } from "../../math/vec"
 import type { Node } from "../Node"
 
@@ -51,23 +52,42 @@ const dim = (v: number): number => Math.max(MIN_HALF, r4(v))
 export class Shape extends Aspect<"shape", Node> {
   static readonly aspect = "shape"
 
+  // Every dimension is LIVE and applies AT ONCE: a write rebuilds the geometry in place, the body
+  // keeping its id, velocity and place (a crouch, a live editor edit) — synchronous, because the
+  // caller reads the result back right away (`controller.resizing`, the node's height). A write that
+  // leaves the geometry's signature unchanged does nothing. `fit()` writes every field and rebuilds once.
+  private _box?: Vec3Like
+  private _sphere?: number
+  private _cylinder?: { halfHeight: number, radius: number }
+  private _capsule?: { halfHeight: number, radius: number }
+  private _mesh?: boolean | "convex"
+  private _heightfield?: boolean
+  private _origin?: Vec3Like
+  private _raycast = true
+
   /** Box half-extents [hx, hy, hz] (world units). */
-  box?: Vec3Like
+  get box(): Vec3Like | undefined { return this._box }
+  set box(v: Vec3Like | undefined) { this._box = v; this._changed() }
   /** Sphere radius. */
-  sphere?: number
+  get sphere(): number | undefined { return this._sphere }
+  set sphere(v: number | undefined) { this._sphere = v; this._changed() }
   /** Cylinder aligned on Y: half-height + radius. */
-  cylinder?: { halfHeight: number, radius: number }
+  get cylinder(): { halfHeight: number, radius: number } | undefined { return this._cylinder }
+  set cylinder(v: { halfHeight: number, radius: number } | undefined) { this._cylinder = v; this._changed() }
   /** Capsule aligned on Y: half-height of the cylinder section + radius. */
-  capsule?: { halfHeight: number, radius: number }
+  get capsule(): { halfHeight: number, radius: number } | undefined { return this._capsule }
+  set capsule(v: { halfHeight: number, radius: number } | undefined) { this._capsule = v; this._changed() }
   /** The node's own triangles (a Mesh's geometry or a Model's GLB, world scale applied).
    *  `true` = exact triangle mesh — static/kinematic bodies, triggers, characters' ground and picking
    *  only (a dynamic body can't be a triangle mesh; Physics throws). `'convex'` = convex hull of the
    *  vertices, works for dynamic bodies too. A Model uses its bind pose (skinned parts skipped). */
-  mesh?: boolean | "convex"
+  get mesh(): boolean | "convex" | undefined { return this._mesh }
+  set mesh(v: boolean | "convex" | undefined) { this._mesh = v; this._changed() }
   /** The node's terrain (`Terrain.create(...).node`) as a Jolt height field — the exact drawn grid,
    *  holes included (docs/terrain-plan.md). Static / kinematic / picking / character ground only,
    *  like `mesh: true`. `terrain.commit()` pushes edits into the live shape. */
-  heightfield?: boolean
+  get heightfield(): boolean | undefined { return this._heightfield }
+  set heightfield(v: boolean | undefined) { this._heightfield = v; this._changed() }
   /**
    * The shape's centre, relative to the node's origin — world units in the node's ROTATED frame
    * (the node's scale is ignored, exactly like the explicit dimensions above). Default [0, 0, 0].
@@ -81,15 +101,22 @@ export class Shape extends Aspect<"shape", Node> {
    * you would expect. With no `origin` an auto shape (`{}`) still centres itself on the node's own
    * mesh bounds — only explicit dimensions sit on the pivot by default.
    */
-  origin?: Vec3Like
-  /** Whether pointer rays can hit this shape (click / touchstart). Default true. */
-  raycast = true
+  get origin(): Vec3Like | undefined { return this._origin }
+  set origin(v: Vec3Like | undefined) { this._origin = v; this._changed() }
+  /** Whether pointer rays can hit this shape (click / touchstart). Default true. Live, at once. */
+  get raycast(): boolean { return this._raycast }
+  set raycast(v: boolean) { this._raycast = v; if (this._bodyId) _creator.physicsSetPickable(this._bodyId, v) }
+
+  /** Scene-editor inspector: the geometry fields (accessors, so they are listed here by name). */
+  static fields: FieldMeta<Shape> = {
+    box: {}, sphere: {}, cylinder: {}, capsule: {}, mesh: {}, heightfield: {}, origin: {}, raycast: {},
+  }
 
   private _shapeId = 0
   private _bodyId = 0
   /** Centre the "auto" box measured for itself — used when `origin` isn't set explicitly. */
   private _autoOrigin: [number, number, number] | null = null
-  /** Geometry props as of the last build (see onReconfigure). */
+  /** Geometry props as of the last build (see _changed). */
   private _sig = ""
 
   /** @internal native shape id (0 if the build has no physics). */
@@ -110,11 +137,10 @@ export class Shape extends Aspect<"shape", Node> {
     this.node._xfKind = 0
   }
 
-  /** Re-configuring (`node.aspect(Shape, { origin })`) rebuilds the geometry when a dimension, the
-   *  kind or the origin changed, and re-applies pickability. The body keeps its id and velocity. */
-  onReconfigure(): void {
-    if (this._signature() !== this._sig) this._rebuild()
-    if (this._bodyId) _creator.physicsSetPickable(this._bodyId, this.raycast)
+  /** A dimension, the kind or the origin was written: rebuild the geometry when it actually changed.
+   *  The body keeps its id and velocity. */
+  private _changed(): void {
+    if (this._shapeId && this._signature() !== this._sig) this._rebuild()
   }
 
   /**
@@ -134,14 +160,14 @@ export class Shape extends Aspect<"shape", Node> {
       console.warn(`Shape.fit: "${this.node.name}" has no geometry to measure yet (a model still loading, or a node with no mesh)`)
       return this
     }
-    this.box = f.box
-    this.sphere = f.sphere
-    this.cylinder = f.cylinder
-    this.capsule = f.capsule
-    if (kind === "mesh") this.mesh = true
-    else if (kind === "convex") this.mesh = "convex"
-    else if (kind !== undefined) this.mesh = undefined
-    this.origin = f.origin
+    this._box = f.box
+    this._sphere = f.sphere
+    this._cylinder = f.cylinder
+    this._capsule = f.capsule
+    if (kind === "mesh") this._mesh = true
+    else if (kind === "convex") this._mesh = "convex"
+    else if (kind !== undefined) this._mesh = undefined
+    this._origin = f.origin
     this._rebuild()
     return this
   }

package/src/gl/vehicle/Vehicle.ts

@@ -28,8 +28,8 @@
 // `Wheel` aspect of the wheel's own node (which is where Jolt keeps it too); Vehicle collects every
 // Wheel under itself and groups them into axles by Z.
 //
-// The engine gets NUMBERS: the blob of settings (`_buildSettings`, live re-tunable) and one input
-// vector per frame. It never shapes them — no taper, no rate limit, no gearbox, no idle governor.
+// The engine gets NUMBERS: the blob of settings (`_buildSettings`: its tuning half re-sent from
+// `flush()` whenever a live value of the car or a wheel is written) and one input vector per frame. It never shapes them — no taper, no rate limit, no gearbox, no idle governor.
 //
 // Chassis space is forward −Z / up +Y — the SDK's own convention, the one `node.forward` reports: if
 // the model faces the other way, rotate the MODEL (a child), never the chassis node. Physics owns the
@@ -175,6 +175,12 @@ export interface AeroConfig {
   drag?: number
 }
 
+// The three groups' defaults — every key the live views carry (a key left out of an assigned object
+// takes the value here). `curve` / `feedback` / `driver` default to "not given", as the blob reads them.
+const ENGINE_DEFAULTS: EngineConfig = { torque: 500, maxRpm: 6000, idleRpm: 1000, curve: undefined, inertia: 0.5, braking: 0.2 }
+const STEERING_DEFAULTS: SteeringConfig = { maxAngle: 35, caster: 0.03, trail: 0.025, trailAtPeak: 0.5, feedback: undefined, driver: undefined }
+const AERO_DEFAULTS: AeroConfig = { downforce: 0, drag: 0.03 }
+
 /** Blob v15 — see bridges.d.ts for the field-by-field layout. */
 const BLOB_VERSION = 15
 const BLOB_HEADER = 34
@@ -199,21 +205,42 @@ export class Vehicle extends Aspect<"vehicle", Node> {
    *  (`id` stays 0, with a warning). */
   static get supported(): boolean { return Physics.supported && typeof _creator.vehicleCreate === "function" }
 
-  /** Chassis mass in kg (default 1200). Wheels are massless in this model. */
-  mass = 1200
+  // ---- the car as hardware. LIVE (a write reaches the engine before the next step — a drift button
+  // is `car.vehicle.differential = 'locked'`): differential, antiRoll, maxTilt, friction,
+  // clutchStrength, clutchCapacity, and the three groups engine / steering / aero (write a field, or
+  // assign a whole object: what it leaves out is the default). STRUCTURAL (baked when the car is
+  // built — build it again with `car.aspect(Vehicle, {…})`, which resets its motion): mass,
+  // centerOfMass, driveAxle, and which wheels exist, where, with what width and travel.
+
+  private _mass = 1200
+  /** Chassis mass in kg (default 1200). Wheels are massless in this model. Structural: a write on a
+   *  live car warns and keeps the built mass. */
+  get mass(): number { return this._mass }
+  set mass(v: number) {
+    if (this._id && v !== this._builtMass) {
+      console.warn(`Vehicle: mass is fixed once the body exists (still ${this._builtMass} kg) — build the aspect again to change it`)
+      return
+    }
+    this._mass = v
+  }
   /** Centre of mass height in chassis space (metres, negative = lower). Left out, it drops to halfway
-   *  down the chassis shape — a car with its mass at the shape's centre tips over. */
+   *  down the chassis shape — a car with its mass at the shape's centre tips over. Structural. */
   centerOfMass?: number
   /** Which axle the engine drives (default "rear") — the default for every wheel's own `driven`
-   *  share: 1 on that axle, 0 elsewhere. `none` = no drive at all (a trailer, a pushed cart). */
+   *  share: 1 on that axle, 0 elsewhere. `none` = no drive at all (a trailer, a pushed cart). Structural. */
   driveAxle: DriveLayout = "rear"
+
+  private _differential: DifferentialMode | number = "lsd"
   /** Differential lock across each driven axle. `locked` is the drift setup — both wheels turn
-   *  together, so the pair lets go as a pair. Live: re-configure the aspect to switch it mid-drive. */
-  differential: DifferentialMode | number = "lsd"
+   *  together, so the pair lets go as a pair. Live: switch it mid-drive. */
+  get differential(): DifferentialMode | number { return this._differential }
+  set differential(v: DifferentialMode | number) { this._differential = v; this.dirty() }
+  private _antiRoll: boolean | number = true
   /**
    * Anti-roll bars between each axle's wheels — what stops a car rolling onto its inside wheels in a
    * fast corner. `true` (default) is a bar 0.01 as stiff as the wheel's own spring; a number is that
-   * ratio directly, and `0` / `false` removes the bars.
+   * ratio directly, and `0` / `false` removes the bars. Live: the stiffness, on axles built with a
+   * bar (`false` at build = no bar to stiffen later).
    *
    * **The numbers are far smaller than they look and the gain is steep** — Jolt's bar feeds
    * `lengthDifference × stiffness × dt` as a bias into the suspension's own soft constraint, so 4%
@@ -223,25 +250,44 @@ export class Vehicle extends Aspect<"vehicle", Node> {
    * This is the knob for how much a car visibly LEANS, not for wheel lift: bars change how far the
    * body tips, not how much load transfers. For lift, lower `centerOfMass`.
    */
-  antiRoll: boolean | number = true
-  /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. */
-  maxTilt = 60
+  get antiRoll(): boolean | number { return this._antiRoll }
+  set antiRoll(v: boolean | number) { this._antiRoll = v; this.dirty() }
+  private _maxTilt = 60
+  /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. Live. */
+  get maxTilt(): number { return this._maxTilt }
+  set maxTilt(v: number) { this._maxTilt = v; this.dirty() }
+  private _friction = DEFAULT_FRICTION
   /** Friction of the CHASSIS body itself — how it slides when it lands on its roof or side. Nothing
-   *  to do with the tires; those are the `Wheel`'s `tire` × the ground's friction. */
-  friction = DEFAULT_FRICTION
+   *  to do with the tires; those are the `Wheel`'s `tire` × the ground's friction. Live, at once. */
+  get friction(): number { return this._friction }
+  set friction(v: number) { this._friction = v; if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, v) }
+  private _clutchStrength = 10
   /** Strength of the clutch when fully engaged (default 10). Small values slip; large ones weld the
-   *  engine to the wheels. `clutch` (the input) scales it 0..1. */
-  clutchStrength = 10
+   *  engine to the wheels. `clutch` (the input) scales it 0..1. Live. */
+  get clutchStrength(): number { return this._clutchStrength }
+  set clutchStrength(v: number) { this._clutchStrength = v; this.dirty() }
+  private _clutchCapacity = 0
   /** The clutch's torque CAPACITY, N·m (default 0 = none: Jolt's viscous clutch alone, torque =
    *  `clutchStrength` × slip speed, no ceiling — rigid at any real slip). Set it and the clutch
    *  SLIPS at this much torque × `clutch` — a dry clutch, emulated a physics step at a time: a
    *  launch can be feathered, and a dumped clutch in too high a gear drags the engine down instead
-   *  of lurching. A road car's is ~1.5× the engine's peak torque. */
-  clutchCapacity = 0
-
-  engine: EngineConfig = { torque: 500, maxRpm: 6000, idleRpm: 1000, inertia: 0.5, braking: 0.2 }
-  steering: SteeringConfig = { maxAngle: 35 }
-  aero: AeroConfig = { downforce: 0, drag: 0.03 }
+   *  of lurching. A road car's is ~1.5× the engine's peak torque. Live. */
+  get clutchCapacity(): number { return this._clutchCapacity }
+  set clutchCapacity(v: number) { this._clutchCapacity = v; this.dirty() }
+
+  private _engine = this.live(ENGINE_DEFAULTS)
+  /** The engine (`EngineConfig`). Live: `car.vehicle.engine.torque = 800`, or assign a whole config. */
+  get engine(): EngineConfig { return this._engine }
+  set engine(v: EngineConfig) { this._engine = this.live(ENGINE_DEFAULTS, v); this.dirty() }
+  private _steering = this.live(STEERING_DEFAULTS)
+  /** The steering (`SteeringConfig`). Live, one level deep: `feedback` and `driver` are each
+   *  replaced as a whole (`steering.driver = { maxTorque: 90 }`), not edited inside. */
+  get steering(): SteeringConfig { return this._steering }
+  set steering(v: SteeringConfig) { this._steering = this.live(STEERING_DEFAULTS, v); this.dirty() }
+  private _aero = this.live(AERO_DEFAULTS)
+  /** Aerodynamics (`AeroConfig`). Live: a wing that deploys is `car.vehicle.aero.downforce = 0.6`. */
+  get aero(): AeroConfig { return this._aero }
+  set aero(v: AeroConfig) { this._aero = this.live(AERO_DEFAULTS, v); this.dirty() }
 
   /** Scene-editor inspector: the flat, tunable half. The grouped objects are edited in code. */
   static fields: FieldMeta<Vehicle> = {
@@ -276,9 +322,33 @@ export class Vehicle extends Aspect<"vehicle", Node> {
   private _input = new Float32Array(INPUT_FIXED)
   private _sent = new Float32Array(INPUT_FIXED)
   private _dirty = true          // an input write since the last send
-  private _retunePending = false
+  private _rebuildPending = false
+
+  onAttach(): void { this._setup(false) }
+  onDetach(): void { this._teardown() }
+
+  /** A live value changed on the car or a wheel: the tuning half of the blob is re-sent in
+   *  `flush()`, one send however many values changed this frame. */
+  protected flush(): void {
+    if (this._rebuildPending) {
+      // A wheel came or went: the constraint is built again around the wheels that are there now,
+      // where the car stands, its motion reset (the inputs are kept and re-sent).
+      this._rebuildPending = false
+      this._teardown()
+      this._setup(true)
+      return
+    }
+    if (this._id) _creator.vehicleSetTuning?.(this._id, this._buildSettings())
+  }
+
+  /** @internal A wheel's live value changed: retune with the next flush. */
+  _retune(): void { this.dirty() }
+  /** @internal A wheel was built or removed under a live car: rebuild with the next flush. */
+  _rebuildSoon(): void { if (this._id) { this._rebuildPending = true; this.dirty() } }
 
-  onAttach(): void {
+  // `rebuild` = from flush(), after a wheel change: an author error that attach throws on is a
+  // warning here, and the car stays torn down until the next change.
+  private _setup(rebuild: boolean): void {
     if (!Physics.supported) return
     if (!_creator.vehicleCreate) {
       console.warn("Vehicle: this host has no vehicle model (Vehicle.supported is false) — the car will not move")
@@ -297,7 +367,9 @@ export class Vehicle extends Aspect<"vehicle", Node> {
 
     this._wheels = this._collectWheels()
     if (this._wheels.length === 0) {
-      throw new Error("Vehicle found no wheels — put a Wheel aspect on each wheel node under the chassis: hubFL.aspect(Wheel)")
+      const msg = "Vehicle found no wheels — put a Wheel aspect on each wheel node under the chassis: hubFL.aspect(Wheel)"
+      if (rebuild) { console.warn(msg); return }
+      throw new Error(msg)
     }
 
     const shapeId = shape._claim()  // the vehicle owns the shape; drop the pick-only body
@@ -324,7 +396,7 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     this._dirty = true
   }
 
-  onDetach(): void {
+  private _teardown(): void {
     if (this._id) { _creator.vehicleDestroy(this._id); this._id = 0; this._bodyId = 0 }
     for (const w of this._wheels) w._vehicle = null
     this._wheels = []
@@ -333,31 +405,6 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     this.node.get(Shape)?._recreatePickBody()   // hands the routing back to the pick body
   }
 
-  /**
-   * Re-configuring an attached vehicle retunes it in place — the way a drift button switches the
-   * differential without the car so much as blinking:
-   *
-   *   car.aspect(Vehicle, { differential: drift ? 'locked' : 'lsd' })
-   *
-   * Live: `differential`, `engine`, `steering`, `aero`, `maxTilt`, `friction`, `clutchStrength`,
-   * `clutchCapacity`, `antiRoll` (its stiffness, on axles that have a bar), and every `Wheel`'s
-   * `tire`. Everything else describes the car's STRUCTURE — `mass`, `centerOfMass`, which wheels
-   * exist and where, their suspension, the driven shares — and is baked into the constraint at
-   * attach; to change one of those, re-attach the aspect.
-   */
-  onReconfigure(): void {
-    if (!this._id) return
-    if (this.mass !== this._builtMass) {
-      console.warn(`Vehicle: mass is fixed once the body exists (still ${this._builtMass} kg) — re-add the aspect to change it`)
-      this.mass = this._builtMass
-    }
-    this._retunePending = true
-    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.friction)
-  }
-
-  /** @internal A wheel's tire changed: re-send the tuning before the next step (one send however
-   *  many wheels changed this frame). */
-  _retuneSoon(): void { this._retunePending = true }
 
   /** Native vehicle id (0 until attached / no physics support). */
   get id(): number { return this._id }
@@ -395,15 +442,12 @@ export class Vehicle extends Aspect<"vehicle", Node> {
   /**
    * EARLY phase: hand this frame's inputs to the engine, before the step. The vector is sent when
    * anything changed — and every frame while a throttle, steer or brake is non-zero, because that is
-   * what keeps a driven car awake (an idle car with zero input sleeps). The pending re-tune (a
-   * config or tire change) goes first, so the step runs on the new numbers.
+   * what keeps a driven car awake (an idle car with zero input sleeps). A pending re-tune (a live
+   * value of the car or a wheel changed) went out in `flush()`, before this phase, so the step runs
+   * on the new numbers.
    */
   protected updateBefore(): void {
     if (!this._id) return
-    if (this._retunePending) {
-      this._retunePending = false
-      _creator.vehicleSetTuning?.(this._id, this._buildSettings())
-    }
     const input = this._input
     input[0] = this._throttle
     input[1] = this._steer
@@ -567,7 +611,7 @@ export class Vehicle extends Aspect<"vehicle", Node> {
       const w = found[i]!
       const a = axleOf[i]!
       const measured = w._measure()
-      w.radius ??= measured.radius
+      w._radius ??= measured.radius
       w.width ??= measured.width
       w.steer ??= a === 0
       w.driven ??= this.driveAxle === "none" ? 0 : this.driveAxle === "all" ? 1 : (this.driveAxle === "front" ? a === 0 : a === maxAxle) ? 1 : 0

package/src/gl/vehicle/Wheel.ts

@@ -138,13 +138,28 @@ export function resolveTire(tire: Tire): ResolvedTire {
   }
 }
 
+/** `suspension`'s defaults — every key the live view carries. */
+const SUSPENSION_DEFAULTS: Required<WheelSuspension> = { travel: 0.4, stiffness: 1.4, damping: 0.5 }
+
+/**
+ * One wheel. LIVE: `radius`, `suspension.stiffness` / `damping` and `tire` — write them and the car
+ * retunes before the next step (a tire losing air: `wheel.radius *= 0.9`, `wheel.suspension.stiffness
+ * *= 0.7`, `wheel.tire = Tire.scale(wheel.tire, 0.5)`). STRUCTURAL: `width`, `suspension.travel`, `axle`,
+ * `steer`, `driven` — baked when the car is built; to change one, build the wheel again
+ * (`hub.aspect(Wheel, {…})` — the car rebuilds itself around it, its motion reset).
+ */
 export class Wheel extends Aspect<"wheel", Node> {
   static readonly aspect = "wheel"
 
+  /** @internal the radius as given, or as measured at bind (`radius` reads it). */
+  _radius?: number
   /** Wheel radius in metres. Default: measured from the node's rendered bounds, else 0.35. Too small
-   *  and the car scrapes, too large and it floats. */
-  radius?: number
-  /** Wheel width in metres. Default: measured, else 0.25. */
+   *  and the car scrapes, too large and it floats. Live: the ROLLING radius — the suspension hangs
+   *  where it was built, so a smaller one lowers that corner of the car, the way a tire losing air
+   *  does; the wheel's inertia keeps the radius it was built with. */
+  get radius(): number | undefined { return this._radius }
+  set radius(v: number | undefined) { this._radius = v; this.dirty() }
+  /** Wheel width in metres. Default: measured, else 0.25. Structural. */
   width?: number
   /** Axle group, front to back. Default: derived from Z. Set it for a car whose wheels are not in neat
    *  left/right pairs — an axle's wheels are paired for the differential and the anti-roll bar. */
@@ -157,10 +172,20 @@ export class Wheel extends Aspect<"wheel", Node> {
    *  `0.2` on each rear. Structural: baked at attach. */
   driven?: number
 
-  suspension: WheelSuspension = { travel: 0.4, stiffness: 1.4, damping: 0.5 }
-  /** The tire (default `Tire.road()`). Live: re-assign it or re-configure the aspect and the car
-   *  retunes in place — a grip slider, a tire that heats up. */
-  tire: Tire = Tire.road()
+  private _suspension = this.live(SUSPENSION_DEFAULTS)
+  /** The suspension. Live: `stiffness` and `damping` (a softer corner sags and rolls more) — write a
+   *  field (`wheel.suspension.stiffness = 1`) or assign a whole object (what it leaves out is the
+   *  default). `travel` is structural. */
+  get suspension(): WheelSuspension { return this._suspension }
+  set suspension(v: WheelSuspension) { this._suspension = this.live(SUSPENSION_DEFAULTS, v); this.dirty() }
+
+  private _tire = this.live(Tire.road())
+  /** The tire (default `Tire.road()`). Live: assign one (`wheel.tire = Tire.drift()`, or
+   *  `Tire.scale(wheel.tire, 0.5)` for a grip slider, a tire that heats up) or write a field
+   *  (`wheel.tire.traction = 1`); a curve is replaced, never edited in place. A tire assigned without
+   *  `traction` / `circle` gets `road`'s. */
+  get tire(): Tire { return this._tire }
+  set tire(v: Tire) { this._tire = this.live(Tire.road(), v); this.dirty() }
 
   /** INPUT: brake torque on this wheel THIS frame, N·m (default 0). Sticky, like `Vehicle.throttle`:
    *  write it every frame from a driver system's `updateBefore` — the foot brake's share, the
@@ -189,15 +214,24 @@ export class Wheel extends Aspect<"wheel", Node> {
   /** @internal Resting centre in chassis space (what the author placed). */
   _rest = new Vec3()
 
+  /** A wheel built under a car that already runs (`hub.aspect(Wheel, {…})` on a live car): the car
+   *  rebuilds itself around the new set of wheels before the next step. */
+  onAttach(): void {
+    for (let n: Node | null = this.node.parent; n; n = n.parent) {
+      const v = (n as unknown as { vehicle?: Vehicle }).vehicle
+      if (v) { v._rebuildSoon(); return }
+    }
+  }
+
   onDetach(): void {
+    this._vehicle?._rebuildSoon()   // one wheel fewer: the car is built again around what is left
     this._vehicle = null
     this._index = -1
   }
 
-  /** Re-configuring a wheel on a live car retunes the car: the tire is live; size, suspension, the
-   *  driven share and the axle are structural (re-attach the Vehicle). */
-  onReconfigure(): void {
-    this._vehicle?._retuneSoon()
+  /** A live value changed (the tire, the radius, the spring): the car retunes in the same flush. */
+  protected flush(): void {
+    this._vehicle?._retune()
   }
 
   /** @internal Called by Vehicle once the car exists, with the geometry it resolved. */

package/src/plugins/gen/ar/contract.d.ts

@@ -5,6 +5,10 @@
 // camera and background the session drives every frame through the host's gl facade.
 // A session is ONE AR scene: ARScene opens it with the scene and its camera entity as params and
 // closes it with the scene. `@permission camera` on start: the host asks, the halves never do.
+// What a session finds in the camera's picture and drives an entity to: an image target (a printed
+// picture, by its bytes) and, since contract version 2, a QR code (a printed symbol, by its text) —
+// both through the `image` event. Codes are the web's (WebXR) first: the native halves take them and
+// say they track none yet.
 import type { Service, File, Entity, Scene3D, f64 } from "../../../plugin"
 
 export type ARMode = "world" | "images"
@@ -31,6 +35,20 @@ export interface ImageTarget {
   entity: Entity
 }
 
+/** A printed QR code the session tracks: found by its text in the camera's picture; while
+ *  tracked its entity is driven like an image target's — a rigid pose in metres, no scale — the
+ *  symbol's centre, Y out of it, X along its top edge, Z towards its bottom. Web (WebXR) first;
+ *  the native halves later. */
+export interface QRTarget {
+  /** The code's text: a symbol with another text is not this target. "" = ANY code (the first
+   *  one decoded): a test, or a plaque whose text is not known to the app. */
+  text: string
+  /** The printed side of the symbol (its modules, no quiet zone), metres. */
+  size: f64
+  /** The entity that follows the code (its Anchor node). */
+  entity: Entity
+}
+
 export interface StartOptions {
   /** Default "world". "images": image tracking only (no planes, no hit test; iOS runs
    *  ARImageTrackingConfiguration, which is lighter). */
@@ -38,6 +56,9 @@ export interface StartOptions {
   /** Default "horizontal". Ignored in "images". */
   planes?: PlaneDetection
   images?: ImageTarget[]
+  /** The QR codes to track (in "world" and in "images"); a half without them says so and drives
+   *  none. @since 2 */
+  codes?: QRTarget[]
   /** Default "gravity". "gravityAndHeading": -Z points north (the compass). */
   worldAlignment?: WorldAlignment
   /** Deliver `light` events. Default false. */
@@ -76,7 +97,8 @@ export interface AREvents {
   /** An image target found, lost, or its size refined. While tracked its entity is driven: a rigid
    *  pose in metres, no scale — the image's centre, Y out of it, the image in XZ (X along its width,
    *  Z towards its bottom). `extent` = [width, height] metres, the framework's estimate (sent again
-   *  when it changes by a millimetre, at most 10 per second); the last one when lost. */
+   *  when it changes by a millimetre, at most 10 per second); the last one when lost. A QR target's
+   *  comes the same way (its frame: X along the symbol's top edge), `extent` = [size, size]. */
   image: { entity: Entity, tracked: boolean, extent: f64[] }
   /** An anchor made by `anchor()` lost or regained after a relocalization. */
   anchor: { entity: Entity, tracked: boolean }
@@ -86,6 +108,11 @@ export interface AREvents {
   /** The session failed and is over: "unavailable" (no ARKit / ARCore support, ARCore not
    *  installed and declined), "camera" (the camera could not be used), "failed". */
   error: { code: ARErrorCode, message: string }
+  /** The session is over, and not by `stop()`: the user left it ("user" — the browser's back / exit
+   *  of an immersive WebXR session) or the system took it ("system"). Not an error: ARScene closes
+   *  the scene. ARKit and ARCore never end a session by themselves (an interruption is `tracking`
+   *  limited): the native halves do not send it. @since 2 */
+  ended: { reason: "user" | "system" }
 }
 
 export interface AR extends Service<"ar", ARParams, AREvents> {
@@ -102,6 +129,13 @@ export interface AR extends Service<"ar", ARParams, AREvents> {
    *  `StartOptions.images`.
    *  @rejects notRunning failed */
   setImages(images: ImageTarget[]): Promise<void>
+  /** The twin of `setImages` for QR codes: replace the set of QR targets of a RUNNING session
+   *  without restarting it; a code no longer in the set stops driving its entity (`tracked: false`
+   *  once if it was tracked). Before `start`, the codes are `StartOptions.codes`. A half that tracks
+   *  no codes yet (the native ones) rejects "failed".
+   *  @since 2
+   *  @rejects notRunning failed */
+  setCodes(codes: QRTarget[]): Promise<void>
   /** What is under a point of the scene's view — in its touches' space (a scene touch's `clientX` /
    *  `clientY`: the units of the gl facade's viewport) — nearest first. Empty when nothing is, or on
    *  a host without surfaces (the web).