lecodes-cli 0.2.0 → 0.5.0

package/runtime/sdk/g2/Scene2D.ts

@@ -2,15 +2,38 @@
 // 2D engine and starts its RAF loop; only the active scene renders. Grown from the Phase 0 seed.
 
 import { Color, type ColorInput } from "../core/color"
+import { _installAspectFrames } from "../core/Aspect"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
 import { node2dRegistry, type Node2D } from "./Node2D"
 import { ensurePointerEvents } from "./touch"
 
+// Route aspect update(dt) through the render-synced native phases (c2dRender early = before physics,
+// late = after animations / before draw), so followers/cameras are in lockstep with the draw. Done from
+// the 2D layer (not core) so a 3D-only bundle never pulls in the 2D bridge. Installed once, lazily on
+// the first Scene2D. On an older wasm without the hooks the installer returns false → setLoop fallback.
+let framesInstalled = false
+const installRenderSyncedFrames = (): void => {
+  if (framesInstalled) return
+  framesInstalled = true
+  _installAspectFrames((early, late) => {
+    if (typeof _creator2d.setEarlyUpdate !== "function") return false
+    _creator2d.setEarlyUpdate(early)
+    _creator2d.setLateUpdate(late)
+    return true
+  })
+}
+
 export type Scene2DOptions = {
   /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
   background?: ColorInput
+  /** Texture sampling for the 2D renderer: `'nearest'` (default — crisp pixel art) or `'linear'`
+   *  (smooth — for hi-res / non-pixel-art assets). Applied when the scene is opened, so switching
+   *  scenes restores the active scene's choice. NOTE: this is a GLOBAL renderer setting (one sampler
+   *  for ALL textures, not per-texture), so the currently-open scene's filter wins. Omit to leave the
+   *  current setting (engine default is nearest). */
+  filter?: 'nearest' | 'linear'
 }
 
 /** Returned by scene2d.layer(n); chain .ySort() to enable top-down depth sorting for that layer. */
@@ -37,9 +60,14 @@ export class Scene2D {
   readonly _clickListeners: Array<(ev: ClickEvent<Node2D | null>) => void> = []
   readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void> = []
 
+  /** Texture filter to (re)assert on open(); the sampler is global, so each scene reclaims it. */
+  private readonly _filter?: 'nearest' | 'linear'
+
   constructor(options: Scene2DOptions = {}) {
+    installRenderSyncedFrames()
     this.id = _creator2d.createScene()
     this.camera = new Camera2D(this.id)
+    this._filter = options.filter
     if (options.background !== undefined) this.background = options.background
   }
 
@@ -85,6 +113,8 @@ export class Scene2D {
 
   /** Make this the active scene (brings up the 2D engine on the canvas; closes any other). */
   open(): this {
+    // Reassert this scene's texture filter (the sampler is global — see Scene2DOptions.filter).
+    if (this._filter !== undefined) _creator2d.setDefaultFilter(this._filter === 'linear')
     _creator2d.openScene(this.id)
     Scene2D._active = this
     return this

package/runtime/sdk/g2/{Shape.ts → Shape2D.ts}

@@ -1,19 +1,19 @@
-// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape does not by itself
-// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger (sensor), both
-// of which require a Shape and turn its geometry into a Box2D fixture. The shape is also what pointer
-// picking hits, so a node is clickable once it has a Shape + Physics2D/Trigger (a body to query).
+// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape2D does not by itself
+// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger2D (sensor), both
+// of which require a Shape2D and turn its geometry into a Box2D fixture. The shape is also what pointer
+// picking hits, so a node is clickable once it has a Shape2D + Physics2D/Trigger2D (a body to query).
 //
-//   wall.aspect(Shape, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
-//   goal.aspect(Shape, { circle: 20 }).aspect(Trigger)
-//   hero.aspect(Shape, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
+//   wall.aspect(Shape2D, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
+//   goal.aspect(Shape2D, { circle: 20 }).aspect(Trigger2D)
+//   hero.aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
 //
-// With no geometry set, Shape derives a box from the node's sprite size ("auto").
+// With no geometry set, Shape2D derives a box from the node's sprite size ("auto").
 
 import { Aspect } from "../core/Aspect"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { Node2D } from "./Node2D"
 
-export class Shape extends Aspect<"shape", Node2D> {
+export class Shape2D extends Aspect<"shape", Node2D> {
   static readonly aspect = "shape"
 
   /** Box half-extents [hw, hh] (world units). */
@@ -30,7 +30,7 @@ export class Shape extends Aspect<"shape", Node2D> {
   offset?: Vec2Like
 
   /**
-   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger).
+   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger2D).
    * `sensor` selects a sensor (trigger) vs solid fixture; density/friction/restitution are the
    * material (ignored for sensors / segments only use friction+restitution).
    */

package/runtime/sdk/g2/Sprite.ts

@@ -4,11 +4,15 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { Vec2, type Vec2Like } from "../math/vec"
+import { Canvas, isCanvas } from "../canvas/Canvas"
 import { Node2D } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
 
+/** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
+export type TextureSource = Texture2D | Canvas
+
 export type SpriteOptions = {
-  texture?: Texture2D
+  texture?: TextureSource
   /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
   anchor?: Vec2Like
   /** World size; defaults to the texture's pixel dimensions. */
@@ -44,14 +48,20 @@ export class Sprite extends Node2D {
   }
 
   get texture(): Texture2D | undefined { return this._texture }
-  set texture(t: Texture2D | undefined) {
-    this._texture = t
-    if (!t) return
-    _creator2d.setSprite(this.id, t.id) // native resets UV + size to the full texture
+  set texture(t: TextureSource | undefined) {
+    const tex = isCanvas(t) ? t.texture() : t   // a Canvas bakes to a texture on assign
+    this._texture = tex
+    if (!tex) return
+    _creator2d.setSprite(this.id, tex.id) // native resets UV + size to the full (pixel) texture
+    // A Canvas is authored in LOGICAL units but baked at logical × pixelRatio, so default the sprite's
+    // WORLD size to the canvas's LOGICAL size — pixelRatio then only affects crispness, not on-screen
+    // size. (A plain texture keeps the native default: the texture's pixel dimensions.)
+    if (!this._size && isCanvas(t)) this._size = new Vec2(t.width, t.height)
     if (this._size) _creator2d.setSpriteSize(this.id, this._size.x, this._size.y)
   }
 
-  /** Current world size: explicit override if set, else the texture's pixel dimensions. */
+  /** Current world size: explicit override if set, else the texture's pixel dimensions (a Canvas-backed
+   *  sprite defaults to the canvas's LOGICAL size, so pixelRatio is crispness only, not size). */
   get size(): Vec2 { return this._size ?? (this._texture ? new Vec2(this._texture.width, this._texture.height) : new Vec2(0, 0)) }
   set size(v: Vec2Like) { this._size = new Vec2(v); _creator2d.setSpriteSize(this.id, this._size.x, this._size.y) }
 

package/runtime/sdk/g2/Texture2D.ts

@@ -3,7 +3,7 @@
 
 // Internal SDK code imports injected globals explicitly (the bare-global inject is only for USER
 // code; here `fetch` would otherwise resolve to the node/bun ambient one).
-import { fetch, type FetchResponse } from "../runtime/fetch"
+import { fetch, type FetchResponse, type File } from "../runtime/fetch"
 
 export class Texture2D {
   /** Native texture handle. */
@@ -17,7 +17,17 @@ export class Texture2D {
     this.height = height
   }
 
-  static load(source: string | FetchResponse): Promise<Texture2D> {
+  // Wrap a Canvas's baked surface as a texture (RGBA8, already rasterized → synchronous, no decode).
+  // Structural type avoids a Canvas import cycle (Canvas imports Texture2D).
+  static fromCanvas(canvas: { _bakeSurface(): number, width: number, height: number, pixelRatio: number }): Texture2D {
+    const surfaceId = canvas._bakeSurface()
+    const texId = _creator2d.createTextureFromCanvas(surfaceId)
+    return new Texture2D(texId, Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio))
+  }
+
+  // Accepts a URL, an already-fetched response, or a File (e.g. from Canvas.toFile() / openFilePicker) —
+  // anything backed by a host buffer. The buffer's encoded bytes are decoded + uploaded by the engine.
+  static load(source: string | FetchResponse | File): Promise<Texture2D> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {
         if (resp.status >= 400) {

package/runtime/sdk/g2/{Trigger.ts → Trigger2D.ts}

@@ -1,10 +1,10 @@
-// A trigger zone, as an aspect on a Node2D. Requires a Shape (its geometry); creates a static SENSOR
+// A trigger zone, as an aspect on a Node2D. Requires a Shape2D (its geometry); creates a static SENSOR
 // body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
 // instead of colliding. A trigger does not block movement.
 //
 //   const goal = new Node2D({ ... })
-//     .aspect(Shape, { box: [32, 64] })
-//     .aspect(Trigger)
+//     .aspect(Shape2D, { box: [32, 64] })
+//     .aspect(Trigger2D)
 //   goal.addEventListener('enter', other => win(other))
 //   goal.addEventListener('exit',  other => ...)
 //
@@ -13,21 +13,21 @@
 import { Aspect } from "../core/Aspect"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import { ensurePhysicsEvents } from "./loop"
-import { Shape } from "./Shape"
+import { Shape2D } from "./Shape2D"
 import type { Node2D } from "./Node2D"
 
-export class Trigger extends Aspect<"trigger", Node2D> {
+export class Trigger2D extends Aspect<"trigger", Node2D> {
   static readonly aspect = "trigger"
 
   private _h = 0
-  /** Native body handle (0 if no physics support). */
-  get handle(): number { return this._h }
+  /** Native physics body id (0 if no physics support). Mirrors 3D `Trigger.id`. */
+  get id(): number { return this._h }
 
   onAttach(): void {
     if (!_creator2d.physicsHasSupport || !_creator2d.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
+    const shape = this.node.get(Shape2D)
     if (!shape) {
-      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+      throw new Error("Trigger2D requires a Shape2D aspect — add it first: node.aspect(Shape2D, {…}).aspect(Trigger2D)")
     }
     this._h = _creator2d.physicsCreateBody(this.node.id, 0 /* static */)
     if (!this._h) return

package/runtime/sdk/gl/CharacterController.ts

@@ -0,0 +1,101 @@
+// A character controller, as an aspect on a 3D Node, backed by Jolt's CharacterVirtual — a kinematic
+// collide-and-slide controller (NOT a rigid body: no bouncing/tipping, crisp control, built-in stair
+// stepping + slope handling). Requires a Shape (a capsule is recommended) and does NOT use Physics.
+//
+//   const hero = new Mesh(capsuleGeometry(), material)
+//     .aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
+//     .aspect(CharacterController, { speed: 6, jumpSpeed: 8 })
+//   Input.on('move', (x, z) => hero.controller.move(x, z))
+//   Input.on('jump', () => hero.controller.jump())
+//
+// You drive horizontal intent + jump; the controller integrates gravity and Jolt handles collision
+// against the world. `grounded` reports whether it's on walkable ground. It runs in the EARLY update
+// phase (feeds this frame's step). Note: it collides with solid bodies but PASSES THROUGH triggers,
+// and (v1) is not itself detected by triggers and isn't pointer-pickable while active.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3 } from "../math/vec"
+import { Shape } from "./Shape"
+import type { Node } from "./Node"
+
+const clamp1 = (v: number): number => (v < -1 ? -1 : v > 1 ? 1 : v)
+
+export class CharacterController extends Aspect<"controller", Node> {
+  static readonly aspect = "controller"
+
+  /** Horizontal move speed (world units/s). */
+  speed = 5
+  /** Jump take-off speed (world units/s). */
+  jumpSpeed = 7
+  /** Character-tuned gravity (world units/s²), separate from the world gravity — usually stronger for
+   *  snappier feel. Applied to the vertical velocity each frame. */
+  gravity = -20
+  /** Max ground slope (degrees) the character treats as walkable. Set before attach. */
+  maxSlope = 45
+
+  updateBeforePhysics = true // EARLY phase — set velocity so THIS frame's step consumes it
+
+  private _charId = 0
+  private _mx = 0
+  private _mz = 0
+  private _jumpQueued = false
+  private _vy = 0
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("CharacterController requires a Shape aspect (a capsule is recommended) — add it first: node.aspect(Shape, { capsule: {…} }).aspect(CharacterController)")
+    }
+    const shapeId = shape._claim() // the character owns the shape; it is not a rigid body
+    this._charId = _creator.characterCreate(this.node.id, shapeId, this.maxSlope)
+  }
+
+  onDetach(): void {
+    if (this._charId) { _creator.characterDestroy(this._charId); this._charId = 0 }
+    this.node.get(Shape)?._recreatePickBody()
+  }
+
+  /** Native character id (0 until attached / no physics support). */
+  get id(): number { return this._charId }
+
+  /** Horizontal move intent; each component in [-1, 1] (e.g. from input). Sticky — set 0 to stop. */
+  move(x: number, z: number): void { this._mx = clamp1(x); this._mz = clamp1(z) }
+
+  /** Queue a jump; consumed on the next frame if grounded. */
+  jump(): void { this._jumpQueued = true }
+
+  /** True while standing on walkable ground (OnGround). */
+  get grounded(): boolean {
+    return this._charId ? _creator.characterGetGroundState(this._charId) === 0 : false
+  }
+
+  /** Ground state: 0 on-ground, 1 on-steep-slope, 2 touching-but-unsupported, 3 in-air. */
+  get groundState(): number {
+    return this._charId ? _creator.characterGetGroundState(this._charId) : 3
+  }
+
+  /** Current velocity (world units/s, fresh Vec3). */
+  get velocity(): Vec3 {
+    const o = new Float32Array(3)
+    if (this._charId) _creator.characterGetVelocity(this._charId, o)
+    return new Vec3(o[0], o[1], o[2])
+  }
+
+  /** Teleport to a world position (clears vertical velocity). */
+  teleport(x: number, y: number, z: number): this {
+    if (this._charId) _creator.characterSetPosition(this._charId, x, y, z)
+    this._vy = 0
+    return this
+  }
+
+  update(dt: number): void {
+    if (!this._charId) return
+    const grounded = _creator.characterGetGroundState(this._charId) === 0
+    if (grounded && this._vy < 0) this._vy = 0          // landed
+    if (this._jumpQueued && grounded) this._vy = this.jumpSpeed
+    this._jumpQueued = false
+    this._vy += this.gravity * dt                        // integrate gravity (CharacterVirtual is kinematic)
+    _creator.characterSetVelocity(this._charId, this._mx * this.speed, this._vy, this._mz * this.speed)
+  }
+}

package/runtime/sdk/gl/Material.ts

@@ -6,6 +6,12 @@
 import { Color, type ColorInput } from "../core/color"
 import { fetch, type FetchResponse } from "../runtime/fetch"
 import { Texture } from "./Texture"
+// Type-only (erased at build) so a 3D material never pulls the 2D-canvas runtime; the guard is inline.
+import type { Canvas } from "../canvas/Canvas"
+
+/** Duck-type a Canvas without importing it (keeps 3D material free of 2D-canvas code). */
+const isCanvasSource = (v: unknown): v is Canvas =>
+  typeof v === "object" && v !== null && (v as { __canvas?: unknown }).__canvas === true
 
 type UniformValue = string | Texture | number | boolean | number[] | Float32Array | null
 
@@ -28,7 +34,7 @@ const applyUniform = (id: number, key: string, value: UniformValue): void => {
   }
 }
 
-export type MaterialColorOptions = { color?: ColorInput, map?: Texture | null }
+export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
 
 export class Material {
   /** @internal native material-instance handle. */
@@ -65,11 +71,12 @@ export class Material {
     if (this._colorKey) this.uniforms[this._colorKey] = Color.toHexString(c)
   }
 
-  set map(value: Texture | null) {
+  set map(value: Texture | Canvas | null) {
     if (value === null) {
       if (this._useMapFlag) this.uniforms.useBaseColorMap = false
     } else {
-      this.uniforms.baseColorMap = value
+      // A Canvas bakes to a (cached) 3D texture on assign — same as Sprite accepting a Canvas in 2D.
+      this.uniforms.baseColorMap = isCanvasSource(value) ? Texture.fromCanvas(value) : value
       if (this._useMapFlag) this.uniforms.useBaseColorMap = true
     }
   }

package/runtime/sdk/gl/Node.ts

@@ -2,7 +2,7 @@
 // on them. Native (creator-gl) owns the authoritative transform; reads decompose a cached local
 // matrix (re-synced lazily, since physics can write the transform from native each frame).
 //
-// Capabilities are aspects: node.aspect(Physics, …) (→ node.physics), node.aspect(Collider, …).
+// Capabilities are aspects: node.aspect(Physics, …) (→ node.physics), node.aspect(Shape, …).
 // A GLB import is the Model node kind (with the ModelAnimation aspect). Hierarchy lives here.
 
 import { AspectHost } from "../core/Aspect"
@@ -12,6 +12,7 @@ import { Quat, cw, type QuatLike } from "../math/quat"
 import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
+import { ensurePhysicsEvents } from "./physicsEvents"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
@@ -28,6 +29,10 @@ export type NodeEvents = {
   track: () => void
   /** AR anchors only: the anchor lost tracking. */
   untrack: () => void
+  /** A physics contact/trigger overlap began (the other body's node). Needs a Shape + Physics/Trigger. */
+  enter: (other: Node) => void
+  /** A physics contact/trigger overlap ended. */
+  exit: (other: Node) => void
 }
 
 export class Node extends AspectHost<NodeEvents> {
@@ -171,7 +176,7 @@ export class Node extends AspectHost<NodeEvents> {
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
   }
 
-  // --- behaviors are aspects: node.aspect(Physics, …) / node.aspect(Collider, …) ---
+  // --- behaviors are aspects: node.aspect(Shape, …) / node.aspect(Physics, …) ---
 
   /** Orient the node so the given axis (default "-z", "forward") points at a world point. */
   lookAt(point: Vec3Like, mode: "z" | "-z" | "x" | "-x" | "y" | "-y" = "-z", ortho: Vec3Like = [ 0, 1, 0 ]): this {
@@ -207,6 +212,7 @@ export class Node extends AspectHost<NodeEvents> {
   override addEventListener<K extends keyof NodeEvents>(channel: K, callback: NodeEvents[K]): void {
     if (channel === "click") registerTouchEndEvent()
     else if (channel === "touchstart") registerTouchStartEvent()
+    else if (channel === "enter" || channel === "exit") ensurePhysicsEvents()
     super.addEventListener(channel, callback)
   }
 
@@ -215,6 +221,9 @@ export class Node extends AspectHost<NodeEvents> {
     this.dispatch(channel, ...args)
   }
 
+  /** @internal — emit a physics contact/trigger event (the physics-event router can't reach dispatch). */
+  _emitCollision(channel: "enter" | "exit", other: Node): void { this.dispatch(channel, other) }
+
   /** @internal — host animation-complete callback; forwards to the ModelAnimation aspect (if any).
    *  Returns whether the clip should keep playing. */
   _onAnimationComplete(clipIndex: number): boolean {

package/runtime/sdk/gl/Physics.ts

@@ -1,47 +1,70 @@
-// Physics body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl.
-//   node.aspect(Physics, { motion: 'dynamic' });  node.physics.applyImpulse([0, 6, 0])
+// 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).
 //
-// 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. (Ported from the former Body class.)
+//   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 type { Node } from "./Node"
+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 type BodyShape =
-  | { type: "auto" }
-  | { type: "box", halfExtents: Vec3Like }
-  | { type: "sphere", radius: number }
-  | { type: "cylinder", halfHeight: number, radius: number }
+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
-  /** Default { type: "auto" } — a box from the mesh AABB × world scale. */
-  shape: BodyShape = { type: "auto" }
 
   private _bodyId = 0
 
   onAttach(): void {
-    // No physics in this build (CREATOR_GL_PHYSICS=OFF) → bodyId stays 0; all methods no-op.
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const motion = MOTION[this.motion]
-    const shape = resolveShape(this.node, this.shape)
-    if (shape.type === "sphere") {
-      this._bodyId = _creator.physicsCreateSphere(this.node.id, shape.radius, motion, this.mass)
-    } else if (shape.type === "cylinder") {
-      this._bodyId = _creator.physicsCreateCylinder(this.node.id, shape.halfHeight, shape.radius, motion, this.mass)
-    } else {
-      this._bodyId = _creator.physicsCreateBox(this.node.id, cx(shape.halfExtents), cy(shape.halfExtents), cz(shape.halfExtents), motion, this.mass)
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
     }
+    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 }
+    this.node.get(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. */
@@ -69,27 +92,28 @@ export class Physics extends Aspect<"physics", Node> {
     return this
   }
 
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+  // --- 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()
   }
-}
 
-// Resolve "auto" to a box from the mesh AABB × world scale (so the physical box matches the rendered
-// size). Falls back to a unit box if there is no geometry.
-const resolveShape = (node: Node, shape: BodyShape): Exclude<BodyShape, { type: "auto" }> => {
-  if (shape.type !== "auto") return shape
-  const scale = node.worldScale
-  let hx = 0.5, hy = 0.5, hz = 0.5
-  const geom = node.geometry
-  if (geom) {
-    const v = geom.vertices
-    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity
-    for (let i = 0; i + 2 < v.length; i += 3) {
-      if (v[i] < minX) minX = v[i]; if (v[i] > maxX) maxX = v[i]
-      if (v[i + 1] < minY) minY = v[i + 1]; if (v[i + 1] > maxY) maxY = v[i + 1]
-      if (v[i + 2] < minZ) minZ = v[i + 2]; if (v[i + 2] > maxZ) maxZ = v[i + 2]
+  /** 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],
     }
-    hx = (maxX - minX) * 0.5; hy = (maxY - minY) * 0.5; hz = (maxZ - minZ) * 0.5
   }
-  return { type: "box", halfExtents: [ hx * scale.x, hy * scale.y, hz * scale.z ] }
 }

package/runtime/sdk/gl/Scene.ts

@@ -6,6 +6,7 @@
 // direct light + shadows.
 
 import { Color, type ColorInput } from "../core/color"
+import { _installAspectFrames } from "../core/Aspect"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { Camera } from "./Camera"
@@ -29,6 +30,22 @@ export type SceneOptions = {
   antialias?: boolean
 }
 
+// Route aspect update(dt) through the render-synced native phases (render() early = before physics,
+// late = after animations / before draw), so followers/cameras are in lockstep with the draw. Done from
+// the 3D layer (not core) so a 2D-only bundle never pulls in the 3D bridge. Installed once, lazily on
+// the first Scene. On an older wasm without the hooks the installer returns false → setLoop fallback.
+let framesInstalled = false
+const installRenderSyncedFrames = (): void => {
+  if (framesInstalled) return
+  framesInstalled = true
+  _installAspectFrames((early, late) => {
+    if (typeof _creator.setEarlyUpdate !== "function") return false
+    _creator.setEarlyUpdate(early)
+    _creator.setLateUpdate(late)
+    return true
+  })
+}
+
 export class Scene {
   /** @internal native scene handle. */
   readonly _id: number
@@ -44,6 +61,7 @@ export class Scene {
   static get active(): Scene | null { return Scene._active }
 
   constructor(options: SceneOptions = {}) {
+    installRenderSyncedFrames()
     const parent = (options as any)._parent as Scene | undefined
     if (parent) {
       this.camera = parent.camera