lecodes-cli 0.18.0 → 0.18.2

package/runtime/sdk/gl/Node.ts

@@ -13,7 +13,8 @@ import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 import { ensurePhysicsEvents } from "./physicsEvents"
-import { glState } from "./state"
+import { Material } from "./Material"
+import type { CompAxis, CompWriter } from "../core/compWrite"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
@@ -49,7 +50,10 @@ const findNodeByWalk = (rootId: number, name: string): number => {
   return exact || loose
 }
 
-export class Node extends AspectHost<NodeEvents> {
+// Scratch for the world-position read-back in _setOwnedPosition (one per module, never handed out).
+const worldScratch = new Float32Array(3)
+
+export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** Native entity handle. */
   readonly id: number
 
@@ -58,11 +62,10 @@ export class Node extends AspectHost<NodeEvents> {
   isTracked = false
 
   private _matrix?: Float32Array
-  private _lastSync = 0
-  private _syncFrame = -1
   private _worldMatrix?: Float32Array
-  private _scaleCache?: [number, number, number]
   private _boneCache?: Map<string, Node | null>
+  /** Materials assigned through setMaterial, by primitive slot (a Mesh fills slot 0 itself). */
+  protected _materials?: Material[]
 
   constructor(internalId?: number) {
     super()
@@ -80,29 +83,31 @@ export class Node extends AspectHost<NodeEvents> {
   set visible(value: boolean) { _creator.setVisible(this.id, value) }
 
   // --- local transform ---
-  // Native owns the authoritative matrix; we keep a Float32Array cache (re-synced lazily because physics
-  // can rewrite it each frame). The PUBLIC `matrix` getter hands back a fresh Mat4 *copy* (value
-  // semantics — mutating it never touches the node until you assign it back). `_sync()` is the internal
-  // hot path that returns the cache directly for cheap component reads.
+  // Native owns the authoritative matrix. `_sync()` reads it into a per-node scratch buffer on EVERY
+  // call: a bridge read is ~40 ns on QuickJS — what the Date.now() of a staleness check cost — so a
+  // cache bought nothing and needed invalidation hooks (physics / controllers / animation rewrite
+  // transforms natively between frames). The PUBLIC `matrix` getter hands back a fresh Mat4 *copy*
+  // (value semantics — mutating it never touches the node until you assign it back); `_sync()` is
+  // the internal hot path for component reads.
   private _sync(): Float32Array {
-    if (!this._matrix) this._matrix = new Float32Array(16)
-    // stale once per render frame (glState.frame — physics/controllers/animation rewrite transforms
-    // between frames), or after 10 ms of wall time when no scene loop is running
-    if (this._lastSync === 0 || this._syncFrame !== glState.frame || Date.now() - this._lastSync > 10) {
-      _creator.getMatrix(this.id, this._matrix)
-      this._scaleCache = undefined
-      this._lastSync = Date.now()
-      this._syncFrame = glState.frame
-    }
-    return this._matrix
+    const m = this._matrix ?? (this._matrix = new Float32Array(16))
+    _creator.getMatrix(this.id, m)
+    return m
   }
 
   get matrix(): Mat4 { return new Mat4(this._sync()) }
   set matrix(m: Mat4Like) {
-    if (!this._matrix) this._matrix = new Float32Array(16)
-    this._matrix.set(matArr(m))
-    this._lastSync = Date.now()
-    _creator.setMatrix(this.id, this._matrix)
+    const buf = this._matrix ?? (this._matrix = new Float32Array(16))
+    buf.set(matArr(m))
+    _creator.setMatrix(this.id, buf)
+    // A matrix write on a physics-owned node must move the engine object too, or it is silently
+    // overwritten by the next sync. Position always; rotation only for a BODY (see _setOwnedRotation).
+    // Scale is never routed — a Jolt shape is built at a fixed size, that is `Shape`'s job.
+    // `worldMatrix` composes into this setter, so it is covered here too.
+    if (this._xf) {
+      this._setOwnedPosition(buf[12], buf[13], buf[14])
+      this._setOwnedRotation()
+    }
   }
 
   get worldMatrix(): Mat4 {
@@ -120,39 +125,86 @@ export class Node extends AspectHost<NodeEvents> {
     this.matrix = p.worldMatrix.invert().mul(m)
   }
 
+  /** @internal The engine object that mirrors this node's transform, if any — a physics body or a
+   *  character (0 = none). `position` writes are routed to it as well, because the engine is the
+   *  authority: on a dynamic body a plain setPosition is overwritten by the next sync, and on a
+   *  static / pick / trigger body it would leave the COLLIDER behind while the node moved. Set by
+   *  Shape (bodies) and CharacterController. */
+  _xf = 0
+  /** @internal What `_xf` is: 1 = character, 2 = physics body. */
+  _xfKind = 0
+
+  // Route a position write to the engine object that owns this node. Kept out of the setters' hot path
+  // (they only pay one truthiness check). `position` stays a LOCAL coordinate like on every node, while
+  // physics works in world space — so the node is written first and the world point read back natively
+  // (one bridge call for any parent depth, no allocation; the native transform manager updates the
+  // world matrix synchronously).
+  private _setOwnedPosition(x: number, y: number, z: number): void {
+    _creator.setPosition(this.id, x, y, z)   // keep the node itself right, so a read-back is immediate
+    _creator.getWorldPosition(this.id, worldScratch)
+    if (this._xfKind === 1) _creator.characterSetPosition(this._xf, worldScratch[0], worldScratch[1], worldScratch[2])
+    else _creator.physicsSetBodyPosition(this._xf, worldScratch[0], worldScratch[1], worldScratch[2])
+  }
+
+  // The rotation half of the same routing. BODIES ONLY: a character's rotation is node-owned by design
+  // (the engine writes its position and nothing else — a capsule is symmetric about its up axis, so its
+  // yaw is physically meaningless), and pushing one into Jolt would invent an authority that isn't there.
+  // The node has already been written by the caller, so the world rotation is read back from it — that
+  // way the engine's own euler convention decides, instead of this file re-deriving it.
+  private _setOwnedRotation(): void {
+    if (this._xfKind !== 2 || !_creator.physicsSetBodyRotation) return
+    const q = this.worldMatrix.rotation
+    _creator.physicsSetBodyRotation(this._xf, q.x, q.y, q.z, q.w)
+  }
+
   get position(): Vec3 { const m = this._sync(); return new Vec3(m[12], m[13], m[14]) }
-  set position(v: Vec3Like) { this._lastSync = 0; _creator.setPosition(this.id, cx(v), cy(v), cz(v)) }
+  set position(v: Vec3Like) {
+    if (this._xf) this._setOwnedPosition(cx(v), cy(v), cz(v))
+    else _creator.setPosition(this.id, cx(v), cy(v), cz(v))
+  }
 
-  // Scalar position accessors — the loud, correct way to nudge one axis (`node.x = 3`), so nobody reaches
-  // for `node.position.x = 3` (a no-op: the getter returns a fresh copy).
+  // Scalar position accessors — one axis without touching the others (`node.x = 3`). The direct spelling
+  // `node.position.x = 3` compiles to the same thing (chisel's comp_write pass routes it through
+  // `_writeComp` below); only a STORED copy of `position` is still a copy.
   get x(): number { return this._sync()[12] }
-  set x(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, v, m[13], m[14]) }
+  set x(v: number) { const m = this._sync(); if (this._xf) this._setOwnedPosition(v, m[13], m[14]); else _creator.setPosition(this.id, v, m[13], m[14]) }
   get y(): number { return this._sync()[13] }
-  set y(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, m[12], v, m[14]) }
+  set y(v: number) { const m = this._sync(); if (this._xf) this._setOwnedPosition(m[12], v, m[14]); else _creator.setPosition(this.id, m[12], v, m[14]) }
   get z(): number { return this._sync()[14] }
-  set z(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, m[12], m[13], v) }
+  set z(v: number) { const m = this._sync(); if (this._xf) this._setOwnedPosition(m[12], m[13], v); else _creator.setPosition(this.id, m[12], m[13], v) }
+
+  /** @internal chisel `comp_write` (see core/compWrite.ts): `node.position.<axis> = v` is compiled to a
+   *  call here; the scalar setters already carry the physics routing. The list is compile-time data. */
+  static _comps = [ "position" ]
+  _writeComp(_prop: string, axis: CompAxis, v: number): void {
+    if (axis === "x") this.x = v
+    else if (axis === "y") this.y = v
+    else if (axis === "z") this.z = v
+  }
 
   get scale(): Vec3 {
-    if (this._lastSync === 0 || !this._scaleCache) {
-      const m = this._sync()
-      this._scaleCache = [ Math.hypot(m[0], m[1], m[2]), Math.hypot(m[4], m[5], m[6]), Math.hypot(m[8], m[9], m[10]) ]
-    }
-    return new Vec3(this._scaleCache)
+    const m = this._sync()
+    return new Vec3(Math.hypot(m[0], m[1], m[2]), Math.hypot(m[4], m[5], m[6]), Math.hypot(m[8], m[9], m[10]))
   }
   set scale(v: Vec3Like | number) {
-    this._lastSync = 0
     if (typeof v === "number") _creator.setScale(this.id, v, v, v)
     else _creator.setScale(this.id, cx(v), cy(v), cz(v))
   }
 
   get quaternion(): Quat { return new Mat4(this._sync()).rotation }
-  set quaternion(v: QuatLike) { this._lastSync = 0; _creator.setQuaternion(this.id, cx(v), cy(v), cz(v), cw(v)) }
+  set quaternion(v: QuatLike) {
+    _creator.setQuaternion(this.id, cx(v), cy(v), cz(v), cw(v))
+    if (this._xf) this._setOwnedRotation()
+  }
 
   get eulerAngles(): Vec3 { return new Mat4(this._sync()).eulerAngles }
   // order 1 = YXZ — the SDK's euler convention (math/quat.ts); the getter also extracts YXZ, so
   // the pair round-trips. (Historically this passed 0/XYZ AND the engine stored the euler matrix
   // transposed — the setter applied the INVERSE rotation. Both fixed 2026-07-10.)
-  set eulerAngles(v: Vec3Like) { this._lastSync = 0; _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 1) }
+  set eulerAngles(v: Vec3Like) {
+    _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 1)
+    if (this._xf) this._setOwnedRotation()
+  }
 
   // --- world-space reads ---
   get forward(): Vec3 {
@@ -190,13 +242,29 @@ export class Node extends AspectHost<NodeEvents> {
   setParent(parent: Node | null, worldPositionStays = false): this {
     if (parent === null) _creator.setParentNull(this.id, worldPositionStays)
     else _creator.setParent(this.id, parent.id, worldPositionStays)
-    if (worldPositionStays) this._lastSync = 0
     return this
   }
   traverse(callback: (node: Node) => void): void {
     callback(this)
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
   }
+  // --- materials (any renderable: a Mesh, or an internal node of a loaded Model) ---
+  /** The material assigned to slot 0 through this API (null before one is set — a GLB part's own
+   *  glTF material stays native-side). */
+  get material(): Material | null { return this.getMaterial(0) }
+  set material(m: Material) { this.setMaterial(m, 0) }
+  /** Replace the material of one primitive slot (`index` = the primitive's order in the glTF
+   *  mesh; a primitive-shape Mesh has one slot). */
+  setMaterial(material: Material, index = 0): this {
+    (this._materials ??= [])[index] = material
+    _creator.setMaterial(this.id, Material.idOf(material), index)
+    return this
+  }
+  /** The material previously assigned to `index` (null when none was — see Mesh for the probe). */
+  getMaterial(index = 0): Material | null {
+    return this._materials?.[index] ?? null
+  }
+
   /** Find a descendant by name — bones of a loaded Model included (`hero.bone('RightHand').add(sword)`).
    *  Same rule the Animator binds clips with: exact name first, then the part after the last `:` / `|`
    *  (Mixamo `mixamorig:Hips` matches `Hips`); a skinned joint beats a plain node of the same name.
@@ -260,8 +328,20 @@ export class Node extends AspectHost<NodeEvents> {
   _emitCollision(channel: "enter" | "exit", other: Node): void { this.dispatch(channel, other) }
 
 
+  /** Destroy this node and its whole subtree. Every aspect in the subtree is detached first (its
+   *  `onDetach` runs: physics bodies released, updaters unregistered, listeners dropped) — native
+   *  `destroyEntity` frees the entity tree but knows nothing about JS-side aspects, and a destroyed
+   *  node's `update()` must not keep ticking. Deepest nodes go first, then this one. */
   destroy(): void {
-    nodeRegistry.delete(this.id)
+    const subtree: Node[] = [this]
+    _creator.traverse(this.id, (id) => { const n = nodeRegistry.get(id); if (n) subtree.push(n) })
+    for (let i = subtree.length - 1; i >= 0; i--) {
+      const n = subtree[i]
+      n._detachAll()
+      n._xf = 0
+      n._xfKind = 0
+      nodeRegistry.delete(n.id)
+    }
     _creator.destroyEntity(this.id)
   }
 }

package/runtime/sdk/gl/Physics.ts

@@ -8,17 +8,23 @@
 //   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.
+// velocity / applyImpulse. Reading node.position is free (native already wrote it). A `position` write
+// is a TELEPORT that reaches the body (Shape routes it), which is how a kinematic body is placed too.
 
 import { Aspect } from "../core/Aspect"
 import type { FieldMeta } from "../core/fields"
+import type { CompAxis, CompWriter } from "../core/compWrite"
 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 }
+// Jolt's angular velocity is rad/s; every angle the SDK exposes is in degrees (like `eulerAngles`).
+const DEG2RAD = Math.PI / 180
+const RAD2DEG = 180 / Math.PI
+// Scratch for velocity reads (one per module, never handed out) — a read allocates the Vec3 only.
+const scratch = new Float32Array(3)
 
 export interface PhysicsConfig {
   /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
@@ -35,7 +41,14 @@ export interface RayHit {
   fraction: number
 }
 
-export class Physics extends Aspect<"physics", Node> {
+/**
+ * What a body's friction already is the moment the host creates it. This is part of the ABI, not an
+ * assumption: bridges.d.ts states it, so every host owes us this value. Knowing it lets attach skip
+ * a bridge call per body whenever nobody named a surface.
+ */
+export const DEFAULT_FRICTION = 0.6
+
+export class Physics extends Aspect<"physics", Node> implements CompWriter {
   static readonly aspect = "physics"
 
   /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
@@ -60,11 +73,19 @@ export class Physics extends Aspect<"physics", Node> {
    * 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.
+   * 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`.)
    */
-  friction = 0.6
+  get friction(): number { return this._friction }
+  set friction(v: number) {
+    this._friction = v
+    // Unconditional on a live body, unlike attach: it may be on its way BACK to the default from
+    // something else, and skipping that would leave the ice patch in place.
+    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, v)
+  }
+  private _friction = DEFAULT_FRICTION
 
   /** Scene-editor inspector: `motion` as a dropdown (a string default alone infers a text box). */
   static fields: FieldMeta<Physics> = {
@@ -86,7 +107,9 @@ export class Physics extends Aspect<"physics", Node> {
     }
     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()
+    // A fresh body already carries DEFAULT_FRICTION host-side, so only a NAMED surface has to
+    // travel — the common case costs no bridge call at all.
+    if (this._friction !== DEFAULT_FRICTION) _creator.physicsSetFriction?.(this._bodyId, this._friction)
     shape._ownBody(this._bodyId)
   }
 
@@ -99,26 +122,57 @@ export class Physics extends Aspect<"physics", Node> {
     }
   }
 
-  /** 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). */
+  /** Linear velocity in world units/second (fresh Vec3 on read; `velocity.y = 5` written directly on
+   *  the aspect is compiled to a component write — see `_writeComp`). */
   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])
+    if (!this._bodyId) return new Vec3(0, 0, 0)
+    _creator.physicsGetLinearVelocity(this._bodyId, scratch)
+    return new Vec3(scratch[0], scratch[1], scratch[2])
   }
   set velocity(v: Vec3Like) {
     if (this._bodyId) _creator.physicsSetLinearVelocity(this._bodyId, cx(v), cy(v), cz(v))
   }
 
+  /**
+   * Angular velocity — **degrees/second about each world axis** (the SDK's angle unit everywhere;
+   * the engine works in radians and converts here). Fresh Vec3 on read.
+   *
+   * This is the only handle on a body's spin, and placing an object usually needs it: a `position`
+   * write is a pure teleport, so a crate that was tumbling keeps tumbling at its new home. Putting
+   * something down is `body.velocity = [0,0,0]; body.angularVelocity = [0,0,0]; node.position = p`.
+   */
+  get angularVelocity(): Vec3 {
+    if (!this._bodyId || !_creator.physicsGetAngularVelocity) return new Vec3(0, 0, 0)
+    _creator.physicsGetAngularVelocity(this._bodyId, scratch)
+    return new Vec3(scratch[0] * RAD2DEG, scratch[1] * RAD2DEG, scratch[2] * RAD2DEG)
+  }
+  set angularVelocity(v: Vec3Like) {
+    if (this._bodyId && _creator.physicsSetAngularVelocity) {
+      _creator.physicsSetAngularVelocity(this._bodyId, cx(v) * DEG2RAD, cy(v) * DEG2RAD, cz(v) * DEG2RAD)
+    }
+  }
+
+  /** @internal chisel `comp_write` (see core/compWrite.ts): `body.velocity.y = v` / `body.angularVelocity.z
+   *  = v` written directly on the aspect compile to a call here — one read into the scratch, one set, no
+   *  vector. The list is compile-time data. */
+  static _comps = [ "velocity", "angularVelocity" ]
+  _writeComp(prop: string, axis: CompAxis, v: number): void {
+    if (!this._bodyId || axis === "w") return
+    const i = axis === "x" ? 0 : axis === "y" ? 1 : 2
+    if (prop === "velocity") {
+      _creator.physicsGetLinearVelocity(this._bodyId, scratch)
+      scratch[i] = v
+      _creator.physicsSetLinearVelocity(this._bodyId, scratch[0], scratch[1], scratch[2])
+    } else if (_creator.physicsGetAngularVelocity && _creator.physicsSetAngularVelocity) {
+      _creator.physicsGetAngularVelocity(this._bodyId, scratch)
+      scratch[i] = v * DEG2RAD
+      _creator.physicsSetAngularVelocity(this._bodyId, scratch[0], scratch[1], scratch[2])
+    }
+  }
+
   /** 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))
@@ -138,11 +192,8 @@ export class Physics extends Aspect<"physics", Node> {
     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
-  }
+  // No moveTo(): `node.position = p` IS the move. Shape hands the body id to the node, so a position
+  // write reaches the body — one way to place anything, whether or not physics is involved.
 
   // --- world (static) -------------------------------------------------------------------------
   /** Configure gravity / limits. Call once before creating bodies. */

package/runtime/sdk/gl/Scene.ts

@@ -6,8 +6,9 @@
 // direct light + shadows.
 
 import { Color, type ColorInput } from "../core/color"
-import { _installAspectFrames } from "../core/Aspect"
+import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem, _detachAllSystems, type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect"
 import { _bumpNavEpoch, _navEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
+import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { _requestCameraPermission } from "../plugins/permission"
@@ -18,6 +19,42 @@ import { Node, nodeRegistry } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 
+export type AmbientOcclusionOptions = {
+  /** Strength of the darkening (default 1). */
+  intensity?: number
+  /** How far the occlusion reaches, in metres (default 0.3). */
+  radius?: number
+  /** Falloff contrast; >1 tightens it into the crease (default 1). */
+  power?: number
+  /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
+  quality?: "low" | "medium" | "high" | "ultra"
+}
+
+export type FogOptions = {
+  /** A TINT on the in-scattered ambient, not an absolute colour: the engine multiplies it by the
+   *  environment luminance, so white (the default) means "fog as bright as the ambient" and the fog
+   *  brightens with `environmentIntensity`. Do NOT expect the same hex to look like it does in
+   *  `skybox` — that one IS an absolute radiance and reads roughly an order of magnitude brighter.
+   *  Tint towards the sky's hue; leave it white to sit at the ambient level. */
+  color?: ColorInput
+  /** Metres from the camera before the fog starts (default 0). */
+  start?: number
+  /** Extinction per metre at `height`; 0.01 ≈ clearly visible over ~100 m (default 0.01). */
+  density?: number
+  /** The fog's "sea level" in world Y (default 0). */
+  height?: number
+  /** How fast it thins with altitude, 1/m. 0 = uniform everywhere; higher = a ground-hugging layer
+   *  you can see over (default 0). */
+  heightFalloff?: number
+  /** Cap on how opaque it can get, 0–1 — keeps far shapes readable (default 1). */
+  maxOpacity?: number
+  /** Metres after which fog stops applying; 0 = everywhere (default 0). */
+  cutoff?: number
+  /** Take the colour from the environment in the view direction, tinted by `color`, instead of a
+   *  flat `color`. Convincing when the IBL is a real sky (default false). */
+  fromEnvironment?: boolean
+}
+
 export type SceneOptions = {
   /** Image-based ambient lighting (default on). */
   ibl?: boolean
@@ -31,8 +68,29 @@ export type SceneOptions = {
    *  saturation until very bright; `'linear'` clips each channel (what an engine without a
    *  tonemapper shows — saturated, Unity-without-post-processing look); `'filmic'` (Uncharted). */
   toneMapping?: "aces" | "neutral" | "linear" | "filmic"
-  /** Skybox / clear color. */
-  skybox?: ColorInput
+  /** The sky. Three forms:
+   *  - a colour — a flat clear colour;
+   *  - `{ texture }` — a KTX1 **cubemap**, the sharp `<name>_skybox.ktx` that filament's `cmgen`
+   *    produces from an equirectangular .hdr/.exr. This is the one to use for a real sky. Pass an
+   *    `asset('../assets/sky.ktx')` handle or a bare staged filename;
+   *  - `'environment'` — reuse the scene's IBL cubemap. Cheapest (no second texture) but that file
+   *    is prefiltered for roughness, so the sky comes out soft; fine as a fallback, not as the goal.
+   *
+   *  Either texture form draws through filament's own skybox pass: a full-screen pass in device
+   *  space after the opaque queue. No geometry, no meridian seam, no pole distortion — do NOT build
+   *  a sky dome or a fullscreen equirect material by hand, both are strictly worse. */
+  skybox?: ColorInput | "environment" | { texture: string }
+  /** Screen-space ambient occlusion — the contact darkening in creases and where props meet the
+   *  ground. Without it an IBL lights a crease exactly as brightly as an open face, so everything
+   *  reads as pasted onto the floor rather than standing on it. `true` takes defaults tuned for
+   *  human-scale props; `radius` is world-space metres and is the one knob that must follow the
+   *  scene's scale (~0.3 for objects on a table, ~0.6-1 for a yard of crates and containers). */
+  ambientOcclusion?: boolean | AmbientOcclusionOptions
+  /** Distance fog / aerial perspective: distant geometry loses contrast so the eye reads depth, and
+   *  the hard edge where a finite level ends against the skybox goes away. By default the fog applies
+   *  at every distance — the skybox included — so the sky itself takes the fog colour and the horizon
+   *  blends on its own; `cutoff` opts geometry beyond a distance back out. */
+  fog?: FogOptions
   /** 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. */
@@ -45,6 +103,27 @@ export type SceneOptions = {
    *  (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 }
+  /** Anisotropic filtering, 1 (off) … 16. Default 2. What it buys is detail on surfaces seen at a
+   *  GRAZING angle — a first-person weapon, a floor, a wall — where the sample footprint is far
+   *  longer in one axis than the other and isotropic filtering has to pick a mip for the long one,
+   *  several levels coarser than the short axis deserves. Measured on a weapon seen from the side
+   *  (local contrast): 8.18 at 1× → 10.02 at 2× → 10.84 at 4× → 11.29 at 8×. The default is 2
+   *  because it is where the curve is steepest per unit of memory bandwidth; raise it if you have
+   *  the headroom.
+   *
+   *  It is an ENGINE-WIDE default, not a property of this scene: a sampler is baked when its
+   *  texture is bound, so this reaches the models a scene loads AFTER it (which is every model in a
+   *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
+   *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
+  anisotropy?: number
+  /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
+   *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
+   *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
+   *  1..8 is where white lands as a multiple of SDR white — the "HDR brightness" of a console
+   *  calibration screen, where 1.5–2 is the norm; default 1 keeps a white wall at the UI's white,
+   *  faithful but dim next to what "HDR on" is expected to look like. Engine-wide like `anisotropy`;
+   *  `device.hdr` is the runtime form and tells you whether the display has any headroom at all. */
+  hdr?: { strength?: number; paperWhite?: number }
 }
 
 // Route aspect update(dt) through the render-synced native phases (render() early = before physics,
@@ -63,11 +142,16 @@ const installRenderSyncedFrames = (): void => {
     _creator.setLateUpdate(late)
     return true
   })
+  // Time.scale / Time.paused reach the engine's own clocks (physics, animators, particles) through
+  // setTimeScale; a host without it keeps running its sims at wall-clock speed (feature-detected).
+  _installTimeScale((scale) => { _creator.setTimeScale?.(scale) })
 }
 
 export class Scene implements Presentable {
   /** @internal native scene handle. */
   readonly _id: number
+  /** @internal the IBL intensity this scene was built with (Lightmap.load's ambient floor). */
+  _environmentIntensity = 20000
   readonly camera: Camera
 
   /** @internal touch listeners, read by the dispatch system. */
@@ -97,16 +181,26 @@ export class Scene implements Presentable {
     }
 
     if (options.ibl !== false) _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000)
+    this._environmentIntensity = options.ibl === false ? 0 : (options.environmentIntensity ?? 20000)
     if (options.bloom) _creator.setBloomOptions(this._id, true, options.bloomIntensity ?? 0.2, 1)
     if (options.toneMapping !== undefined && options.toneMapping !== "aces") {
       _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.skybox !== undefined) this.skybox = options.skybox
+    if (options.ambientOcclusion) this.setAmbientOcclusion(options.ambientOcclusion)
+    if (options.fog) this.setFog(options.fog)
     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)
     }
+    // Before anything else in this constructor that could load a texture: the value has to be in
+    // place by the time assets bind their samplers.
+    if (options.anisotropy !== undefined) _creator.setTextureAnisotropy?.(options.anisotropy)
+    if (options.hdr) {
+      if (options.hdr.strength !== undefined) device.hdr.strength = options.hdr.strength
+      if (options.hdr.paperWhite !== undefined) device.hdr.paperWhite = options.hdr.paperWhite
+    }
     if (options.renderScale !== undefined || options.dynamicResolution) {
       this.setRenderOptions(options.renderScale ?? 1, options.dynamicResolution ?? false)
     }
@@ -125,7 +219,34 @@ export class Scene implements Presentable {
     return this._material
   }
 
-  set skybox(color: ColorInput) { _creator.setSkybox(this._id, Color.toPackedRgb(color)) }
+  set skybox(sky: ColorInput | "environment" | { texture: string }) {
+    if (sky === "environment") { _creator.setSkyboxFromEnvironment?.(this._id); return }
+    if (typeof sky === "object" && sky !== null && "texture" in sky) {
+      const src = sky.texture
+      // `asset()` hands back "id:<n>" (already staged); a bare name is resolved on the spot.
+      const id = src.startsWith("id:") ? Number(src.slice(3)) : _creatorUtils.fetchLocal(src)
+      _creator.setSkyboxTexture?.(this._id, id)
+      return
+    }
+    _creator.setSkybox(this._id, Color.toPackedRgb(sky))
+  }
+
+  /** Runtime form of `ambientOcclusion` (a graphics-settings menu). `false` turns it off. */
+  setAmbientOcclusion(options: boolean | AmbientOcclusionOptions): void {
+    const o: AmbientOcclusionOptions = typeof options === "object" ? options : {}
+    const quality = { low: 0, medium: 1, high: 2, ultra: 3 }[o.quality ?? "medium"] ?? 1
+    _creator.setAmbientOcclusionOptions?.(this._id, options !== false, o.intensity ?? 1, o.radius ?? 0.3, o.power ?? 1, quality)
+  }
+
+  /** Runtime form of `fog` (weather, entering a building). `false` turns it off. */
+  setFog(options: FogOptions | false): void {
+    const o: FogOptions = options === false ? {} : options
+    _creator.setFogOptions?.(
+      this._id, options !== false, Color.toPackedRgb(o.color ?? "#ffffff"),
+      o.start ?? 0, o.density ?? 0.01, o.height ?? 0, o.heightFalloff ?? 0,
+      o.maxOpacity ?? 1, o.cutoff ?? 0, o.fromEnvironment ?? false,
+    )
+  }
 
   setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void {
     _creator.setMaterialGlobalParameter(this._id, i, x, y, z, w)
@@ -143,6 +264,41 @@ export class Scene implements Presentable {
     return this
   }
 
+  // ---- systems: aspects of the scene (core/Aspect.ts `System`) ----
+  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  readonly _systems = new Map<Function, Aspect<any, any, any>>()
+
+  /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed
+   *  as now-having it (`scene.system(Hud).hud`). A `System<'x', Scene2D>` is rejected here. */
+  // `this: Self` (not `Self & Scene`): with the intersection TS infers Self = Scene and a chain
+  // `scene.system(A).system(B)` loses A's accessor from the result type.
+  system<Self extends TargetOf<A>, A extends Aspect<any, any, any>>(
+    this: Self,
+    ctor: AspectCtor<A>,
+    opts?: Partial<A>,
+  ): Self & FieldOf<A> {
+    return _attachSystem(this as unknown as Scene, ctor, opts) as unknown as Self & FieldOf<A>
+  }
+  /** Safe access — undefined if the system isn't attached. */
+  get<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): A | undefined {
+    return this._systems.get(ctor) as A | undefined
+  }
+  /** Existence check AND type guard: inside `if (scene.has(Hud))`, `scene.hud` is present. */
+  has<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
+    return this._systems.has(ctor)
+  }
+  /** Detach a system (runs its onDetach). Chainable. */
+  removeSystem<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this {
+    _detachSystem(this, ctor)
+    return this
+  }
+  /** Tear the scene down: every system detaches (last-attached first) and the scene closes. Nodes
+   *  are yours — destroy the ones you own; the native scene object itself is not released. */
+  destroy(): void {
+    _detachAllSystems(this)
+    this.close()
+  }
+
   createOverlay(options: SceneOptions = {}): Scene {
     return new Scene({ ...options, _parent: this } as any)
   }