lecodes-cli 0.17.2 → 0.18.0

package/runtime/sdk/gl/Physics.ts

@@ -1,126 +1,171 @@
-// Rigid body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl. Requires a Shape
-// aspect on the same node (its geometry becomes the body's collision shape).
-//
-//   Physics.configure({ gravity: [0, -9.81, 0] })          // once, before creating bodies
-//   ground.aspect(Shape, { box: [20, 0.5, 20] }).aspect(Physics, { motion: 'static' })
-//   crate.aspect(Shape, {}).aspect(Physics, { mass: 2 })   // auto box from the mesh
-//   crate.physics.applyImpulse([0, 6, 0])
-//   crate.addEventListener('enter', other => …)            // contact / trigger overlap began
-//
-// For a `dynamic` body, physics OWNS the transform — do NOT set node.position per frame; drive it via
-// velocity / applyImpulse. Reading node.position is free (native already wrote it). Kinematic bodies
-// are driven with moveTo.
-
-import { Aspect } from "../core/Aspect"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { nodeRegistry, type Node } from "./Node"
-import { Shape } from "./Shape"
-
-export type MotionType = "static" | "dynamic" | "kinematic"
-const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
-
-export interface PhysicsConfig {
-  /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
-  gravity?: Vec3Like
-  /** Max simultaneous bodies (resizes the world; only before any body exists). Default 4096. */
-  maxBodies?: number
-}
-
-/** Closest raycast hit. */
-export interface RayHit {
-  node: Node | null
-  point: Vec3
-  normal: Vec3
-  fraction: number
-}
-
-export class Physics extends Aspect<"physics", Node> {
-  static readonly aspect = "physics"
-
-  /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
-   *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
-   *  smoothness — bodies then advance in discrete steps. */
-  private static _interpolation = true
-  static get interpolation(): boolean { return Physics._interpolation }
-  static set interpolation(on: boolean) { Physics._interpolation = on; _creator.setInterpolation(on) }
-
-  /** Default "dynamic". */
-  motion: MotionType = "dynamic"
-  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
-  mass = 1
-
-  private _bodyId = 0
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
-    if (!shape) {
-      throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
-    }
-    if (this.motion === "dynamic" && shape._isTriangleMesh) {
-      throw new Error("Physics: a dynamic body cannot use Shape { mesh: true } (triangle meshes are static/kinematic only) — use { mesh: 'convex' } or a primitive shape")
-    }
-    const shapeId = shape._claim() // drop the pick-only body; reuse its shape
-    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
-    shape._ownBody(this._bodyId)
-  }
-
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    const shape = this.node.get(Shape)
-    if (shape) {
-      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
-      shape._recreatePickBody()  // keep the node pickable if the Shape stays
-    }
-  }
-
-  /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
-  get id(): number { return this._bodyId }
-
-  /** Linear velocity in world units/second (fresh Vec3 on read). */
-  get velocity(): Vec3 {
-    const out = new Float32Array(3)
-    if (this._bodyId) _creator.physicsGetLinearVelocity(this._bodyId, out)
-    return new Vec3(out[0], out[1], out[2])
-  }
-  set velocity(v: Vec3Like) {
-    if (this._bodyId) _creator.physicsSetLinearVelocity(this._bodyId, cx(v), cy(v), cz(v))
-  }
-
-  /** Apply an instantaneous impulse (kg·m/s) and wake the body. */
-  applyImpulse(v: Vec3Like): this {
-    if (this._bodyId) _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v))
-    return this
-  }
-
-  /** Teleport / drive a kinematic (or dynamic) body to a world position. */
-  moveTo(p: Vec3Like): this {
-    if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p))
-    return this
-  }
-
-  // --- world (static) -------------------------------------------------------------------------
-  /** Configure gravity / limits. Call once before creating bodies. */
-  static configure(config: PhysicsConfig = {}): void {
-    const g = config.gravity ?? [0, -9.81, 0]
-    _creator.physicsConfigure(cx(g), cy(g), cz(g), config.maxBodies ?? 0)
-  }
-
-  /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
-  static get supported(): boolean {
-    return !!_creator.physicsHasSupport && _creator.physicsHasSupport()
-  }
-
-  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
-  static raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000): RayHit | null {
-    const out = new Float32Array(7)
-    const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
-    if (!id) return null
-    return {
-      node: nodeRegistry.get(id) ?? null,
-      point: new Vec3(out[0], out[1], out[2]),
-      normal: new Vec3(out[3], out[4], out[5]),
-      fraction: out[6],
-    }
-  }
-}
+// Rigid body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl. Requires a Shape
+// aspect on the same node (its geometry becomes the body's collision shape).
+//
+//   Physics.configure({ gravity: [0, -9.81, 0] })          // once, before creating bodies
+//   ground.aspect(Shape, { box: [20, 0.5, 20] }).aspect(Physics, { motion: 'static' })
+//   crate.aspect(Shape, {}).aspect(Physics, { mass: 2 })   // auto box from the mesh
+//   crate.physics.applyImpulse([0, 6, 0])
+//   crate.addEventListener('enter', other => …)            // contact / trigger overlap began
+//
+// For a `dynamic` body, physics OWNS the transform — do NOT set node.position per frame; drive it via
+// velocity / applyImpulse. Reading node.position is free (native already wrote it). Kinematic bodies
+// are driven with moveTo.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import { nodeRegistry, type Node } from "./Node"
+import { Shape } from "./Shape"
+
+export type MotionType = "static" | "dynamic" | "kinematic"
+const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
+
+export interface PhysicsConfig {
+  /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
+  gravity?: Vec3Like
+  /** Max simultaneous bodies (resizes the world; only before any body exists). Default 4096. */
+  maxBodies?: number
+}
+
+/** Closest raycast hit. */
+export interface RayHit {
+  node: Node | null
+  point: Vec3
+  normal: Vec3
+  fraction: number
+}
+
+export class Physics extends Aspect<"physics", Node> {
+  static readonly aspect = "physics"
+
+  /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
+   *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
+   *  smoothness — bodies then advance in discrete steps. */
+  private static _interpolation = true
+  static get interpolation(): boolean { return Physics._interpolation }
+  static set interpolation(on: boolean) { Physics._interpolation = on; _creator.setInterpolation(on) }
+
+  /** Default "dynamic". */
+  motion: MotionType = "dynamic"
+  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
+  mass = 1
+  /**
+   * Surface friction: 0 = ice, ~1 = grippy asphalt, and values above 1 are allowed (rubber on
+   * tarmac).
+   *
+   * The engine COMBINES the two touching bodies as `sqrt(a * b)`, so the LOWER value dominates and
+   * the floor caps everything standing on it. The default **0.6** is a neutral solid surface (the
+   * raw Jolt default of 0.2 is ice by game standards); dry tarmac a car should corner on wants a
+   * `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). It is a PLAIN FIELD on purpose: an accessor pair would be tree-shaken out of the
+   * bundle, because passing `{ friction }` in a config object is not a member reference the
+   * bundler can see, and the write would then silently land on a dead property.
+   */
+  friction = 0.6
+
+  /** Scene-editor inspector: `motion` as a dropdown (a string default alone infers a text box). */
+  static fields: FieldMeta<Physics> = {
+    motion: { options: [ "static", "kinematic", "dynamic" ] },
+    mass: { min: 0, step: 0.1 },
+    friction: { min: 0, max: 2, step: 0.05 },
+  }
+
+  private _bodyId = 0
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
+    }
+    if (this.motion === "dynamic" && shape._isTriangleMesh) {
+      throw new Error("Physics: a dynamic body cannot use Shape { mesh: true } (triangle meshes are static/kinematic only) — use { mesh: 'convex' } or a primitive shape")
+    }
+    const shapeId = shape._claim() // drop the pick-only body; reuse its shape
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
+    this._applyFriction()
+    shape._ownBody(this._bodyId)
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()  // keep the node pickable if the Shape stays
+    }
+  }
+
+  /** Re-configuring (`node.aspect(Physics, { friction })`) pushes the new surface to the live body. */
+  onReconfigure(): void { this._applyFriction() }
+
+  private _applyFriction(): void {
+    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.friction)
+  }
+
+  /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
+  get id(): number { return this._bodyId }
+
+  /** Linear velocity in world units/second (fresh Vec3 on read). */
+  get velocity(): Vec3 {
+    const out = new Float32Array(3)
+    if (this._bodyId) _creator.physicsGetLinearVelocity(this._bodyId, out)
+    return new Vec3(out[0], out[1], out[2])
+  }
+  set velocity(v: Vec3Like) {
+    if (this._bodyId) _creator.physicsSetLinearVelocity(this._bodyId, cx(v), cy(v), cz(v))
+  }
+
+  /** Apply an instantaneous impulse (kg·m/s) and wake the body. */
+  applyImpulse(v: Vec3Like): this {
+    if (this._bodyId) _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v))
+    return this
+  }
+
+  /** The same impulse applied at a WORLD-SPACE point instead of the centre of mass: the lever arm
+   *  becomes angular impulse, so the body spins as well as moves (a bullet hitting a crate off
+   *  centre, a blast lifting it by its base). Falls back to the central impulse on an older host. */
+  applyImpulseAt(v: Vec3Like, point: Vec3Like): this {
+    if (!this._bodyId) return this
+    if (_creator.physicsApplyImpulseAt) {
+      _creator.physicsApplyImpulseAt(this._bodyId, cx(v), cy(v), cz(v), cx(point), cy(point), cz(point))
+    } else {
+      _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v))
+    }
+    return this
+  }
+
+  /** Teleport / drive a kinematic (or dynamic) body to a world position. */
+  moveTo(p: Vec3Like): this {
+    if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p))
+    return this
+  }
+
+  // --- world (static) -------------------------------------------------------------------------
+  /** Configure gravity / limits. Call once before creating bodies. */
+  static configure(config: PhysicsConfig = {}): void {
+    const g = config.gravity ?? [0, -9.81, 0]
+    _creator.physicsConfigure(cx(g), cy(g), cz(g), config.maxBodies ?? 0)
+  }
+
+  /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
+  static get supported(): boolean {
+    return !!_creator.physicsHasSupport && _creator.physicsHasSupport()
+  }
+
+  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+  static raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000): RayHit | null {
+    const out = new Float32Array(7)
+    const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
+    if (!id) return null
+    return {
+      node: nodeRegistry.get(id) ?? null,
+      point: new Vec3(out[0], out[1], out[2]),
+      normal: new Vec3(out[3], out[4], out[5]),
+      fraction: out[6],
+    }
+  }
+}

package/runtime/sdk/gl/Scene.ts

@@ -33,8 +33,18 @@ export type SceneOptions = {
   toneMapping?: "aces" | "neutral" | "linear" | "filmic"
   /** Skybox / clear color. */
   skybox?: ColorInput
-  /** Multisample anti-aliasing. */
-  antialias?: boolean
+  /** Multisample anti-aliasing: `true` = 4×, `2`/`4` = that many samples, `false` = off (FXAA
+   *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
+   *  fill-rate cost after resolution — turn it down on big screens before anything else. */
+  antialias?: boolean | 2 | 4
+  /** Render the 3D at this fraction of the viewport (0.25–1) and upscale; the UI stays at native
+   *  resolution. A fixed, predictable cut of per-pixel GPU work — `0.75` is ~45 % cheaper and
+   *  barely visible in motion, `0.5` quarters it. Headless renders ignore it. */
+  renderScale?: number
+  /** Let the engine shrink the 3D buffers under `renderScale` only when frames run over budget
+   *  (Filament dynamic resolution, sharpened upscale) down to `min` (default 0.5). Off by default:
+   *  it makes the output frame-time dependent, so flow tests / headless renders never enable it. */
+  dynamicResolution?: boolean | { min?: number }
 }
 
 // Route aspect update(dt) through the render-synced native phases (render() early = before physics,
@@ -92,7 +102,21 @@ export class Scene implements Presentable {
       _creator.setToneMapping?.(this._id, { neutral: 1, linear: 2, filmic: 3 }[options.toneMapping] ?? 0)
     }
     if (options.skybox !== undefined) _creator.setSkybox(this._id, Color.toPackedRgb(options.skybox))
-    if (options.antialias) _creator.setSceneMultiSampleAntiAliasing(this._id, true, 4)
+    if (options.antialias !== undefined) {
+      const a = options.antialias
+      // `false` must reach the host: desktop defaults to 4× MSAA, so an explicit off is a real change.
+      _creator.setSceneMultiSampleAntiAliasing(this._id, a !== false, typeof a === "number" ? a : 4)
+    }
+    if (options.renderScale !== undefined || options.dynamicResolution) {
+      this.setRenderOptions(options.renderScale ?? 1, options.dynamicResolution ?? false)
+    }
+  }
+
+  /** Runtime form of `renderScale` / `dynamicResolution` (a graphics-settings menu). `renderScale`
+   *  0.25–1; older hosts without the method ignore it. */
+  setRenderOptions(renderScale: number, dynamicResolution: boolean | { min?: number } = false): void {
+    const min = typeof dynamicResolution === "object" ? (dynamicResolution.min ?? 0.5) : 0.5
+    _creator.setSceneRenderOptions?.(this._id, renderScale, !!dynamicResolution, min)
   }
 
   /** Scene occlusion material. */

package/runtime/sdk/gl/Shape.ts

@@ -8,15 +8,42 @@
 //   wall.aspect(Shape, { box: [1, 2, 1] }).aspect(Physics, { motion: 'static' })
 //   coin.aspect(Shape, { sphere: 0.5 }).aspect(Trigger)
 //   crate.aspect(Shape, {}).aspect(Physics)                 // auto box from the mesh AABB × world scale
+//   barrel.aspect(Shape, { capsule: {…}, origin: [0, 0.9, 0] })   // collider lifted off the pivot
+//   tree.aspect(Shape, {}).shape.fit('capsule')             // dimensions measured from the model
 //
 // Explicit dims are world-space half-extents (not scaled by the node). Use {} ("auto") to track the
-// mesh × world scale. Note: a Shape-only pick body is a STATIC snapshot at attach time — for a moving
-// pickable object add a Physics body (which follows the sim), rather than relying on the pick body.
+// mesh × world scale. `origin` moves the shape off the node's pivot (world units, in the node's
+// rotated frame) — the usual case is a model whose art sits above its origin. Note: a Shape-only
+// pick body is a STATIC snapshot at attach time — for a moving pickable object add a Physics body
+// (which follows the sim), rather than relying on the pick body.
 
 import { Aspect } from "../core/Aspect"
 import { cx, cy, cz, type Vec3Like } from "../math/vec"
 import type { Node } from "./Node"
 
+/** Which geometry a Shape uses — the one-of the fields below encode (see `_build`'s order). */
+export type ShapeKind = "auto" | "box" | "sphere" | "cylinder" | "capsule" | "mesh" | "convex"
+
+/** A node-local AABB, in the node's OWN frame (its own transform excluded), before world scale. */
+export type ShapeBounds = { min: [number, number, number], max: [number, number, number] }
+
+/** Dimensions measured from a node's rendered geometry — what `Shape.fit` writes, and the numbers
+ *  the scene editor's "Fit to mesh" button puts in the file. Exactly one dimension key is set (none
+ *  for a mesh/convex kind, whose geometry is the mesh itself); `origin` centres it on the art. */
+export type ShapeFit = {
+  box?: [number, number, number]
+  sphere?: number
+  cylinder?: { halfHeight: number, radius: number }
+  capsule?: { halfHeight: number, radius: number }
+  origin: [number, number, number]
+}
+
+/** Half-extents below this collapse a shape (Jolt refuses a box thinner than its convex radius,
+ *  and a zero-radius sphere) — a fitted plane or a decal quad lands here. */
+const MIN_HALF = 0.001
+const r4 = (v: number): number => Math.round(v * 1e4) / 1e4
+const dim = (v: number): number => Math.max(MIN_HALF, r4(v))
+
 export class Shape extends Aspect<"shape", Node> {
   static readonly aspect = "shape"
 
@@ -33,11 +60,29 @@ export class Shape extends Aspect<"shape", Node> {
    *  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"
+  /**
+   * 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].
+   *
+   * A model's pivot is rarely its centre of volume (a character stands ON its origin, a wheel hangs
+   * off its axle), so a collider centred on the pivot is half sunk into the floor. `origin` lifts it
+   * without moving the node: `{ capsule: { halfHeight: 0.6, radius: 0.3 }, origin: [0, 0.9, 0] }`.
+   * `fit()` and the scene editor's "Fit to mesh" fill it in from the rendered bounds.
+   *
+   * On a DYNAMIC body the offset also moves the centre of mass, so a lopsided collider tips the way
+   * 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
 
   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). */
+  private _sig = ""
 
   /** @internal native shape id (0 if the build has no physics). */
   get shapeId(): number { return this._shapeId }
@@ -55,6 +100,112 @@ export class Shape extends Aspect<"shape", Node> {
     if (this._shapeId) { _creator.physicsDestroyShape(this._shapeId); this._shapeId = 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)
+  }
+
+  /**
+   * Measure the node's rendered geometry and size the collider to it — the code half of the scene
+   * editor's "Fit to mesh". Keeps the current kind unless one is passed; `auto` becomes an explicit
+   * box, and a mesh/convex shape only has its `origin` cleared (its geometry IS the mesh).
+   *
+   *   crate.aspect(Shape, {}).shape.fit()             // box around what the model actually draws
+   *   hero.aspect(Shape, {}).shape.fit('capsule')     // capsule of the same height + girth
+   *
+   * A model loads asynchronously, so fit AFTER its `load()` resolves — an empty subtree measures as
+   * nothing and the call is a no-op (it warns). Rebuilds the live shape, keeping the body.
+   */
+  fit(kind?: ShapeKind): this {
+    const f = Shape.fitTo(this.node, kind ?? this.kind)
+    if (!f) {
+      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._rebuild()
+    return this
+  }
+
+  /** Which geometry this shape currently uses (the `_build` dispatch, as a name). */
+  get kind(): ShapeKind {
+    if (this.mesh === "convex") return "convex"
+    if (this.mesh) return "mesh"
+    if (this.sphere !== undefined) return "sphere"
+    if (this.cylinder) return "cylinder"
+    if (this.capsule) return "capsule"
+    if (this.box) return "box"
+    return "auto"
+  }
+
+  // ---- fitting (static, so the scene-editor harness can measure without attaching) -------------
+
+  /**
+   * The node's subtree AABB in its OWN local frame (its own transform excluded), or null when there
+   * is nothing to measure. Reads the engine's bounds — which cover a loaded GLB and every child —
+   * and falls back to a Mesh node's own CPU geometry on hosts without them.
+   */
+  static boundsOf(node: Node): ShapeBounds | null {
+    const box = _creator.computeBoundingBox?.(node.id)
+    if (box && (box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) {
+      return { min: [box[0], box[1], box[2]], max: [box[3], box[4], box[5]] }
+    }
+    const v = node.geometry?.vertices
+    if (!v || v.length < 3) return null
+    const min: [number, number, number] = [Infinity, Infinity, Infinity]
+    const max: [number, number, number] = [-Infinity, -Infinity, -Infinity]
+    for (let i = 0; i + 2 < v.length; i += 3) {
+      for (let k = 0; k < 3; k++) {
+        if (v[i + k] < min[k]) min[k] = v[i + k]
+        if (v[i + k] > max[k]) max[k] = v[i + k]
+      }
+    }
+    return isFinite(min[0]) ? { min, max } : null
+  }
+
+  /**
+   * Dimensions + origin that make `kind` hug what `node` renders — world units, so the node's world
+   * scale is baked in exactly as the Shape fields expect. Null when the node has no geometry (a
+   * model that hasn't loaded, an empty).
+   */
+  static fitTo(node: Node, kind: ShapeKind = "box"): ShapeFit | null {
+    const b = Shape.boundsOf(node)
+    return b ? Shape.fitBounds(b, node.worldScale, kind) : null
+  }
+
+  /**
+   * The measuring itself, over plain numbers: a node-local AABB + the node's world scale in, shape
+   * dimensions out. Separate from `fitTo` so the scene-editor harness can measure a node from
+   * ANOTHER bundle without touching accessors the bundler may have shaken out of it.
+   *
+   * A sphere takes the LARGEST half-extent and a cylinder/capsule the larger of X/Z, so the fit
+   * reads as the object's silhouette rather than as an enclosing ball; adjust from there.
+   */
+  static fitBounds(bounds: ShapeBounds, scale: Vec3Like, kind: ShapeKind = "box"): ShapeFit {
+    const sc = [Math.abs(cx(scale)), Math.abs(cy(scale)), Math.abs(cz(scale))]
+    const half = [0, 1, 2].map((k) => (bounds.max[k] - bounds.min[k]) * 0.5 * sc[k])
+    const origin = [0, 1, 2].map((k) => r4((bounds.max[k] + bounds.min[k]) * 0.5 * sc[k])) as [number, number, number]
+    if (kind === "mesh" || kind === "convex") return { origin: [0, 0, 0] }   // the mesh IS the geometry
+    if (kind === "sphere") return { sphere: dim(Math.max(half[0], half[1], half[2])), origin }
+    if (kind === "cylinder" || kind === "capsule") {
+      const radius = dim(Math.max(half[0], half[2]))
+      const halfHeight = kind === "capsule" ? Math.max(0, r4(half[1] - radius)) : dim(half[1])
+      return { [kind]: { halfHeight, radius }, origin }
+    }
+    return { box: [dim(half[0]), dim(half[1]), dim(half[2])], origin }
+  }
+
+  // ---- body/shape lifetime --------------------------------------------------------------------
+
   /** @internal Physics/Trigger take over: drop the pick body and hand back the shape id. */
   _claim(): number {
     if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
@@ -78,13 +229,60 @@ export class Shape extends Aspect<"shape", Node> {
   /** @internal true for an exact triangle mesh — Physics refuses a dynamic body on it. */
   get _isTriangleMesh(): boolean { return this.mesh === true }
 
+  // Rebuild the geometry in place: the body keeps its id, velocity and world transform (Physics
+  // holds that id, so re-creating the body instead would strand it). A shape a CharacterController
+  // or a Vehicle claimed is theirs — they were handed the old one and keep it.
+  private _rebuild(): void {
+    if (!this._shapeId) return               // never attached, or a build without physics
+    const previous = this._shapeId
+    const id = this._build()
+    if (!id) return                          // build failed — keep what works
+    this._shapeId = id
+    if (this._bodyId) {
+      if (_creator.physicsSetBodyShape) _creator.physicsSetBodyShape(this._bodyId, id, true)
+      else console.warn("Shape: this host can't re-shape a live body — the new dimensions apply from the next attach")
+    } else {
+      console.warn(`Shape: "${this.node.name}"'s geometry is owned by a CharacterController / Vehicle — re-attach it to pick up the new dimensions`)
+    }
+    _creator.physicsDestroyShape(previous)
+  }
+
   private _build(): number {
-    if (this.mesh) return this._buildMesh(this.mesh === "convex")
-    if (this.sphere !== undefined) return _creator.physicsBuildSphere(this.sphere)
-    if (this.cylinder) return _creator.physicsBuildCylinder(this.cylinder.halfHeight, this.cylinder.radius)
-    if (this.capsule) return _creator.physicsBuildCapsule(this.capsule.halfHeight, this.capsule.radius)
-    if (this.box) return _creator.physicsBuildBox(cx(this.box), cy(this.box), cz(this.box))
-    return this._buildAutoBox()
+    this._autoOrigin = null
+    this._sig = this._signature()
+    let id = 0
+    if (this.mesh) id = this._buildMesh(this.mesh === "convex")
+    else if (this.sphere !== undefined) id = _creator.physicsBuildSphere(this.sphere)
+    else if (this.cylinder) id = _creator.physicsBuildCylinder(this.cylinder.halfHeight, this.cylinder.radius)
+    else if (this.capsule) id = _creator.physicsBuildCapsule(this.capsule.halfHeight, this.capsule.radius)
+    else if (this.box) id = _creator.physicsBuildBox(cx(this.box), cy(this.box), cz(this.box))
+    else id = this._buildAutoBox()
+    if (id) this._applyOrigin(id)
+    return id
+  }
+
+  // Push `origin` (or, for an auto box, the mesh centre it measured) onto the built shape. A host
+  // without the call keeps the old "centred on the node" behaviour; only an EXPLICIT origin warns,
+  // since the auto centre is a silent improvement nobody asked for.
+  private _applyOrigin(shapeId: number): void {
+    const o = this.origin
+    const x = o ? cx(o) : this._autoOrigin?.[0] ?? 0
+    const y = o ? cy(o) : this._autoOrigin?.[1] ?? 0
+    const z = o ? cz(o) : this._autoOrigin?.[2] ?? 0
+    if (x === 0 && y === 0 && z === 0) return
+    if (!_creator.physicsSetShapeOrigin) {
+      if (o) console.warn("Shape { origin } needs a newer host — the collider stays centred on the node")
+      return
+    }
+    _creator.physicsSetShapeOrigin(shapeId, x, y, z)
+  }
+
+  // What a rebuild has to notice: the kind, its dimensions and the origin (`raycast` is applied to
+  // the body directly, and the node's own transform is the body's, not the shape's).
+  private _signature(): string {
+    const v = (a: Vec3Like | undefined) => (a ? `${cx(a)},${cy(a)},${cz(a)}` : "")
+    const t = (o: { halfHeight: number, radius: number } | undefined) => (o ? `${o.halfHeight},${o.radius}` : "")
+    return `${v(this.box)}|${this.sphere ?? ""}|${t(this.cylinder)}|${t(this.capsule)}|${this.mesh ?? ""}|${v(this.origin)}`
   }
 
   // mesh: a Mesh node hands its CPU geometry over; anything else is tried as a GLB root (the host
@@ -111,7 +309,10 @@ export class Shape extends Aspect<"shape", Node> {
     return id
   }
 
-  // auto: a box from the mesh AABB × world scale (so the physical box matches the rendered size).
+  // auto: a box from the node's own mesh AABB × world scale (so the physical box matches the
+  // rendered size), CENTRED on those bounds — geometry modelled off its pivot gets a box that still
+  // wraps it. A node with no geometry of its own (a Model root, an empty) keeps the 0.5 default;
+  // `fit()` measures the whole subtree instead.
   private _buildAutoBox(): number {
     const s = this.node.worldScale
     let hx = 0.5, hy = 0.5, hz = 0.5
@@ -127,7 +328,10 @@ export class Shape extends Aspect<"shape", Node> {
         if (v[i + 2] < minZ) minZ = v[i + 2]
         if (v[i + 2] > maxZ) maxZ = v[i + 2]
       }
-      hx = (maxX - minX) * 0.5; hy = (maxY - minY) * 0.5; hz = (maxZ - minZ) * 0.5
+      if (isFinite(minX)) {
+        hx = (maxX - minX) * 0.5; hy = (maxY - minY) * 0.5; hz = (maxZ - minZ) * 0.5
+        this._autoOrigin = [(maxX + minX) * 0.5 * s.x, (maxY + minY) * 0.5 * s.y, (maxZ + minZ) * 0.5 * s.z]
+      }
     }
     return _creator.physicsBuildBox(hx * s.x, hy * s.y, hz * s.z)
   }