lecodes-sdk 2.8.0 → 2.8.2

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.18.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.8.0",
+  "version": "2.8.2",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -317,6 +317,10 @@ declare global {
     /** @count count=pages */
     staticsBuildKind?(kind: u32, templateEntity: u32, pages: Uint32Array): u32
     staticsEnd?(): u32
+    /** The cached placement an engine-built static came from: its full node path, "" = not one. The paths outlive
+     *  `staticsEnd` (until the next `staticsBegin`; a destroyed entity is forgotten) so gl/Node.ts `nodeOf` can give
+     *  a hit wall its passive aspects from the scene's def. */
+    staticsPathOf?(entityId: u32): string
     setCulling(entityId: u32, culling: boolean): void
     /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
      *  Optional: an older host leaves everything at the default 4. */
@@ -912,6 +916,9 @@ declare global {
     physicsCreateBody(entityId: u32, shapeId: u32, motion: i32, mass: f32, sensor: boolean, pickOnly: boolean): u32
     /** @ifdef CREATOR_GL_PHYSICS */
     physicsSetPickable(bodyId: u32, pickable: boolean): void
+    /** The motion of the body on `entityId`: 0 static, 1 kinematic, 2 dynamic, -1 no body — read off the engine, so it
+     *  answers for a body the SDK never made (a static the level cache built). @ifdef CREATOR_GL_PHYSICS */
+    physicsMotionOf?(entityId: u32): i32
     /** Surface friction of one body (0 = ice, ~1 = grippy asphalt). Values COMBINE as sqrt(a * b), so
      *  a low value on either side dominates. New bodies start at 0.6 — a neutral solid surface.
      *  The vehicle wheel cast reads the GROUND body's value — this is what caps a car's cornering. @ifdef CREATOR_GL_PHYSICS */

package/src/bridges/tree.d.ts

@@ -217,6 +217,11 @@ declare global {
  *  listeners are a flag mask, events go back through the runtime's entry points with the node id.
  *  One implementation per platform: renderers/tgfx (desktop, Quest), the Kotlin views (Android),
  *  UIKit (Apple), the null renderer of lecodes-server.
+ *  The runtime calls it through a QUEUE (runtime/native src/host/hostqueue.h, docs/plans/
+ *  host-commit-plan.md): a write reaches the host at the next commit — the end of the tick, before
+ *  a layout, before a read — in the order the runtime made it; a slot with a result commits first
+ *  and answers at once; an `@immediate` slot commits first and is called at once (its callbacks and
+ *  borrowed values are never kept).
  *  @host ui HostUI */
 export interface HostUI {
   /** Create the host view for a node of `type` ("column", "text", "image", "input", "screen", …).
@@ -259,7 +264,8 @@ export interface HostUI {
   viewVersion?(name: string): i32
   /** NativeView channel: invoke `method` on the live instance `viewId`; `args` is the array of the
    *  call's arguments, valid for the call. Settle exactly one of the two callbacks through the
-   *  dispatch bridge — `onComplete` with the result as ONE value, or with none. */
+   *  dispatch bridge — `onComplete` with the result as ONE value, or with none.
+   *  @immediate its callbacks and the borrowed `args` cannot wait for a commit */
   viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
   /** A LAYER root is shown: a pass-through root the runtime lays out at the frame, above every
    *  destination (the app layer) or over the presented surface (a scene's / a native view's / a
@@ -272,8 +278,10 @@ export interface HostUI {
   /** The layer root is hidden (its view stays; releaseNode says when it is gone). */
   layerClose(node: nodeid): void
   /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle
-   *  one of the callbacks through the dispatch bridge. */
+   *  one of the callbacks through the dispatch bridge.
+   *  @immediate its callbacks cannot wait for a commit */
   registerFont(url: string, fontFamily: string, weight: i32, style: i32, onComplete: () => void, onReject: (err: string) => void): void
+  /** @immediate not a tree write */
   showToast(message: string, duration: i32): void
   /** Is the button node currently pressed (the UIButton.isPressed getter)? */
   getButtonPressed(node: nodeid): boolean
@@ -284,9 +292,11 @@ export interface HostUI {
    *  it. @out 4 */
   getBoundingRect?(node: nodeid): Float32Array | null
   /** A node's touchStart / longPress listener took the gesture (`ev.track`): keep feeding this
-   *  pointer's moves (`claim` = a PanDirection bitmask, `hasMove` = it wants onMove). */
+   *  pointer's moves (`claim` = a PanDirection bitmask, `hasMove` = it wants onMove).
+   *  @immediate the answer belongs to the gesture the host is tracking */
   touchHandler?(pointerId: i32, hasMove: boolean, claim: u8, node: nodeid): void
-  /** A long press was HANDLED: swallow the click that would follow the release. */
+  /** A long press was HANDLED: swallow the click that would follow the release.
+   *  @immediate the answer belongs to the gesture the host is tracking */
   longPressHandler?(pointerId: i32, node: nodeid): void
   /** Virtualized list: apply a scroll position (physical px). `animated` false = anchoring (idempotent,
    *  after the content height update), true = a user scroll command. */

package/src/core/Aspect.ts

@@ -533,6 +533,13 @@ export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}
   static after?: Function[]
   /** Tick BEFORE these classes within the same phase (`static before = [Camera]`). */
   static before?: Function[]
+  /** DATA ONLY. A `use(...)` of this aspect in a scene file leaves its node STATIC for the level cache (gl/Statics.ts):
+   *  the engine builds the node without a JS object, and the aspect is attached the first time a hit, a contact or
+   *  a pick reaches the node — `hit.node.get(Surface)` answers then. So: fields and the methods the game calls on a
+   *  hit (a tag like `Surface { kind }`, a breakable's hit points), no `update()` (`use()` refuses one) and nothing in
+   *  `onAttach()` the level needs from its first frame. Without it a custom aspect keeps its node on the JS path,
+   *  built at load like any mover. */
+  static passive?: boolean
 
   /** Every live instance of an aspect/system class, in attach order — the registry a game used to
    *  hand-roll as `static all[]`. Live, read-only: copy it (`[...Aspect.all(Barrel)]`) before a loop

package/src/gl/Node.ts

@@ -51,8 +51,14 @@ const registerLoose = (n: Node): void => {
   sinceSweep = 0
   for (const [id, ref] of loose) { const w = ref.deref(); if (!w || w._h.id !== id) loose.delete(id) }
 }
+/** @internal The static level cache's hand into `nodeOf` (gl/Statics.ts sets it while a cached level is up):
+ *  `pathOf` names the placement an engine-built entity came from ("" = not one), `attach` gives that entity's
+ *  fresh wrapper the PASSIVE aspects of the placement's def (Aspect.passive). A wall the engine built has no JS
+ *  node until a hit, a contact or a pick reaches it — this is where it gets one, and its `Surface`, and only then. */
+export const lazyPlacements: { current: { pathOf(id: number): string, attach(node: Node, path: string): void } | null } = { current: null }
+
 /** @internal The wrapper for an entity id the runtime handed back: the pinned one, else the
- *  app's live loose handle, else a throwaway over the engine-owned id. */
+ *  app's live loose handle, else a wrapper over the engine-owned id (pinned: the next ask finds it). */
 export const nodeOf = (id: number): Node => {
   const pinned = nodes.get(id)
   if (pinned) return pinned
@@ -62,7 +68,18 @@ export const nodeOf = (id: number): Node => {
     if (w && w._h.id === id) return w
     loose.delete(id)
   }
-  return new Node(id)
+  const n = new Node(id)
+  const lazy = lazyPlacements.current
+  if (lazy) { const path = lazy.pathOf(id); if (path) lazy.attach(n, path) }
+  return n
+}
+
+/** @internal `nodeOf(id)` when `id` is a placement the level cache built, else null — a hit inside a model walks
+ *  up to the placement's own entity (gl/touch.ts). */
+export const placementNodeOf = (id: number): Node | null => {
+  if (nodes.get(id)) return nodeOf(id)
+  const lazy = lazyPlacements.current
+  return lazy && lazy.pathOf(id) ? nodeOf(id) : null
 }
 
 export type NodeEvents = {
@@ -472,6 +489,8 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
 
   /** @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 — does anyone listen on `channel` (the physics-event router asks before it makes a wrapper). */
+  _hasListeners(channel: keyof NodeEvents): boolean { return this.hasListeners(channel) }
 
 
   /** Destroy this node and its whole subtree. Every aspect in the subtree is detached first (its

package/src/gl/Statics.ts

@@ -24,7 +24,7 @@
 
 import { fetch, assetNameOf, assetUrlOf, type FetchResponse } from "../runtime/fetch"
 import { Model, foliageKindOf, type FoliageKind } from "./Model"
-import { Node } from "./Node"
+import { Node, lazyPlacements } from "./Node"
 import { Scene } from "./Scene"
 import { Physics } from "./physics/Physics"
 import { Shape } from "./physics/Shape"
@@ -57,11 +57,49 @@ const movesByPhysics = (def: SceneNodeDef): boolean =>
     ((e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
     || (e.ctor as unknown) === CharacterController)
 
+/** A passive aspect (Aspect.passive): data the engine does not need — attached to the placement's wrapper on the
+ *  first hit (`attachPassive`), never built at load. */
+export const isPassive = (e: AspectEntry<any>): boolean => (e.ctor as { passive?: boolean }).passive === true
+
 const dataAspect = (e: AspectEntry<any>): boolean => {
   const c = e.ctor as unknown
   if (c === Shape) return true
   if (c === Physics) return ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") === "static"
-  return false
+  return isPassive(e)
+}
+
+/** Attach the passive aspects of `def` to `node` (props as written: a passive aspect is data, `ref()`s are not
+ *  resolved). Who gets them: the entity a hit comes back with. A placement's clone, on the first hit, through
+ *  `lazyPlacements` — a covered root with a model included, since its clone is what the ray strikes, not the plain
+ *  JS node the clone hangs under. A root WITHOUT a model (a group tagged `Surface` over its walls) has no clone:
+ *  its JS node takes them at load, and a hit on a wall under it finds them one `parent` up (a game's surface lookup
+ *  walks `hit.node.parent`). */
+export const attachPassive = (node: Node, def: SceneNodeDef): void => {
+  for (const e of def.aspects ?? []) if (isPassive(e)) (node as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(e.ctor, e.props)
+}
+
+/** The covered placements that carry passive aspects, by path: every def under the roots, and a root itself when
+ *  it has a model (its clone is a placement at the root's own path). A model-less root is not here — `attachPassive`
+ *  put its tags on its JS node at load. */
+const passiveByPath = (roots: CoveredRoot[], scene: SceneDef): Map<string, SceneNodeDef> => {
+  const out = new Map<string, SceneNodeDef>()
+  const walk = (defs: Record<string, SceneNodeDef> | undefined, prefix: string, stack: Set<SceneDef>): void => {
+    for (const [ name, nd ] of Object.entries(defs ?? {})) {
+      const path = prefix === "" ? name : `${prefix}/${name}`
+      if ((nd.aspects ?? []).some(isPassive)) out.set(path, nd)
+      walk(nd.children, path, stack)
+      const pdef = nd.prefab !== undefined ? (nd.prefab as { def?: SceneDef }).def : undefined
+      if (pdef && !stack.has(pdef)) walk(pdef.nodes, path, new Set(stack).add(pdef))
+    }
+  }
+  const stack = new Set<SceneDef>([ scene ])
+  for (const r of roots) {
+    if (r.def.model !== undefined && (r.def.aspects ?? []).some(isPassive)) out.set(r.path, r.def)
+    walk(r.def.children, r.path, stack)
+    const pdef = r.def.prefab !== undefined ? (r.def.prefab as { def?: SceneDef }).def : undefined
+    if (pdef && !stack.has(pdef)) walk(pdef.nodes, r.path, new Set(stack).add(pdef))
+  }
+  return out
 }
 
 const cacheable = (def: SceneNodeDef, stack: Set<SceneDef>): boolean => {
@@ -288,8 +326,16 @@ const templates: Model[] = []
 export const build = async (
   opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array,
   template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>,
+  covered: CoveredRoot[], def: SceneDef,
 ): Promise<number> => {
   const sceneId = (scene as unknown as { _id: number })._id
+  // the hand into nodeOf for this level's life (the next cached level replaces it; a level without passive
+  // aspects under its roots installs none — nodeOf then costs what it did)
+  const passive = passiveByPath(covered, def)
+  lazyPlacements.current = passive.size > 0 && _creator.staticsPathOf ? {
+    pathOf: (id) => _creator.staticsPathOf!(id),
+    attach: (node, path) => { const d = passive.get(path); if (d) attachPassive(node, d) },
+  } : null
   const kinds = _creator.staticsBegin!(sceneId, Uint32Array.from(roots.map((r) => r.id)), (opened.resp as unknown as { _h: { id: number } })._h.id)
   if (kinds !== opened.kinds.length) { console.warn(`[static] the engine declined the cache (${kinds} of ${opened.kinds.length} kinds)`); _creator.staticsEnd!(); return 0 }
   await Promise.all(opened.kinds.map(async (k, i) => {

package/src/gl/physics/CharacterController.ts

@@ -33,7 +33,9 @@
 // scaled directly instead of needing a child node for the visuals (a capsule is symmetric about its up
 // axis, so its yaw is physically irrelevant either way).
 //
-// CROUCHING goes through the Shape aspect (`node.aspect(Shape, { capsule: … })`) — see `resizing`.
+// CROUCHING is a property write on the Shape aspect (`hero.shape.capsule = …`) — see `resizing`. The
+// node (the capsule's centre) has moved by the feet difference when the write returns; a first-person
+// camera is placed from the FEET plus an eased eye height, never from the node (docs/3d/physics.md).
 //
 // 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.
@@ -160,13 +162,18 @@ export class CharacterController extends Aspect<"controller", Node> implements C
    * True while a requested collider resize hasn't taken — you asked to stand up and there is something
    * overhead. Resizing goes through the `Shape` aspect itself:
    *
-   *     hero.aspect(Shape, { capsule: CROUCHED })   // always fits — you are shrinking
-   *     hero.aspect(Shape, { capsule: STANDING })   // may be refused under a low ceiling
-   *     if (hero.controller.resizing) …             // still crouched; call it again next frame
+   *     hero.shape.capsule = CROUCHED               // always fits — you are shrinking
+   *     hero.shape.capsule = STANDING               // may be refused under a low ceiling
+   *     if (hero.controller.resizing) …             // still crouched; write it again next frame
    *
    * A refusal changes nothing, so the retry is just the same call again — and it is an exact headroom
    * test against the real capsule, unlike a hand-rolled raycast (a ray is a line; a capsule has girth).
-   * The FEET stay planted across a resize, so the character neither hovers nor sinks.
+   * The FEET stay planted across a resize, so the character neither hovers nor sinks — which means the
+   * node (the capsule's centre) has ALREADY moved by the feet difference when the write returns. Place
+   * a first-person camera from the feet (`node.y − (halfHeight + radius)` of the capsule worn) plus an
+   * eased eye height; placed from the node it pops by that difference. Write the property: a second
+   * `node.aspect(Shape, …)` builds a fresh Shape (it is handed to the character too, but it is a
+   * rebuild per stance, not a resize).
    */
   get resizing(): boolean {
     return this.node.get(Shape)?._resizeRefused ?? false

package/src/gl/physics/Physics.ts

@@ -15,7 +15,7 @@ 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 { nodes, type Node } from "../Node"
+import { nodeOf, type Node } from "../Node"
 import { Shape } from "./Shape"
 
 export type MotionType = "static" | "dynamic" | "kinematic"
@@ -214,13 +214,27 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
     return typeof _creator !== "undefined" && !!_creator && typeof _creator.physicsHasSupport === "function" && _creator.physicsHasSupport()
   }
 
-  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+  /** The motion of the body on `node`, read off the engine: it answers for a body the SDK never made (a static the
+   *  level cache built, which has no `Physics` aspect until a hit reaches it, and no body-making one ever). null = no
+   *  body on this node. The way to tell a wall from a prop on a hit: `Physics.motionOf(hit.node) === "static"`. */
+  static motionOf(node: Node | null): MotionType | null {
+    if (!node) return null
+    if (_creator.physicsMotionOf) {
+      const m = _creator.physicsMotionOf(node.id)
+      return m === 0 ? "static" : m === 1 ? "kinematic" : m === 2 ? "dynamic" : null
+    }
+    return node.get(Physics)?.motion ?? null   // an older host: the aspect is all there is
+  }
+
+  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. `node` is the body's
+   *  node — for a static the level cache built, a wrapper made on this hit (Node.ts nodeOf), carrying the placement's
+   *  passive aspects; its `Physics` is read with `Physics.motionOf`. */
   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: nodes.get(id) ?? null,
+      node: nodeOf(id),
       point: new Vec3(out[0], out[1], out[2]),
       normal: new Vec3(out[3], out[4], out[5]),
       fraction: out[6],

package/src/gl/physics/Shape.ts

@@ -127,14 +127,25 @@ export class Shape extends Aspect<"shape", Node> {
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
     this._shapeId = this._build()
-    if (this._shapeId) this._createPickBody()
+    if (!this._shapeId) return
+    // A fresh Shape on a node a live CharacterController owns: `node.aspect(Shape, { capsule })`
+    // RE-ATTACHES (aspect() always builds), which is how a game is tempted to crouch. Hand the geometry
+    // to the character exactly as a property write does. A pick body here would instead take the
+    // node's position routing away from the character, and the capsule it wears would never change —
+    // the player's "how tall am I" switches while the body stays, and the eye pops by the difference.
+    if (this.node._xfKind === 1) {
+      if (!this._offerToCharacter(this.node._xf, this._shapeId)) this._sig = ""   // uncommitted: the next write retries
+      return
+    }
+    this._createPickBody()
   }
 
   onDetach(): void {
     if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
     if (this._shapeId) { _creator.physicsDestroyShape(this._shapeId); this._shapeId = 0 }
-    this.node._xf = 0
-    this.node._xfKind = 0
+    // The routing is this Shape's to clear only while one of ITS bodies carries it. A live
+    // CharacterController keeps its own, and the geometry it wears (Jolt holds a reference to it).
+    if (this.node._xfKind !== 1) { this.node._xf = 0; this.node._xfKind = 0 }
   }
 
   /** A dimension, the kind or the origin was written: rebuild the geometry when it actually changed.
@@ -298,17 +309,12 @@ export class Shape extends Aspect<"shape", Node> {
     // and tries again. That retry is the headroom test, and it is exact (the real capsule, not a ray).
     const charId = this.node._xfKind === 1 ? this.node._xf : 0
     if (charId) {
-      if (_creator.characterSetShape?.(charId, id)) {
+      if (this._offerToCharacter(charId, id)) {
         this._shapeId = id
-        this._resizeRefused = false
         _creator.physicsDestroyShape(previous)
       } else {
         _creator.physicsDestroyShape(id)     // drop what we just built; the old collider stays live
         this._sig = previousSig
-        this._resizeRefused = !!_creator.characterSetShape
-        if (!_creator.characterSetShape) {
-          console.warn(`Shape: this host can't resize a live CharacterController — "${this.node.name}" keeps its current collider`)
-        }
       }
       return
     }
@@ -327,6 +333,20 @@ export class Shape extends Aspect<"shape", Node> {
    *  is still using another. Surfaced as `controller.resizing`. */
   _resizeRefused = false
 
+  /** The character this node belongs to tries the geometry on. Jolt validates the fit (standing up
+   *  under a pipe) and can refuse; a refusal changes nothing in the engine. The feet stay planted, so
+   *  on success the node has already moved by the change in the shape's lower bound when this returns. */
+  private _offerToCharacter(charId: number, shapeId: number): boolean {
+    if (!_creator.characterSetShape) {
+      console.warn(`Shape: this host can't resize a live CharacterController — "${this.node.name}" keeps its current collider`)
+      this._resizeRefused = false
+      return false
+    }
+    const ok = _creator.characterSetShape(charId, shapeId)
+    this._resizeRefused = !ok
+    return ok
+  }
+
   private _build(): number {
     this._autoOrigin = null
     this._sig = this._signature()

package/src/gl/physics/physicsEvents.ts

@@ -2,7 +2,7 @@
 // is delivered to BOTH nodes with the other as the argument. type: 0 = enter (contact/overlap began),
 // 1 = exit (ended). Registered lazily on the first trigger/physics body or 'enter'/'exit' listener.
 
-import { nodes } from "../Node"
+import { nodes, nodeOf } from "../Node"
 
 let registered = false
 export const ensurePhysicsEvents = (): void => {
@@ -10,10 +10,15 @@ export const ensurePhysicsEvents = (): void => {
   if (!_creator.setOnPhysicsEvent) return // physics-less build / bridge without the hook
   registered = true
   _creator.setOnPhysicsEvent((a, b, type) => {
-    const na = nodes.get(a)
-    const nb = nodes.get(b)
-    if (!na || !nb) return
+    const ka = nodes.get(a)
+    const kb = nodes.get(b)
     const channel = type === 1 ? "exit" : "enter"
+    // nobody listening on either side: nothing to deliver, and no wrapper made for the other side (a car's
+    // wheels touch every tile of a road the level cache built — a wrapper each would be 15k for nothing)
+    if (!ka?._hasListeners(channel) && !kb?._hasListeners(channel)) return
+    // the side nobody holds (a static the engine built) gets its wrapper now, passive aspects and all (Node.ts nodeOf)
+    const na = ka ?? nodeOf(a)
+    const nb = kb ?? nodeOf(b)
     na._emitCollision(channel, nb)
     nb._emitCollision(channel, na)
   })

package/src/gl/touch.ts

@@ -3,7 +3,7 @@
 
 import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch"
 import { ensureEmitter, setSceneTouchHandlers } from "../ui/tree"
-import { nodes } from "./Node"
+import { nodes, placementNodeOf } from "./Node"
 import { glState } from "./state"
 
 // Hits inside a loaded model (GLB) land on sub-entities the user never created a Node for — walk up
@@ -15,6 +15,9 @@ const resolveHitNode = (entityId: number) => {
     if (id === 0) break
     node = nodes.get(id)
   }
+  // nobody holds any of them: a static the level cache built — its placement's entity up the chain gets a wrapper
+  // now (Node.ts nodeOf), passive aspects and all
+  for (let id = entityId, i = 0; !node && id !== 0 && i < 32; i++, id = _creator.getParent(id)) node = placementNodeOf(id) ?? undefined
   return node ?? null
 }
 

package/src/inject.ts

@@ -63,6 +63,8 @@ export { audio, type PlaySoundOptions, type SpatialOptions, type Rolloff, type A
 export { openFilePicker, files, type FileData } from "./runtime/files"
 export { share } from "./runtime/share"
 export { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "./runtime/touch"
+// Pan, pinch and twist as one gesture over the per-pointer tracks (see src/runtime/gestures.ts).
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures"
 
 // ---- 2D engine (creator-2d) ----
 export { Scene2D } from "./g2/Scene2D"

package/src/plugin.ts

@@ -31,7 +31,8 @@ export type { NativeView } from "./ui/NativeView"
 export type { FetchResponse } from "./runtime/fetch"
 // The 3D a wrapper builds on (the "ar" plugin's ARScene — docs/plans/ar-plugin-plan.md): the scene it
 // extends, the node its anchors are, the mesh it draws a plane's grid with, the math of a pose, the
-// touch a placement gesture follows, the System its per-frame work rides on (the scene's first frame).
+// touch a placement gesture follows (and `trackGesture`, the pan / pinch / twist over it), the System
+// its per-frame work rides on (the scene's first frame).
 // Re-exported, never copied, as the UI above.
 export { Scene, type SceneOptions } from "./gl/Scene"
 export { System } from "./core/Aspect"
@@ -43,6 +44,7 @@ export { Vec2, Vec3, type Vec3Like } from "./math/vec"
 export { Quat, type QuatLike } from "./math/quat"
 export { Mat4 } from "./math/mat4"
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch"
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures"
 export type { DismissOptions } from "./ui/presentable"
 /** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
  *  reads the device's address from, registers through, and a push channel's handlers are kept by. */

package/src/plugins/gen/ar/sdk/ar.ts

@@ -12,8 +12,8 @@
 // the present (a host mounts and sizes the scene's view after it). A host without the plugin is
 // refused before anything is asked.
 //
-// `root` is a pose anchor like any other (`scene.anchor(pose)`): the wrapper pins it on the first
-// horizontal plane the session reports, so the halves know no root.
+// `root` is a pose anchor like any other (`scene.anchor(pose)`), placed by the wrapper — in front of
+// the user on the first floor the session reports (`_placeRoot`) — so the halves know no root.
 
 import {
   Geometry, Mat4, Material, Mesh, Node, Presentable, Quat, Router, Scene, System, Vec3, _ensurePermission, _navEpoch, _toFile,
@@ -63,6 +63,9 @@ export type ARSceneOptions = SceneOptions & {
   /** "world" (default): planes, hit tests, anchors, image and QR targets. "images": image and QR
    *  targets only — lighter on iOS; no planes, no hit test, no `root`. */
   mode?: ARMode
+  /** How far in front of the user `root` is placed, metres (default 1): along the camera's heading,
+   *  on the floor. */
+  rootDistance?: number
 }
 
 export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images" | "codes"> & {
@@ -269,6 +272,8 @@ export class ARScene extends Scene {
   static get isSupported(): boolean { return supports() }
 
   readonly mode: ARMode
+  /** Metres between the user and `root` when it is placed (`rootDistance` option, default 1). */
+  readonly rootDistance: number
   /** `open()` warm-renders the scene first (default true). */
   useWarmRender = true
 
@@ -291,8 +296,9 @@ export class ARScene extends Scene {
   private _codesWarned = false
   private _options: AROpenOptions = {}
   private _root: Anchor | null = null
-  /** The first horizontal plane's pose: where `root` is pinned. */
-  private _floor: ARPose | null = null
+  /** The floor's height (world Y, metres): the first horizontal plane below the camera this session
+   *  found. Null until one is; `root` is placed on it. */
+  private _floor: number | null = null
   /** The image targets. `source` is held for the bytes: a fetched response owns its buffer, which the
    *  host frees once the response is collected — the File the session is handed only names it. */
   private readonly _images: { anchor: ImageAnchor, image: File, width: number, source: FetchResponse | File }[] = []
@@ -310,6 +316,7 @@ export class ARScene extends Scene {
   constructor(options: ARSceneOptions = {}) {
     super(options)
     this.mode = options.mode ?? "world"
+    this.rootDistance = options.rootDistance ?? 1
   }
 
   /** The tracking quality: "notAvailable" before a session, "limited" (with `trackingReason`) while
@@ -328,8 +335,12 @@ export class ARScene extends Scene {
     for (const plane of this._planes.values()) this._drawPlane(plane)
   }
 
-  /** The floor: an anchor pinned on the first horizontal plane the session finds (it fires `track`
-   *  then). Until that it is the world's origin — where the session began. Not in "images" mode. */
+  /** The place in front of the user: an anchor `rootDistance` metres ahead of the camera along its
+   *  heading, on the floor — the first horizontal plane below the camera the session finds; it is
+   *  pinned there and fires `track` then — turned the way the user looks (its −Z along the heading,
+   *  so a model's front, +Z, faces the user). Until the floor is found (and on the web, which finds
+   *  none) it sits the same way at the camera's own height, not pinned. Made on first use; put
+   *  content under it. `placeRoot()` puts it in front of the user again. Not in "images" mode. */
   get root(): Anchor {
     if (this._root) return this._root
     if (this.mode === "images") throw new Error('ARScene.root: there is no root in the "images" mode')
@@ -337,10 +348,19 @@ export class ARScene extends Scene {
     root._scene = this
     this.add(root)
     this._root = root
-    if (this._floor) this._pinRoot(this._floor)
+    this._placeRoot()
     return root
   }
 
+  /** Put `root` in front of the user again — where they look now, `rootDistance` metres ahead, on the
+   *  floor if one is known (the camera's height otherwise), facing them: a "reset" button, or a
+   *  placement after the user has moved. Makes `root` when there is none yet. */
+  placeRoot(): Anchor {
+    if (!this._root) return this.root
+    this._placeRoot()
+    return this._root
+  }
+
   /** An anchor that follows an image (a printed marker, a poster): the session finds it in the camera
    *  image and keeps the anchor on it — a rigid pose in metres (its centre, Y out of the image, the
    *  image in XZ), its size `anchor.extent`. `physicalWidth` = the printed width in metres. Hidden
@@ -679,11 +699,34 @@ export class ARScene extends Scene {
     this._pin(anchor, pose)
   }
 
-  /** `root` onto the floor (the first horizontal plane of this session). */
-  private _pinRoot(pose: ARPose): void {
+  /** Where `root` goes now: `rootDistance` metres from the camera along its heading (its forward
+   *  flattened to the floor; looking straight down or up, the way the top of the screen points), at
+   *  the floor's height when one is known, else the camera's; turned so its −Z runs along the
+   *  heading — a model's front (+Z) faces the user. */
+  private _rootPose(): ARPose {
+    const camera = this.camera
+    const eye = camera.worldPosition
+    const forward = camera.forward
+    let heading = new Vec3(forward.x, 0, forward.z)
+    if (heading.lengthSq() < 1e-6) {
+      // straight down (the usual way to look at a floor) or up: the screen's top points the way
+      const up = Vec3.up.rotate(camera.worldMatrix.rotation)
+      heading = new Vec3(up.x, 0, up.z)
+      if (forward.y > 0) heading = heading.negate()
+      if (heading.lengthSq() < 1e-6) heading = new Vec3(0, 0, -1)
+    }
+    heading = heading.normalize()
+    const position = new Vec3(eye.x + heading.x * this.rootDistance, this._floor ?? eye.y, eye.z + heading.z * this.rootDistance)
+    return { position, rotation: Quat.lookRotation(heading) }
+  }
+
+  /** `root` in front of the user: moved there now, and pinned there when the floor is known (a
+   *  session holds a pin; without one `_pinAll` does not re-pin root — it waits for its own floor). */
+  private _placeRoot(): void {
     const root = this._root!
+    const pose = this._rootPose()
     root.worldMatrix = Mat4.compose(pose.position, pose.rotation)
-    this._pin(root, pose)
+    if (this._floor !== null) this._pin(root, pose)
   }
 
   private _pin(anchor: Anchor, pose: ARPoseLike): void {
@@ -741,10 +784,12 @@ export class ARScene extends Scene {
     plane._polygon = p.polygon
     plane._setTracked(true)
     this._drawPlane(plane)
-    // the floor: the first horizontal plane, where root is pinned
-    if (added && p.type === "horizontal" && !this._floor) {
-      this._floor = pose
-      if (this._root) this._pinRoot(pose)
+    // the floor: the first horizontal plane below the camera (a ceiling is "horizontal" too), where
+    // root is placed — in front of the user, at the plane's height; the plane's centre and turn are
+    // a patch's and say nothing about where the user is
+    if (added && p.type === "horizontal" && this._floor === null && pose.position.y < this.camera.worldPosition.y) {
+      this._floor = pose.position.y
+      if (this._root) this._placeRoot()
     }
     this._emit("plane", { plane, change: added ? "added" : "updated", mergedInto: null })
   }