lecodes-sdk 0.20.2 → 1.1.0

package/src/gl/Model.ts

@@ -1,124 +1,167 @@
-// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
-// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
-// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
-//   const hero = await Model.load(asset('./hero.glb'))
-//   hero.anim.play('Run', { loop: true })
-
-import { fetch, type FetchResponse } from "../runtime/fetch"
-import { Node } from "./Node"
-import { Animator, _pushLod, type LodMode } from "./animation/Animator"
-import { Material } from "./Material"
-
-export class Model extends Node {
-  /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
-   *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
-  declare readonly anim: Animator
-  /** @internal loaded through the lightmap material (docs/lightmap-plan.md); clones inherit it. */
-  _lightmapped = false
-  /** @internal what `load` does without an explicit `lightmap` option: `'dynamic'` while a scene file with
-   *  `env.lightmap.volume` runs (Lightmap sets it), so weapons, spawns and make() subtrees read the volume. */
-  static _lightmapDefault: false | "dynamic" = false
-  /** @internal the shadow pair, mirrored here because the bridge writes both at once. */
-  _castShadows = true
-  /** @internal */
-  _receiveShadows = true
-  /** @internal */
-  _culling = true
-  /** @internal -1 = auto (see `lod`) */
-  _lodMesh = -1
-
-  constructor(internalId: number) {
-    super(internalId)
-    this.aspect(Animator)
-  }
-
-  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
-   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
-   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
-   *  is never wanted. */
-  get castShadows(): boolean { return this._castShadows }
-  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
-
-  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
-  get receiveShadows(): boolean { return this._receiveShadows }
-  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
-
-  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
-   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
-   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
-   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
-   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
-   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
-  get culling(): boolean { return this._culling }
-  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
-  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
-   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
-   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
-   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
-   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
-  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
-  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
-
-  /** @internal the default for a fresh instance (load / clone), decided once per host. */
-  static _cullingDefault(): boolean {
-    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
-    return Model._cullDefault
-  }
-  private static _cullDefault: boolean | undefined
-
-  /** @internal both flags travel together — the bridge walks the instance once. */
-  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
-
-  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
-   *  the same parent and scene and sharing this model's current transform. The clone has its own
-   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
-  clone(): Model {
-    const id = _creator.cloneEntity(this.id)
-    const m = new Model(id)
-    m._lightmapped = this._lightmapped
-    if (!this._culling) { m._culling = false; _creator.setGlbCulling(id, false) }   // the engine default is on
-    if (this._lodMesh >= 0) { m._lodMesh = this._lodMesh; _pushLod(m) }
-    // the clone is a FRESH gltfio instance — it comes back with the asset's own shadow flags,
-    // not this model's, so a cleared flag has to be re-applied
-    m._castShadows = this._castShadows
-    m._receiveShadows = this._receiveShadows
-    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
-    return m
-  }
-
-  /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
-  static load(
-    source: string | FetchResponse,
-    options: {
-      /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
-      culling?: boolean
-      onProgress?: (p: { loaded: number, total?: number }) => void
-      /** Baked lighting (docs/lightmap-plan.md). `true` = a STATIC: loads through the lightmap material so
-       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
-       *  --lightmap-uv`). `'dynamic'` = a mover: the same material, lit by the level's light VOLUME instead
-       *  (no UV1 needed). Omitted: `'dynamic'` while a scene file with `env.lightmap.volume` is running,
-       *  else off. `false` = the standard shader. Hosts without lightmap support ignore it. */
-      lightmap?: boolean | "dynamic"
-    } = {},
-  ): Promise<Model> {
-    if (typeof source === "string") {
-      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
-        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
-        return Model.load(resp, options)
-      })
-    }
-    return new Promise<Model>((resolve, reject) => {
-      const mode = options.lightmap ?? Model._lightmapDefault
-      const lightmapped = !!mode && !!_creator.setNextGlbLightmapped
-      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()))
-      _creator.createGlb((source as unknown as { _id: number })._id, (entityId: number) => {
-        if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
-        const model = new Model(entityId)
-        model._lightmapped = lightmapped
-        const culling = options.culling ?? Model._cullingDefault()
-        if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
-        resolve(model)
-      }, reject)
-    })
-  }
-}
+// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
+// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
+// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.play('Run', { loop: true })
+
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Node } from "./Node"
+import { Animator, _pushLod, type LodMode } from "./animation/Animator"
+import { Material } from "./Material"
+
+/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
+ *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
+ *  `world` its skinned position this frame. */
+export interface TrianglePick {
+  /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
+  entity: number
+  node: number
+  nodeName: string
+  mesh: string
+  primitive: number
+  material: string
+  /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
+  triangle: number
+  backface: boolean
+  distance: number
+  point: [number, number, number]
+  bary: [number, number, number]
+  skin: string
+  vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
+}
+
+export class Model extends Node {
+  /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
+   *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
+  declare readonly anim: Animator
+  /** @internal loaded through the lightmap material (a baked static); clones inherit it. */
+  _lightmapped = false
+  /** @internal loaded through the foliage tier (`Foliage`); clones inherit it. */
+  _foliage = false
+  /** @internal the shadow pair, mirrored here because the bridge writes both at once. */
+  _castShadows = true
+  /** @internal */
+  _receiveShadows = true
+  /** @internal */
+  _culling = true
+  /** @internal -1 = auto (see `lod`) */
+  _lodMesh = -1
+
+  constructor(internalId: number) {
+    super(internalId)
+    this.aspect(Animator)
+  }
+
+  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
+   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
+   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
+   *  is never wanted. */
+  get castShadows(): boolean { return this._castShadows }
+  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
+
+  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
+  get receiveShadows(): boolean { return this._receiveShadows }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
+
+  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
+   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
+   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
+   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
+   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
+   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
+  get culling(): boolean { return this._culling }
+  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
+  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
+   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
+   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
+   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
+   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
+  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
+  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
+
+  /** @internal the default for a fresh instance (load / clone), decided once per host. */
+  static _cullingDefault(): boolean {
+    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
+    return Model._cullDefault
+  }
+  private static _cullDefault: boolean | undefined
+
+  /** @internal both flags travel together — the bridge walks the instance once. */
+  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
+
+  /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
+   *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
+   *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
+   *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
+   *  only. null = miss, or a host without the pick (desktop today). */
+  pickTriangle(screenX: number, screenY: number): TrianglePick | null {
+    const json = _creator.pickTriangle?.(this.id, screenX, screenY)
+    return json ? JSON.parse(json) as TrianglePick : null
+  }
+
+  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+   *  the same parent and scene and sharing this model's current transform. The clone has its own
+   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
+  clone(): Model {
+    const id = _creator.cloneEntity(this.id)
+    const m = new Model(id)
+    m._lightmapped = this._lightmapped
+    m._foliage = this._foliage
+    if (!this._culling) { m._culling = false; _creator.setGlbCulling(id, false) }   // the engine default is on
+    if (this._lodMesh >= 0) { m._lodMesh = this._lodMesh; _pushLod(m) }
+    // the clone is a FRESH gltfio instance — it comes back with the asset's own shadow flags,
+    // not this model's, so a cleared flag has to be re-applied
+    m._castShadows = this._castShadows
+    m._receiveShadows = this._receiveShadows
+    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
+    return m
+  }
+
+  /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
+  static load(
+    source: string | FetchResponse,
+    options: {
+      /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
+      culling?: boolean
+      onProgress?: (p: { loaded: number, total?: number }) => void
+      /** Baked lighting (packages/creator-bake). `true` = a STATIC: loads through the lightmap material so
+       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
+       *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
+       *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
+      lightmap?: boolean
+      /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,
+       *  per-copy tint. Hosts without the tier fall back to the standard shader. */
+      foliage?: boolean
+    } = {},
+  ): Promise<Model> {
+    if (typeof source === "string") {
+      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
+        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
+        return Model.load(resp, options)
+      })
+    }
+    return new Promise<Model>((resolve, reject) => {
+      // the provider path: a foliage model takes the vegetation tier's pair when the host ships it (fetchLocal
+      // id 0 = it does not), a static the lightmap material + its masked twin; anything else the ubershader
+      const foliageWanted = !!options.foliage && !!_creator.setNextGlbLightmapped
+      let foliage = false
+      if (foliageWanted) {
+        const fol = Material.idOf(Material._foliageTemplate())
+        const folMasked = fol ? Material.idOf(Material._foliageMaskedTemplate()) : 0
+        foliage = fol > 0 && folMasked > 0
+        if (foliage) _creator.setNextGlbLightmapped!(fol, folMasked)
+      }
+      const lightmapped = !foliage && !!options.lightmap && !!_creator.setNextGlbLightmapped
+      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()), Material.idOf(Material._lightmapMaskedTemplate()))
+      _creator.createGlb((source as unknown as { _id: number })._id, (entityId: number) => {
+        if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
+        const model = new Model(entityId)
+        model._lightmapped = lightmapped
+        model._foliage = foliage
+        const culling = options.culling ?? Model._cullingDefault()
+        if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
+        resolve(model)
+      }, reject)
+    })
+  }
+}

package/src/gl/Node.ts

@@ -12,10 +12,23 @@ import { Quat, cw, type QuatLike } from "../math/quat"
 import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
-import { ensurePhysicsEvents } from "./physicsEvents"
+import { ensurePhysicsEvents } from "./physics/physicsEvents"
 import { Material } from "./Material"
 import type { CompAxis, CompWriter } from "../core/compWrite"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+import type { Animation } from "../animate/tween/Animation"
+import { CLOCK_GAME, DOM_GL_NODE, eulerValue, quatValue, vec3Value, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import { tweenBag } from "../animate/tween/Timeline"
+
+/** Animatable transform props of a 3D node: a value tweens from the current one, an ARRAY OF
+ *  VALUES is a keyframe list (`position: [[0,0,0], [0,2,0]]`). */
+export type NodeTweenProps = {
+  position?: Vec3Like | Vec3Like[],
+  scale?: number | Vec3Like | (number | Vec3Like)[],
+  quaternion?: QuatLike | QuatLike[],
+  /** Degrees, YXZ; interpolated per axis without shortest-arc, so `[0, 720, 0]` spins twice. */
+  eulerAngles?: Vec3Like | Vec3Like[],
+}
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
 export const nodeRegistry = new Registry<Node>()
@@ -197,6 +210,32 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
     if (this._xf) this._setOwnedRotation()
   }
 
+  // --- keyframe animation (docs/timeline-plan.md) ---
+  /** Tween the transform to the given values — `node.animateTo({ position: [0, 2, 0], duration: 800,
+   *  easing: 'inOutCubic' })`; arrays of values are keyframes. Runs on the game clock (pauses with
+   *  the game) unless `clock: 'ui'`. Returns the {@link Animation} handle. Phase 1: plain nodes —
+   *  a physics-owned node (a body / character) is not routed through its engine object yet. */
+  animateTo(props: NodeTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, true)
+  }
+  /** Tween FROM the given values to the node's current transform (an entrance). */
+  animateFrom(props: NodeTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, false)
+  }
+  /** @internal keyframe-core target protocol */
+  readonly _tweenClock: number = CLOCK_GAME
+  /** @internal */
+  _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    switch (prop) {
+      case "position": return { domain: DOM_GL_NODE, id, value: vec3Value }
+      case "scale": return { domain: DOM_GL_NODE, id, value: vec3Value }
+      case "quaternion": return { domain: DOM_GL_NODE, id, value: quatValue }
+      case "eulerAngles": return { domain: DOM_GL_NODE, id, value: eulerValue }
+      default: return null
+    }
+  }
+
   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

package/src/gl/Particles.ts

@@ -40,6 +40,10 @@ const TAG_ANGULAR_VELOCITY = 17
 const TAG_GROUND = 18
 const TAG_VELOCITY_LIFE = 19
 const TAG_ORDER = 20
+const TAG_SMOOTH_PATH = 21
+const TAG_RIBBON_ORIENT = 22
+/** `TrailOptions.orient` → the native axis code (0 = the camera-facing default). */
+const RIBBON_AXIS: Record<"camera" | "x" | "y" | "z", number> = { camera: 0, x: 1, y: 2, z: 3 }
 
 /** @internal — exported for the tag-sync test only. */
 export const _particleTags = {
@@ -49,7 +53,7 @@ export const _particleTags = {
   SPACE: TAG_SPACE, INHERIT_VELOCITY: TAG_INHERIT_VELOCITY, RATE_DISTANCE: TAG_RATE_DISTANCE,
   RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
   ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
-  ORDER: TAG_ORDER,
+  ORDER: TAG_ORDER, SMOOTH_PATH: TAG_SMOOTH_PATH, RIBBON_ORIENT: TAG_RIBBON_ORIENT,
 }
 
 // --- curve builders -----------------------------------------------------------------------------
@@ -231,7 +235,15 @@ type Shape =
  *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
  *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
 export type VelocityOverLife = { radial?: ParticleValue, x?: ParticleValue, y?: ParticleValue, z?: ParticleValue }
-type Noise = { strength?: number, frequency?: number, speed?: number }
+type Noise = {
+  strength?: number, frequency?: number, speed?: number,
+  /** How much of the displacement a particle earns with AGE (default 0 = all of it from birth).
+   *  The field is sampled by position, so at 0 every particle born at the same spot is pushed the
+   *  same way and a plume's root wanders off its emitter by up to `strength` metres; at 1 a particle
+   *  is born exactly where the emitter put it and drifts into the field over its life — what you
+   *  want whenever the source is visible (an exhaust pipe, a contact patch, a muzzle). */
+  ramp?: number,
+}
 
 /** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
  *  world y with `space: 'world'`, emitter-local y otherwise. */
@@ -278,11 +290,25 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  spread evenly along the path — trail density independent of speed, no per-frame clumps.
    *  Meant for `space: 'world'`. */
   rateOverDistance?: number
+  /** Spread those spawn points along a CURVE through the emitter's recent path instead of the
+   *  straight line between where it was last frame and where it is now. A straight line cuts the
+   *  corner by however far the path bows inside one frame, which grows with the frame TIME — so a
+   *  fast curving emitter looks faceted, and looks worse the slower the machine. Default false
+   *  (the straight line); costs three stored positions and one curve evaluation per spawn.
+   *
+   *  The curve needs a point one frame AHEAD, so each frame's spawns are placed provisionally and
+   *  nudged into place on the next frame, once it exists. Nothing else observes them in between. */
+  smooth?: boolean
   /** Draw order among blended systems at the same depth — higher draws later, i.e. on top (Unity's
    *  sortingOrder). Systems are depth-sorted by their node, so the emitters of one effect tie and
    *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
    *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
   order?: number
+  /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
+   *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
+   *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
+   *  centre says nothing about where its cloud is). `order` breaks ties inside one priority. */
+  renderPriority?: number
   shape?: Shape
   /** Extra velocity over life (radial burst that decays, axis drift) — see `VelocityOverLife`. */
   velocityOverLife?: VelocityOverLife
@@ -437,6 +463,7 @@ export class Particles extends Node {
     super()
     this._material = options.material ?? (options.mesh ? Material.lit() : Material.particles(options))
     _creator.createParticleSystem(this.id, Material.idOf(this._material), options.maxParticles ?? 0)
+    this.renderPriority = options.renderPriority ?? 5
 
     const id = this.id
     this.custom = new Proxy([] as ParticleValue[], {
@@ -463,6 +490,7 @@ export class Particles extends Node {
     if (options.space !== undefined) out.push(TAG_SPACE, 1, options.space === "world" ? 1 : 0)
     if (options.inheritVelocity !== undefined) out.push(TAG_INHERIT_VELOCITY, 1, options.inheritVelocity)
     if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
+    if (options.smooth !== undefined) out.push(TAG_SMOOTH_PATH, 1, options.smooth ? 1 : 0)
     if (options.order !== undefined) out.push(TAG_ORDER, 1, options.order)
     if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
     if (options.shape !== undefined) pushShape(out, options.shape)
@@ -496,7 +524,7 @@ export class Particles extends Node {
     }
     if (options.noise !== undefined) {
       const n = options.noise
-      out.push(TAG_NOISE, 3, n ? n.strength ?? 1 : 0, n ? n.frequency ?? 1 : 0, n ? n.speed ?? 1 : 0)
+      out.push(TAG_NOISE, 4, n ? n.strength ?? 1 : 0, n ? n.frequency ?? 1 : 0, n ? n.speed ?? 1 : 0, n ? n.ramp ?? 0 : 0)
     }
     if (options.seed !== undefined) out.push(TAG_SEED, 1, options.seed)
 
@@ -516,7 +544,13 @@ export class Particles extends Node {
   set space(val: "local" | "world") { this._send([ TAG_SPACE, 1, val === "world" ? 1 : 0 ]) }
   set inheritVelocity(val: number) { this._send([ TAG_INHERIT_VELOCITY, 1, val ]) }
   set rateOverDistance(val: number) { this._send([ TAG_RATE_DISTANCE, 1, val ]) }
+  /** Lay a frame's spawns along a curve through the emitter's path, not the straight chord. */
+  set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
   set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }
+  /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
+  set renderPriority(v: number) {
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+  }
 
   set velocityOverLife(v: VelocityOverLife) {
     const out: number[] = []
@@ -585,7 +619,7 @@ export class Particles extends Node {
 
   set noise(noise: Noise | null) {
     this._send(noise
-      ? [ TAG_NOISE, 3, noise.strength ?? 1, noise.frequency ?? 1, noise.speed ?? 1 ]
+      ? [ TAG_NOISE, 4, noise.strength ?? 1, noise.frequency ?? 1, noise.speed ?? 1, noise.ramp ?? 0 ]
       : [ TAG_NOISE, 3, 0, 0, 0 ])
   }
 }
@@ -602,8 +636,28 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
   width?: ParticleValue
   /** Minimum emitter movement (world units) between recorded points. Default 0.05. */
   minDistance?: number
-  /** Point capacity (default 128). */
+  /** Point capacity (default 128). A spawn that does not fit is DROPPED, so a fast emitter at a
+   *  small `minDistance` wants headroom: a sword tip covers metres inside one `time` window. */
   maxPoints?: number
+  /** Follow a CURVE through the emitter's recent path instead of the straight line between frames.
+   *  A trail is where this shows most — the strip is the path — and it shows worse the lower the
+   *  frame rate, since a longer frame bows further off its own chord. Default false; see
+   *  `ParticlesOptions.smooth`. */
+  smooth?: boolean
+  /** Which way the strip's WIDTH points.
+   *
+   *  `'camera'` (default) rolls the strip about its own length to stay flat to the viewer — it can
+   *  never disappear, which is why it is the default, but it bears no relation to the thing that drew
+   *  it. An AXIS (`'x'`/`'y'`/`'z'`) uses that axis of the emitter's own transform, as it was when
+   *  each point was laid: on a node riding a sword's blade, `'z'` (the blade) makes the strip the
+   *  surface the blade actually swept, and `width` stops being a made-up number — it is the blade. */
+  orient?: "camera" | "x" | "y" | "z"
+  /** With `orient` on an axis: the floor under the strip's APPARENT width, 0..1 of its real width,
+   *  below which it rolls back toward the camera. An honestly oriented strip goes edge-on — and
+   *  vanishes — whenever the swing happens in the plane of view; this is the hybrid that keeps it
+   *  readable. 0 = never roll (honest, and it will vanish), 1 = always (the same as `'camera'`).
+   *  Default 0.4: a sweep still reads as a sweep, and a swing toward the camera still shows. */
+  faceCamera?: number
   color?: ParticleColor
   /** Opacity along the trail. Defaults to fading the tail out (`curve().to(0)`). */
   opacity?: ParticleValue
@@ -617,6 +671,8 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
 export class Trail extends Node {
   private _material: Material
   private _rateDistance: number
+  private _orient = 0
+  private _faceCamera = 0.4
 
   constructor(options: TrailOptions = {}) {
     super()
@@ -632,6 +688,12 @@ export class Trail extends Node {
       TAG_RATE_DISTANCE, 1, this._rateDistance,
       TAG_LIFETIME, 2, time, time,
     ]
+    if (options.smooth) out.push(TAG_SMOOTH_PATH, 1, 1)
+    if (options.orient !== undefined || options.faceCamera !== undefined) {
+      this._orient = RIBBON_AXIS[options.orient ?? "camera"]
+      if (options.faceCamera !== undefined) this._faceCamera = options.faceCamera
+      out.push(TAG_RIBBON_ORIENT, 2, this._orient, this._faceCamera)
+    }
     pushParam(out, 0, options.width ?? 0.1)
     pushParam(out, 2, options.opacity ?? curve().to(0))
     if (options.color !== undefined) pushColor(out, options.color)
@@ -668,6 +730,21 @@ export class Trail extends Node {
     this._send([ TAG_RATE_DISTANCE, 1, this._rateDistance ])
   }
 
+  /** Follow a curve through the emitter's path instead of the straight chord between frames. */
+  set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
+
+  /** Which way the strip's width points — see `TrailOptions.orient`. Keeps the current `faceCamera`. */
+  set orient(val: "camera" | "x" | "y" | "z") {
+    this._orient = RIBBON_AXIS[val]
+    this._send([ TAG_RIBBON_ORIENT, 2, this._orient, this._faceCamera ])
+  }
+
+  /** The hybrid's floor — see `TrailOptions.faceCamera`. */
+  set faceCamera(val: number) {
+    this._faceCamera = val
+    this._send([ TAG_RIBBON_ORIENT, 2, this._orient, val ])
+  }
+
   /** Pause/resume laying down points — existing ones still age out, so the trail fades naturally
    *  after e.g. a sword swing ends. */
   set emitting(val: boolean) { this._send([ TAG_RATE_DISTANCE, 1, val ? this._rateDistance : 0 ]) }

package/src/gl/Scene.ts

@@ -13,7 +13,7 @@ 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 "./SceneAudio"
+import { SceneAudio } from "./audio/SceneAudio"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
 import { Texture } from "./Texture"
@@ -177,7 +177,8 @@ const installRenderSyncedFrames = (): void => {
 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). */
+  /** @internal what `environmentIntensity` currently asks for — the accessor's backing field, so it
+   *  answers on hosts whose engine has no live setter too. */
   _environmentIntensity = 20000
   readonly camera: Camera
   /** The listener + global 3D audio knobs (docs/audio-plan.md). */
@@ -309,6 +310,26 @@ export class Scene implements Presentable {
   setBloom(enabled: boolean, intensity = 0.2): void {
     _creator.setBloomOptions(this._id, enabled, intensity, 1)
   }
+  /**
+   * How bright the environment (IBL) lights the scene, in lux — `SceneOptions.environmentIntensity`
+   * after the fact. Live: it changes the probe's intensity, not the probe, so it costs nothing and
+   * can be dragged. (`setDefaultIbl`, the call that installs a probe, rebuilds the cubemap from the
+   * ktx every time — never drive a slider through a scene option that has to re-open.)
+   *
+   * `lecodes lightmap bake` reads the same number off the live probe, so a scene dimmed here bakes
+   * dimmed. Hosts without the call keep whatever the scene opened with, and the getter still
+   * reports what was asked for.
+   */
+  get environmentIntensity(): number { return this._environmentIntensity }
+  set environmentIntensity(lux: number) {
+    this._environmentIntensity = lux
+    if (_creator.setEnvironmentIntensity) _creator.setEnvironmentIntensity(this._id, lux)
+    else if (!Scene._warnedEnvIntensity) {
+      Scene._warnedEnvIntensity = true
+      console.warn("[scene] this host has no setEnvironmentIntensity — environmentIntensity stays as the scene opened")
+    }
+  }
+  private static _warnedEnvIntensity = false
   /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
   setStencil(enabled: boolean): void {
     if (_creator.setSceneStencil) _creator.setSceneStencil(this._id, enabled)
@@ -367,6 +388,18 @@ export class Scene implements Presentable {
     return new Promise<void>((res) => _creator.warmRender(this._id, res))
   }
 
+  /** 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
+   *  on that frame. Call it once the sun and fog are set, typically under a loading screen; materials
+   *  loaded later are queued in the background as they are created. Resolves at once on a host
+   *  without the bridge. */
+  precompileShaders(): Promise<void> {
+    const fn = _creator.precompileShaders
+    if (!fn) return Promise.resolve()
+    return new Promise<void>((res) => fn.call(_creator, this._id, res))
+  }
+
   // ---- Presentable (docs/navigation-presentable-plan.md) ----
   // A scene is a destination like a screen: opening it replaces whatever is visible (suspending
   // an active Router until Router.restore()), and it can be pushed onto the Router stack. The