lecodes-sdk 1.2.0 → 2.0.1

package/src/gl/Scene.ts

@@ -7,7 +7,9 @@
 
 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, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
+import { _bumpNavEpoch, _navEpoch, _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 { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
@@ -17,7 +19,7 @@ import { SceneAudio } from "./audio/SceneAudio"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
 import { Texture } from "./Texture"
-import { Node, nodeRegistry } from "./Node"
+import { Node, nodes } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 
@@ -32,6 +34,21 @@ export type AmbientOcclusionOptions = {
   quality?: "low" | "medium" | "high" | "ultra"
 }
 
+/** `SceneOptions.taa` / `scene.setAntialias("taa", 4, taa)`: the temporal anti-aliasing knobs. */
+export type TaaOptions = {
+  /** Render the 3D at this fraction (0.5–1) and TAA-upscale it to the viewport; 1 = none. */
+  upscale?: number
+  /** The history's share, 0 (max smoothing) … 1 (none); 0.12 default. */
+  feedback?: number
+  /** Post-TAA sharpen 0–1; defaults to 0.5 with `upscale` below 1, else 0. */
+  sharpness?: number
+  /** A first-person viewmodel: everything closer than this many metres to the camera is treated as
+   *  fixed on screen — its history is read at the same pixel, not reprojected by the camera's motion,
+   *  which would trail the weapon on every turn (TAA has no per-object motion vectors). 1 covers arms
+   *  and weapon at eye height; 0 (the default) = off. A wall walked into within the band smears a little. */
+  viewmodel?: number
+}
+
 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
@@ -105,10 +122,18 @@ export type SceneOptions = {
    *  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. */
-  antialias?: boolean | 2 | 4
+  /** Anti-aliasing: `true` = 4× MSAA, `2`/`4` = that many samples, `false` = off (FXAA takes over),
+   *  `"taa"` = temporal anti-aliasing (Filament's TAA: one full-screen history blend instead of the
+   *  multisampled buffers — cheaper than MSAA on an integrated GPU and it also calms specular and
+   *  foliage shimmer; see `taa` for its knobs). Unset keeps the host default (desktop 4×, mobile/web
+   *  off). The biggest single fill-rate cost after resolution — turn it down on big screens first. */
+  antialias?: boolean | 2 | 4 | "taa"
+  /** The TAA's knobs (`antialias: "taa"`): `upscale` = render the 3D at this fraction (0.5–1) and let
+   *  TAA reconstruct the full resolution — the cheap way to a lower render cost with most of the
+   *  detail kept (`renderScale` shrinks the buffer and stretches it instead); `feedback` = the
+   *  history's share, 0.12 by default (raise it toward 0.3 if fast motion ghosts); `sharpness` =
+   *  a post-TAA sharpen 0–1, useful with `upscale`. */
+  taa?: TaaOptions
   /** Keep a stencil buffer for this scene (off by default: it costs memory and a clear per frame).
    *  Needed before any material's `stencil` test or write does anything. */
   stencil?: boolean
@@ -214,7 +239,7 @@ export class Scene implements Presentable {
       // `asset()` hands back "id:<n>" (already staged); a bare name is resolved on the spot; -1 is
       // "no probe named", which leaves the host on the project-wide `ibl.ktx` (the old behaviour).
       const src = typeof options.ibl === "string" ? options.ibl : undefined
-      const iblId = src === undefined ? -1 : src.startsWith("id:") ? Number(src.slice(3)) : _creatorUtils.fetchLocal(src)
+      const iblId = src === undefined ? -1 : src.startsWith("id:") ? Number(src.slice(3)) : _creatorFetch.local(src)
       _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000, iblId)
     }
     this._environmentIntensity = options.ibl === false ? 0 : (options.environmentIntensity ?? 20000)
@@ -229,7 +254,7 @@ export class Scene implements Presentable {
     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)
+      this.setAntialias(a, 4, options.taa)
     }
     if (options.stencil !== undefined) this.setStencil(options.stencil)
     // Before anything else in this constructor that could load a texture: the value has to be in
@@ -252,9 +277,15 @@ export class Scene implements Presentable {
     _creator.setSceneRenderOptions?.(this._id, renderScale, !!dynamicResolution, min)
   }
 
-  /** Scene occlusion material. */
+  /** Scene occlusion material: an unlit instance in the occluder blue (the built-in `unlit`, which
+   *  every runtime carries) — one per scene, made on first use. */
   get occlusionMaterial(): Material {
-    if (!this._material) this._material = new Material(_creator.getSceneMaterial(this._id))
+    if (!this._material) {
+      const h = _creator.builtinMaterial("unlit")
+      if (!h) throw new Error("Scene.occlusionMaterial: this host carries no unlit material")
+      this._material = new Material(h)
+      this._material.uniforms.baseColor = [0.1, 0.25, 0.57, 1.0]
+    }
     return this._material
   }
 
@@ -263,7 +294,7 @@ export class Scene implements Presentable {
     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)
+      const id = src.startsWith("id:") ? Number(src.slice(3)) : _creatorFetch.local(src)
       _creator.setSkyboxTexture?.(this._id, id)
       return
     }
@@ -290,8 +321,19 @@ export class Scene implements Presentable {
   setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void {
     _creator.setMaterialGlobalParameter(this._id, i, x, y, z, w)
   }
-  setAntialias(enabled: boolean, scale = 4): void {
-    _creator.setSceneMultiSampleAntiAliasing(this._id, enabled, scale)
+  setAntialias(mode: boolean | 2 | 4 | "taa", scale = 4, taa?: TaaOptions): void {
+    if (mode === "taa") {
+      if (!_creator.setTemporalAntiAliasing) {   // an older host: the nearest thing it has
+        _creator.setSceneMultiSampleAntiAliasing(this._id, true, scale)
+        return
+      }
+      const up = taa?.upscale ?? 1
+      _creator.setTemporalAntiAliasing(this._id, true, taa?.feedback ?? 0.12, taa?.sharpness ?? (up < 1 ? 0.5 : 0), up < 0.5 ? 0.5 : up > 1 ? 1 : up, taa?.viewmodel ?? 0)
+      return
+    }
+    // `false` must reach the host: desktop defaults to 4× MSAA, so an explicit off is a real change.
+    _creator.setTemporalAntiAliasing?.(this._id, false, 0.12, 0, 1, 0)
+    _creator.setSceneMultiSampleAntiAliasing(this._id, mode !== false, typeof mode === "number" ? mode : scale)
   }
   /** Depth-reading effects on / off (a graphics-settings menu): soft particles and projected decals
    *  read the scene depth, which costs a depth pre-pass of every opaque draw (~12 % of a fill-bound
@@ -336,12 +378,15 @@ export class Scene implements Presentable {
     else if (enabled) console.warn("[scene] this host has no setSceneStencil — stencil ignored")
   }
 
-  add(...nodes: Node[]): this {
-    for (const n of nodes) _creator.addEntityToScene(this._id, n.id)
+  add(...list: Node[]): this {
+    for (const n of list) { _creator.addEntityToScene(this._id, n.id); nodes.pin(n) }   // the scene owns it now
     return this
   }
-  remove(...nodes: Node[]): this {
-    for (const n of nodes) _creator.removeEntityFromScene(this._id, n.id)
+  remove(...list: Node[]): this {
+    for (const n of list) {
+      _creator.removeEntityFromScene(this._id, n.id)
+      if (!_creator.entityIsOwned(n.id)) nodes.unpin(n.id)   // loose again: its handle owns it
+    }
     return this
   }
 
@@ -422,39 +467,47 @@ export class Scene implements Presentable {
     this.cl.push(callback)
     return this
   }
-  onBackPressed(callback: () => void): this {
+  /** Hardware/system back while the scene is current. */
+  onBack(callback: () => void): this {
     this._backButtonCallback = callback
     return this
   }
-
-  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
-  _viewDesc(): object {
-    return this._vd ??= { type: "scene3d", sceneId: this._id, _p: this }
+  /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+   *  rename; removed with the release that recompiles them. */
+  onBackPressed(callback: () => void): this { return this.onBack(callback) }
+
+  /** @internal The destination tuple (ui/presentable.ts). */
+  _dest(): DestTuple {
+    // Addressed by the router / an attached widget: make sure the (kind, id) resolves back to us.
+    registerDest(TREE_DEST_SCENE3D, this._id, this)
+    return [TREE_DEST_SCENE3D, this._id, "", ""]
+  }
+  /** @internal presentation lifecycle from the runtime */
+  _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
+  /** @internal */
+  _emitClose(): void { for (const cb of this.cl.slice()) cb() }
+  /** @internal */
+  _emitBack(): boolean {
+    if (!this._backButtonCallback) return false
+    this._backButtonCallback()
+    return true
   }
 
   /** Make this the active scene — shows it as the current destination (replaces a screen /
-   *  another scene; only the active scene renders). */
+   *  another scene; only the active scene renders). The runtime activates the engine as part of
+   *  presenting the destination. */
   open(options?: PresentOptions): void | Promise<void> {
     _bumpNavEpoch()
-    if (_navSupported()) {
-      // The host activates the engine (openScene) as part of presenting the destination.
-      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
-    } else {
-      _creator.openScene(this._id)
-      for (const cb of this.ol) cb()
-    }
+    ensureEmitter()
+    registerDest(TREE_DEST_SCENE3D, this._id, this)
+    _creatorTree.open(TREE_DEST_SCENE3D, this._id, "", "", _transitionId(options?.transition, TRANSITION_NONE))
     Scene._active = this
     glState.activeScene = this
     _setCurrent(this)
   }
-  close(): void {
+  close(options?: DismissOptions): void {
     _bumpNavEpoch()
-    if (_navSupported()) {
-      _creatorUI.closeView!()
-    } else {
-      _creator.closeScene()
-      for (const cb of this.cl) cb()
-    }
+    _creatorTree.close(TREE_DEST_SCENE3D, this._id, _transitionId(options?.transition, TRANSITION_NONE))
     if (Scene._active === this) Scene._active = null
     if (glState.activeScene === this) glState.activeScene = null
     if (Presentable.current === this) _setCurrent(null)
@@ -481,7 +534,7 @@ export class Scene implements Presentable {
 export type ARMode = "default" | "markers" | "arcore" | "detached"
 
 const onTrackStateChange = (entityId: number, track: boolean): void => {
-  const node = nodeRegistry.get(entityId)
+  const node = nodes.get(entityId)
   if (!node) return
   node.isTracked = track
   if (track) node._dispatchEvent("track")
@@ -508,7 +561,7 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
 
   /** 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)._id))
+    return new Node(_creator.createAnchor(this._id, physicalWidth, (source as any)._h.id))
   }
 
   /**
@@ -543,9 +596,12 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
     }
   }
 
-  override close(): void {
-    _creator.stopAR()
-    super.close()
+  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)
   }
 }
 
@@ -565,8 +621,8 @@ export class VRScene extends Scene {
     super.open(options)
   }
 
-  override close(): void {
+  override close(options?: DismissOptions): void {
     _creator.stopVR()
-    super.close()
+    super.close(options)
   }
 }

package/src/gl/Texture.ts

@@ -37,8 +37,9 @@ export class Texture {
     Texture._maxSize = size > 0 ? Math.floor(size) : 0
     _creator.setTextureMaxSize?.(Texture._maxSize)
   }
-  /** @internal native texture handle. */
-  readonly _id: number
+  /** @internal The texture's owned handle (`_h.id` = the engine id). A texture the engine or another
+   *  object owns (a canvas's, a video player's) is wrapped from its number and never freed by us. */
+  readonly _h: Handle
   readonly width: number
   readonly height: number
 
@@ -47,10 +48,10 @@ export class Texture {
   /** Vertical wrap mode (V). */
   wrapT = 1
 
-  constructor(width: number, height: number, id: number) {
+  constructor(width: number, height: number, id: Handle | number) {
     this.width = width
     this.height = height
-    this._id = id
+    this._h = typeof id === "number" ? { id } : id
   }
 
   // Wrap a Canvas's baked surface as a 3D texture (RGBA8, already rasterized → synchronous, no decode).
@@ -72,13 +73,13 @@ export class Texture {
     const channels = opts.channels ?? 4
     if (data.length < width * height * channels) throw new Error(`Texture.fromPixels: ${data.length} bytes for ${width}×${height}×${channels}`)
     const id = _creator.createTexturePixels(width, height, channels, data, opts.srgb ?? true)
-    if (id === 0xFFFFFFFF) throw new Error("Texture.fromPixels: the host refused the texture")
+    if (id.id === 0xFFFFFFFF) throw new Error("Texture.fromPixels: the host refused the texture")
     return new Texture(width, height, id)
   }
 
   /** Re-upload a rectangle of a `fromPixels` texture (same channel count). */
   update(x: number, y: number, width: number, height: number, data: Uint8Array): void {
-    _creator.updateTexturePixels?.(this._id, x, y, width, height, data)
+    _creator.updateTexturePixels?.(this._h.id, x, y, width, height, data)
   }
 
   /** Decode an image (PNG / JPG, or a KTX2 the core transcodes) into a texture. `srgb` (default
@@ -97,7 +98,7 @@ export class Texture {
     }
     const flags = (options.srgb === false ? TEXTURE_FLAG_LINEAR : 0) | (options.fullSize ? TEXTURE_FLAG_FULL_SIZE : 0)
     return new Promise<Texture>((resolve, reject) => {
-      _creator.createTexture((source as any)._id, (id, w, h) => resolve(new Texture(w, h, id)), reject, flags)
+      _creator.createTexture((source as any)._h.id, (id, w, h) => resolve(new Texture(w, h, id)), reject, flags)
     })
   }
 }

package/src/gl/animation/AnimationClip.ts

@@ -270,7 +270,7 @@ export class AnimationClip {
       })
     }
     return new Promise<[number, ClipInfo[]]>((resolve, reject) => {
-      _creator.loadClips((source as unknown as { _id: number })._id, (setId: number) => {
+      _creator.loadClips((source as unknown as { _h: Handle })._h.id, (setId: number) => {
         if (setId === 0) { reject(new Error("AnimationClip.load: the file has no animations (or is not a GLB)")); return }
         resolve([setId, readInfo(setId)])
       }, reject)