lecodes-sdk 2.2.8 → 2.2.10

package/src/gl/Mesh.ts

@@ -1,120 +1,120 @@
-// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
-// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
-
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import {
-  Geometry,
-  type CapsuleOptions,
-  type CylinderOptions,
-  type PlaneOptions,
-  type SphereOptions,
-} from "./Geometry"
-import { Material } from "./Material"
-import { Node } from "./Node"
-
-/** Common transform/render options every primitive factory accepts. */
-export type MeshOptions = {
-  material?: Material
-  position?: Vec3Like
-  eulerAngles?: Vec3Like
-  scale?: Vec3Like | number
-  name?: string
-  castShadows?: boolean
-  receiveShadows?: boolean
-  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
-  renderPriority?: number
-}
-
-export class Mesh extends Node {
-  private _geometry?: Geometry
-
-  constructor(geometry?: Geometry, material?: Material) {
-    super()
-    if (geometry) {
-      const mat = material ?? Material.unlit()
-      this._geometry = geometry
-      this._materials = [ mat ]
-      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
-    }
-  }
-
-  override get geometry(): Geometry | undefined { return this._geometry }
-  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
-   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
-  setGeometry(geometry: Geometry): this {
-    this._geometry = geometry
-    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
-    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
-    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
-    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
-    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
-    if (this._culling !== undefined) this.culling = this._culling
-    if (this._castShadows !== undefined) this.castShadows = this._castShadows
-    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
-    return this
-  }
-  private _renderPriority?: number
-  private _culling?: boolean
-  private _castShadows?: boolean
-  private _receiveShadows?: boolean
-
-  /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
-  override get material(): Material { return this._materials![0]! }
-  override set material(m: Material) { this.setMaterial(m, 0) }
-
-  set culling(v: boolean) { this._culling = v; _creator.setCulling(this.id, v) }
-  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
-   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
-   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
-   *  after it can cover it. Write-only; a host that predates the call ignores it. */
-  set renderPriority(v: number) {
-    this._renderPriority = v
-    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
-    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
-  }
-  private static _warnedPriority = false
-  set castShadows(v: boolean) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
-  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
-
-  // --- factories ---
-
-  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
-    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
-  }
-
-  static sphere(options: MeshOptions & SphereOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.sphere(options), options.material), options)
-  }
-
-  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
-  }
-
-  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
-  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.capsule(options), options.material), options)
-  }
-
-  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.plane(options), options.material), options)
-  }
-
-  /** Wrap a custom Geometry. */
-  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
-    return apply(new Mesh(geometry, options.material), options)
-  }
-}
-
-const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
-
-const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
-  if (o.position) mesh.position = o.position
-  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
-  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
-  if (o.name !== undefined) mesh.name = o.name
-  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
-  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
-  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
-  return mesh
-}
+// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
+// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
+
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import {
+  Geometry,
+  type CapsuleOptions,
+  type CylinderOptions,
+  type PlaneOptions,
+  type SphereOptions,
+} from "./Geometry"
+import { Material } from "./Material"
+import { Node } from "./Node"
+
+/** Common transform/render options every primitive factory accepts. */
+export type MeshOptions = {
+  material?: Material
+  position?: Vec3Like
+  eulerAngles?: Vec3Like
+  scale?: Vec3Like | number
+  name?: string
+  castShadows?: boolean
+  receiveShadows?: boolean
+  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
+  renderPriority?: number
+}
+
+export class Mesh extends Node {
+  private _geometry?: Geometry
+
+  constructor(geometry?: Geometry, material?: Material) {
+    super()
+    if (geometry) {
+      const mat = material ?? Material.unlit()
+      this._geometry = geometry
+      this._materials = [ mat ]
+      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
+    }
+  }
+
+  override get geometry(): Geometry | undefined { return this._geometry }
+  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
+   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
+  setGeometry(geometry: Geometry): this {
+    this._geometry = geometry
+    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
+    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
+    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
+    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
+    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
+    if (this._culling !== undefined) this.culling = this._culling
+    if (this._castShadows !== undefined) this.castShadows = this._castShadows
+    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
+    return this
+  }
+  private _renderPriority?: number
+  private _culling?: boolean
+  private _castShadows?: boolean
+  private _receiveShadows?: boolean
+
+  /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
+  override get material(): Material { return this._materials![0]! }
+  override set material(m: Material) { this.setMaterial(m, 0) }
+
+  set culling(v: boolean) { this._culling = v; _creator.setCulling(this.id, v) }
+  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
+   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
+   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
+   *  after it can cover it. Write-only; a host that predates the call ignores it. */
+  set renderPriority(v: number) {
+    this._renderPriority = v
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
+  }
+  private static _warnedPriority = false
+  set castShadows(v: boolean) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
+
+  // --- factories ---
+
+  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
+    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
+    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
+  }
+
+  static sphere(options: MeshOptions & SphereOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.sphere(options), options.material), options)
+  }
+
+  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
+  }
+
+  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
+  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.capsule(options), options.material), options)
+  }
+
+  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.plane(options), options.material), options)
+  }
+
+  /** Wrap a custom Geometry. */
+  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
+    return apply(new Mesh(geometry, options.material), options)
+  }
+}
+
+const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
+
+const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
+  if (o.position) mesh.position = o.position
+  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
+  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
+  if (o.name !== undefined) mesh.name = o.name
+  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
+  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
+  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
+  return mesh
+}

package/src/gl/Node.ts

@@ -68,10 +68,6 @@ export const nodeOf = (id: number): Node => {
 export type NodeEvents = {
   click: (ev: ClickEvent<Node | null>) => void
   touchstart: (ev: TouchStartEvent<Node | null>) => void
-  /** AR anchors only (`scene.root` / `scene.createAnchor()`): the anchor began tracking. */
-  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. */
@@ -106,10 +102,6 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** Native entity id. */
   get id(): number { return this._h.id }
 
-  /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
-   *  'track' / 'untrack' events; `false` for any non-anchor node. */
-  isTracked = false
-
   private _matrix?: Float32Array
   private _worldMatrix?: Float32Array
   private _boneCache?: Map<string, Node | null>

package/src/gl/Scene.ts

@@ -1,23 +1,22 @@
 // A 3D scene: a draw set, a Camera, lights and environment. Opening a scene asks the host to bring up
 // the 3D engine; only the active scene renders. Grown from the Phase 0 seed. Ported from
-// worker/src/Scene.ts (Scene + ARScene), with the camera exposed as scene.camera.
+// worker/src/Scene.ts, with the camera exposed as scene.camera. AR is the "ar" plugin's ARScene (a
+// Scene whose camera and background its session drives — docs/plans/ar-plugin-plan.md); VRScene is here.
 //
 // Lights are explicit: a scene gets image-based ambient (IBL) by default; add a Light.sun() for
 // direct light + shadows.
 
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem, _detachAllSystems, type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect"
-import { _bumpNavEpoch, _navEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
+import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
 import { _surfaceWidgets, type LayerElement, type WidgetSet } from "../ui/UILayer"
 import { device } from "../runtime/device"
+import { File } from "../runtime/fetch"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
-import type { FetchResponse } from "../runtime/fetch"
-import { _requestCameraPermission } from "../plugins/permission"
 import { Camera } from "./Camera"
 import { SceneAudio } from "./audio/SceneAudio"
-import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
 import { PostProcessing, type PostProcessingOptions } from "./postProcessing"
 import { Texture } from "./Texture"
@@ -409,6 +408,16 @@ export class Scene implements Presentable {
     return new Promise<void>((res) => _creator.warmRender(this._id, res))
   }
 
+  /** The scene's picture as a PNG `File`: the composite of its next frame — the scene, its overlays
+   *  and its background (an AR scene's camera image), not the UI over them — encoded by the host
+   *  (a share, an upload, a `UIImage` source). Rejects when the scene is not the one on screen, or
+   *  something else is shown before the frame. */
+  capture(): Promise<File> {
+    return new Promise<File>((res, rej) => _creator.captureImage(this._id,
+      (bufferId, name, size) => res(new File(bufferId, name, size)),
+      () => rej(new Error("Scene.capture(): the scene is not the one on screen"))))
+  }
+
   /** Precompile the scene's shader variants so nothing is compiled mid-game. Every material the host
    *  knows is queued for the sun / shadow / fog / skinning variants and the dynamic-light key — the
    *  first point light (a muzzle flash, an explosion) would otherwise rebuild every lit shader in view
@@ -516,82 +525,6 @@ export class Scene implements Presentable {
   }
 }
 
-// --- AR ---
-
-export type ARMode = "default" | "markers" | "arcore" | "detached"
-
-const onTrackStateChange = (entityId: number, track: boolean): void => {
-  const node = nodes.get(entityId)
-  if (!node) return
-  node.isTracked = track
-  if (track) node._dispatchEvent("track")
-  else node._dispatchEvent("untrack")
-}
-
-export class ARScene<T extends ARMode = "default"> extends Scene {
-  readonly mode: T
-  useWarmRender = true
-  private _root?: Node
-
-  constructor(options: SceneOptions & { mode?: T } = {}) {
-    super(options)
-    this.mode = options.mode ?? ("default" as T)
-    _creator.createARController(this._id, this.camera.id, this.mode, onTrackStateChange)
-  }
-
-  /** Root anchor node (not available in marker mode). */
-  get root(): Node {
-    if (this._root) return this._root
-    this._root = new Node(_creator.createRootAnchor(this._id))
-    return this._root
-  }
-
-  /** Create an anchor from a tracking source (e.g. an image target). */
-  createAnchor(source: FetchResponse, physicalWidth = 0.2): Node {
-    return new Node(_creator.createAnchor(this._id, physicalWidth, (source as any)._h.id))
-  }
-
-  /**
-   * Let the user place & manipulate a node with touch gestures — the staple AR object-placement
-   * interaction: ONE finger drags it across the floor (relative to where the camera looks), TWO fingers
-   * pinch to scale and twist to rotate. Returns a handle; call `.remove()` to detach. Tunable via
-   * options (min/max scale, and toggles for `pan` / `pinch` / `twist`).
-   */
-  addControls(target: Node, options: ControlsOptions = {}): ControlsHandle {
-    return attachControls(this, target, options)
-  }
-
-  override async open(options?: PresentOptions): Promise<void> {
-    await this._prepare()
-    super.open(options)
-  }
-
-  /** @internal Presentable prepare hook: camera permission + warm render + AR session, all while
-   *  the previous destination (typically a loading screen) stays visible — the swap to this scene
-   *  happens only after it resolves. Warm render is headless on every platform (offscreen
-   *  swapchain), so no GL view is created here — the host mounts the scene view at present time.
-   *  Rejects on camera denial / AR launch failure, or if another navigation happened while
-   *  preparing (superseded) — in every rejection case the current destination stays visible. */
-  async _prepare(): Promise<void> {
-    const epoch = _navEpoch()
-    await _requestCameraPermission()
-    if (this.useWarmRender) await this.warmRender()
-    await new Promise<void>((res, rej) => _creator.launchAR(this._id, res, rej))
-    if (_navEpoch() !== epoch) {
-      _creator.stopAR()
-      throw new Error("ARScene.open() superseded: another destination was opened while preparing")
-    }
-  }
-
-  override close(options?: DismissOptions): void {
-    // The session is this scene's unless another ARScene is on screen now: a late close of a scene
-    // something already replaced must not stop the next one's session.
-    const current = Presentable.current
-    if (!(current instanceof ARScene) || current === this) _creator.stopAR()
-    super.close(options)
-  }
-}
-
 // --- VR ---
 
 /**