lecodes-sdk 2.3.1 → 2.4.1

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.3.1",
+  "version": "2.4.1",
   "files": [
     "src",
     "dist",

package/src/audio/support.ts

@@ -1,6 +1,8 @@
 // Feature gate for the game audio system (docs/audio-plan.md). `_creatorAudio` is OPTIONAL as a
 // block: a host without it (or whose engine failed to open a device) makes every Sound silent and
-// every Voice inert — a project stays runnable, nothing throws.
+// every Voice inert — a project stays runnable, nothing throws. hasSupport() opens no device: the
+// native engine is created by the first call that needs it (a load, a bus write), so reading this
+// at load costs nothing; a host whose device then fails to open hands Sound.load the silent clip.
 
 export const audioSupported: boolean =
   typeof _creatorAudio !== "undefined" && !!_creatorAudio && typeof _creatorAudio.hasSupport === "function" && _creatorAudio.hasSupport()

package/src/bridges/audio.d.ts

@@ -13,27 +13,32 @@ declare global {
   // CREATOR_PKG_AUDIO (desktop first; Android / Apple pending — parity `audio-game`). The headless
   // renderer provides a RECORDER (plays are logged, nothing is mixed). Every parameter block is a
   // fixed-order Float32Array (creator-audio.h CAUD_SRC_* / the effect param orders).
+  // The engine (and the audio DEVICE) is created LAZILY, by the first call that needs it — the
+  // `@guard audioEnsureEngine` on every method that touches engine state (creator-pkg.h
+  // "creator-audio host integration"): an app that never makes a sound never opens the device.
+  // hasSupport() therefore opens nothing: it is "the bridge is here and no init has failed".
   /** @engine audio */
   var _creatorAudio: {
-    /** @guard audioEnsureEngine @c caudHasSupport */
+    /** True on a host with the bridge until an engine init has FAILED (no device at all). Opens
+     *  nothing: the engine is created by the first call that needs it. @custom */
     hasSupport(): boolean
     /** Decode the bytes behind a fetch system id (WAV / MP3 / OGG Vorbis) on the engine's
      *  loader thread; mono unless `stereo`. onDone(clipId, durationSeconds, channels). @custom */
     loadClip(systemId: bytes, stereo: boolean, onDone: (clipId: number, duration: number, channels: number) => void, onReject: (message: string) => void): void
     /** @c caudClipRelease */
     releaseClip(clipId: u32): void
-    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. @c caudBusId */
+    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. @guard audioEnsureEngine @c caudBusId */
     busId(name: string): i32
-    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. @c caudBusCreate */
+    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. @guard audioEnsureEngine @c caudBusCreate */
     createBus(name: string): i32
-    /** @c caudBusSetVolume */
+    /** @guard audioEnsureEngine @c caudBusSetVolume */
     setBusVolume(bus: i32, volume: f32): void
-    /** @c caudBusSetMuted */
+    /** @guard audioEnsureEngine @c caudBusSetMuted */
     setBusMuted(bus: i32, muted: boolean): void
     /** kind 1 reverb [roomSize, damping, width, mix, preDelay] · 2 echo [delay, decay, mix] ·
-     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. @c caudBusSetEffect */
+     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. @guard audioEnsureEngine @c caudBusSetEffect */
     setBusEffect(bus: i32, kind: i32, params: Float32Array): void
-    /** @c caudBusStopAll */
+    /** @guard audioEnsureEngine @c caudBusStopAll */
     stopBus(bus: i32, fade: f32): void
     /** A 3D emitter. `attachSource` binds it to an entity the engine follows every frame;
      *  `setSourcePosition` places an unbound one (playAt). @guard audioEnsureEngine @c caudSourceCreate */
@@ -41,11 +46,11 @@ declare global {
     /** @c gl:audioAttachSource */
     attachSource(sourceId: u32, entityId: u32): void
     /** [minDistance, maxDistance, rolloff (0 none 1 inverse 2 linear 3 exp), coneInnerDeg,
-     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. @c caudSourceSetParams */
+     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. @guard audioEnsureEngine @c caudSourceSetParams */
     setSourceParams(sourceId: u32, params: Float32Array): void
-    /** @c caudSourceSetPose @pack x 3 @rest nullptr */
+    /** @guard audioEnsureEngine @c caudSourceSetPose @pack x 3 @rest nullptr */
     setSourcePosition(sourceId: u32, x: f32, y: f32, z: f32): void
-    /** @c caudSourceStopAll */
+    /** @guard audioEnsureEngine @c caudSourceStopAll */
     stopSource(sourceId: u32, fade: f32): void
     /** @c caudSourceVoices */
     sourceVoices(sourceId: u32): i32
@@ -53,22 +58,22 @@ declare global {
     destroySource(sourceId: u32): void
     /** The listener entity; 0 = the active scene camera (the default). @c gl:audioSetListener */
     setListener(entityId: u32): void
-    /** @c caudListenerSetDoppler */
+    /** @guard audioEnsureEngine @c caudListenerSetDoppler */
     setListenerOptions(dopplerFactor: f32): void
     /** HRTF binaural rendering for the `maxVoices` nearest spatial voices (headphones); the rest keep panning. @guard audioEnsureEngine @c caudSetHrtf */
     setHrtf(enabled: boolean, maxVoices: i32): void
     /** Whether the engine's time scale (Time.scale) also pitches the sfx bus. Default false (pause = mute only). @guard audioEnsureEngine @c caudSetTimeScalePitch */
     setTimeScalePitch(enabled: boolean): void
     /** → a voice token (0 = nothing played: the pool refused, the clip is not ready). bus -1 = the
-     *  source's bus (sfx for 2D). pan is 2D only. @c caudPlay @pack bus CaudPlay */
+     *  source's bus (sfx for 2D). pan is 2D only. @guard audioEnsureEngine @c caudPlay @pack bus CaudPlay */
     play(clipId: u32, sourceId: u32, bus: i32, volume: f32, pitch: f32, loop: boolean, priority: i32, fadeIn: f32, startAt: f32, pan: f32): u32
-    /** @c caudVoiceSetVolume */
+    /** @guard audioEnsureEngine @c caudVoiceSetVolume */
     setVoiceVolume(token: u32, volume: f32): void
-    /** @c caudVoiceSetPitch */
+    /** @guard audioEnsureEngine @c caudVoiceSetPitch */
     setVoicePitch(token: u32, pitch: f32): void
-    /** @c caudVoiceSetPan */
+    /** @guard audioEnsureEngine @c caudVoiceSetPan */
     setVoicePan(token: u32, pan: f32): void
-    /** @c caudVoiceStop */
+    /** @guard audioEnsureEngine @c caudVoiceStop */
     stopVoice(token: u32, fade: f32): void
     /** @c caudVoicePlaying */
     voicePlaying(token: u32): boolean
@@ -77,7 +82,7 @@ declare global {
     /** THE ended listener (single slot per JS world): called once per tick with the tokens of the
      *  voices that ended since the previous tick — natural end, stop, steal. @custom */
     setOnEnded(callback: ((tokens: Float32Array) => void) | null): void
-    /** @c caudStopAll */
+    /** @guard audioEnsureEngine @c caudStopAll */
     stopAll(fade: f32): void
     /** A reverb volume: shape 0 box (dims = full size) / 1 sphere (dims[0] = diameter), in the
      *  entity's local units; `blend` metres of crossfade inside the border; reverb params as for
@@ -85,7 +90,7 @@ declare global {
     createZone(): u32
     /** @c gl:audioAttachZone */
     attachZone(zoneId: u32, entityId: u32): void
-    /** @c caudZoneSet */
+    /** @guard audioEnsureEngine @c caudZoneSet */
     setZone(zoneId: u32, shape: i32, dims: Float32Array, blend: f32, bus: i32, reverb: Float32Array): void
     /** @c gl:audioDetachZone, caudZoneDestroy */
     destroyZone(zoneId: u32): void

package/src/bridges/device.d.ts

@@ -38,6 +38,25 @@ declare global {
     /** Whether the overlay is on. */
     statsOverlay?(): boolean
 
+    // ---- The frame rate (device.setFrameRate / setVsync / displayRefreshRate) ---------------------
+    /** Cap the host's frame loop at `fps` frames a second (device.setFrameRate): the tick, and the
+     *  3D frame with it, runs at most that often. `0` = no cap: the display's own rate, or, with
+     *  vsync off, as fast as the host renders. A request, not a state — a phone asks its panel for
+     *  the rate and may be refused; the screen's own maximum still wins. Host state, kept through
+     *  `_creatorApp.run()`. Optional: a host whose loop has no pacing of its own (web, headless)
+     *  leaves it out. */
+    setFrameRate?(fps: f64): void
+    /** Present without waiting for the display's refresh (device.setVsync): off = no vsync wait,
+     *  tearing possible, and with no cap set the loop renders as fast as it can. Optional: desktop
+     *  only — a mobile compositor never presents outside the refresh, so the slot is absent there
+     *  and the SDK answers `false`. */
+    setVsync?(enabled: boolean): void
+    /** The display's refresh rate in Hz (device.displayRefreshRate): the fastest the screen offers
+     *  the app — 120 on a 120 Hz phone whatever mode the cap has put it in (an iPhone's 60 unless
+     *  the app's Info.plist lifts the floor), the monitor's current mode on desktop. Optional: 0
+     *  where the host cannot tell (web, Linux for now). */
+    displayRefreshRate?(): f64
+
     // ---- device.motion (orientation sensor; pull-per-frame model) --------------------------------
     /** Does this device have the motion sensors (gyro)? Surfaced as device.motion.available. */
     motionAvailable?(): boolean

package/src/bridges/gl.d.ts

@@ -286,6 +286,11 @@ declare global {
     setInstanceTransforms(entityId: u32, matrices: Float32Array, first: u32): void
     setInstancedMeshMaterial(entityId: u32, materialId: u32): void
     setInstancedMeshShadows(entityId: u32, cast: boolean, receive: boolean): void
+    /** GLB scatter (gl/Scatter.ts ↔ creator-gl/src/scatter.cpp): the loaded model `sourceId` drawn at `placements.length / 5`
+     *  placements (x y z, yaw in degrees, uniform scale) under `entityId`, hardware-instanced in cells of `cell` metres
+     *  with the source's own buffers and material instances. Returns the renderables made (0 = nothing scattered).
+     *  Absent on a host without it: Scatter then clones the model per placement. @count count=placements/5 */
+    createGlbScatter?(entityId: u32, sourceId: u32, placements: Float32Array, cell: f32, castShadows: boolean): u32
     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. */
@@ -780,6 +785,12 @@ declare global {
     /** Distance fade for every instance of the entity's ASSET (present and future): the cards thin out between `start`
      *  and `end` metres from the camera and past `end` the LOD pass takes the instance out of the scene. end 0 = none. */
     foliageSetFade?(entityId: u32, start: f32, end: f32): void
+    /** THE PLANTS' CASTER DISTANCE: a foliage instance casts the sun's shadow only within `distance` metres of the camera
+     *  (the LOD pass flips its renderables' castShadows); past it a baked ground keeps the shadow. 0 = every plant casts. */
+    foliageSetCast?(distance: f32): void
+    /** THE GROUND'S COLOUR UNDER THE PLANTS: the terrain's control map (RGBA = its four layers' weights) and each layer's
+     *  mean colour (12 floats, linear rgb x 4) — a grass blade's base takes the colour of the soil it stands in. Level-wide. */
+    foliageSetGroundTint?(terrainId: u32, controlTextureId: u32, colors: Float32Array): void
     /** @ifdef CREATOR_GL_PHYSICS */
     physicsConfigure(gx: f32, gy: f32, gz: f32, maxBodies: u32): void
     /** @c setPhysicsInterpolation @ifdef CREATOR_GL_PHYSICS */

package/src/compile/liteMaterial.ts

@@ -33,6 +33,10 @@ export type LiteMaterialArtifact = {
   /** Filament's shadow-catcher flag (unlit only, transparency mandatory — matc enforces both):
    *  the fragment shows baseColor scaled by the received shadow amount, transparent elsewhere. */
   shadowMultiplier: boolean
+  /** matc's `flipUV` (DEFAULT TRUE in Filament's MaterialBuilder): getUV0() / getUV1() return
+   *  `(u, 1 - v)` of the vertex attribute, the raw attribute only when the material says
+   *  `flipUV: false`. A .mat written against a native host counts on it; lite's getters follow. */
+  flipUV: boolean
   params: LiteMaterialParam[]
   /** sampler2d / samplerExternal parameters — all become sampler2D in lite */
   samplers: { name: string }[]
@@ -178,7 +182,7 @@ const SAMPLER_TYPES = new Set(["sampler2d", "samplerExternal"])
 const unsupported = (reason: string): LiteMaterialArtifact => ({
   lecodesLiteMaterial: 1, unsupported: reason,
   shadingModel: "unlit", blending: "opaque", maskThreshold: 0.4,
-  doubleSided: false, culling: "back", depthWrite: true, shadowMultiplier: false,
+  doubleSided: false, culling: "back", depthWrite: true, shadowMultiplier: false, flipUV: true,
   params: [], samplers: [], fragmentCode: "", writesNormal: false, hasVertexBlock: false,
 })
 
@@ -235,6 +239,7 @@ export const buildLiteMaterialArtifact = (text: string): LiteMaterialArtifact =>
       culling,
       depthWrite,
       shadowMultiplier: def.shadowMultiplier === true,
+      flipUV: def.flipUV !== false,
       params,
       samplers,
       fragmentCode,

package/src/gl/Foliage.ts

@@ -71,6 +71,11 @@ export type FoliageOptions = {
   /** Coverage held over distance: the cards' alpha × (1 + coverage × mip level), so a far crown does not thin out as its
    *  atlas mips away. Default 0.25, 0 = none; past ~0.5 a crown turns into a solid mass. */
   coverage?: number
+  /** THE PLANTS' CASTER DISTANCE, metres: a plant casts the sun's shadow only this close to the camera (the LOD pass takes
+   *  the farther ones out of the shadow map; 3 m of hysteresis). Meant for a level with a BAKED ground, which keeps the
+   *  far shadows while the shadow map holds a fraction of the casters (the Forest's Radeon frame: 6 ms of 39 at 25 m).
+   *  Default 0 = every plant casts. */
+  castDistance?: number
 }
 
 const DEFAULT_WIND: Required<FoliageWind> = { direction: [ 1, 0.3 ], speed: 8.3, turbulence: 0.4, gust: 0.35, gustSpeed: 5.6 }
@@ -88,6 +93,7 @@ const state: Required<Omit<FoliageOptions, "wind">> & { wind: Required<FoliageWi
   normalMap: 0.5,
   edgeFade: 0.15,
   coverage: 0.25,
+  castDistance: 0,
 }
 
 const pushWind = (): void => {
@@ -118,6 +124,7 @@ export const Foliage = {
     if (options.edgeFade !== undefined) { state.edgeFade = options.edgeFade; look = true }
     if (options.coverage !== undefined) { state.coverage = options.coverage; look = true }
     if (look) _creator.foliageSetLook?.(state.canopy, state.normalMap, state.edgeFade, state.coverage)
+    if (options.castDistance !== undefined) { state.castDistance = options.castDistance; _creator.foliageSetCast?.(state.castDistance) }
   },
 
   /** The wind: fields given replace the current ones; `false` = calm. Live. */

package/src/gl/Lightmap.ts

@@ -221,13 +221,18 @@ export class Lightmap {
   /** The bake bound last (`load`): what `probe` reads rects from. */
   private static bound: Bound | null = null
 
-  /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
-   *  both receivers and occluders in the bake. `key` names the entry in the .bake (default:
-   *  the node's name + a running number, `container#3`); pass one when names are not stable. */
+  /** Register static geometry — a Model, a Mesh, a Terrain's node, or any node whose subtree holds them. Statics are
+   *  both receivers and occluders in the bake (a model without lightmap UVs, or with materials the lightmap shader
+   *  declines — alpha cards — is an occluder alone; a terrain is ONE rect, built with `Material.terrainLightmap()`).
+   *  `key` names the entry in the .bake (default: the node's name + a running number, `container#3`); pass one when
+   *  names are not stable. */
   static add(node: Node, key?: string): Node {
     const base = key ?? `${node.name || "node"}#${Lightmap.next(node.name || "node")}`
     const found: Entry[] = []
     const walk = (n: Node): void => {
+      // the node `Terrain.create` returned carries its terrain (Terrain.of reads the same field): the host keeps the
+      // terrain's triangles under this node's id for the bake and binds the rect to its chunks
+      if ((n as unknown as { _terrain?: unknown })._terrain) { found.push({ key: base, ground: n }); return }
       if (n instanceof Model) { found.push({ key: base, model: n }); return }
       if (n instanceof Mesh) { found.push({ key: base, mesh: n }); return }
       for (const c of n.children) walk(c)

package/src/gl/Material.ts

@@ -451,8 +451,17 @@ export class Material {
     return Material._folTemplate
   }
   private static _folTemplate: Material | null | undefined
+  /** Which material a foliage model's CARDS (its alpha-MASK materials) take: `"full"` = `foliage-masked`, the
+   *  shader with the card's own plane, normal map, edge fade and the ground's baked light; `"lean"` =
+   *  `foliage-cards`, the same wind with the lighting moved to the vertex (one texture read, the sun's shadow
+   *  kept) — a third of a forest frame less on a phone-class GPU (2026-10-18). Read when the first foliage
+   *  model loads; set it before. */
+  static foliageCards: "full" | "lean" = "full"
   static _foliageMaskedTemplate(): Material | null {
-    if (Material._folMaskedTemplate === undefined) Material._folMaskedTemplate = Material._glbTemplate(_creator.builtinMaterial("foliage-masked"))
+    if (Material._folMaskedTemplate === undefined) {
+      const lean = Material.foliageCards === "lean" ? _creator.builtinMaterial("foliage-cards") : null
+      Material._folMaskedTemplate = Material._glbTemplate(lean ?? _creator.builtinMaterial("foliage-masked"))
+    }
     return Material._folMaskedTemplate
   }
   private static _folMaskedTemplate: Material | null | undefined

package/src/gl/Scatter.ts

@@ -0,0 +1,67 @@
+// A loaded model drawn many times — grass, ground cover, a bush kind — by hardware instancing (2026-10-18, the
+// Forest's grass): `new Scatter(kind, placements)` lays the kind's level-0 meshes out at every placement with the
+// kind's OWN material instances, so a foliage kind keeps its wind, its touch, the ground's baked light and its
+// distance fade, and 1 778 clumps cost ~60 draws instead of 1 778. The engine buckets the placements into cells
+// and splits a cell into chunks of the platform's per-draw cap (64 native); a cell past the kind's fade distance
+// leaves the scene. The chunks are children of this node: add it to a scene, move it, destroy it like any node.
+//
+//   const grass = await Model.load(asset('./kinds/grass.glb'), { foliage: true })   // the KIND: loaded, not added
+//   scene.add(new Scatter(grass, clumps))                                           // clumps: { position, yaw, scale }[]
+//
+// The kind itself need not be in a scene. Placements are fixed at construction — a carpet, not a crowd that moves
+// (InstancedMesh is the one with live transforms). On a host without the engine call the placements become clones
+// of the model under this node, the same picture at the old cost.
+
+import { Node } from "./Node"
+import type { Model } from "./Model"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+
+/** One placement: where the kind's origin stands, its yaw about +Y in degrees, its uniform scale. */
+export type ScatterPlacement = {
+  position: Vec3Like
+  /** Degrees, default 0. */
+  yaw?: number
+  /** Uniform, default 1. */
+  scale?: number
+}
+
+export type ScatterOptions = {
+  /** The cell edge in metres the placements are bucketed by (one draw per 64 placements of a cell). Default 16. */
+  cell?: number
+  /** Whether the copies cast the sun's shadow. Default false: ground cover never does. */
+  castShadows?: boolean
+  name?: string
+}
+
+export class Scatter extends Node {
+  /** Placements given. */
+  readonly count: number
+  /** Renderables the engine made (0 on a host that cloned instead). */
+  readonly draws: number
+
+  constructor(kind: Model, placements: readonly ScatterPlacement[], options: ScatterOptions = {}) {
+    super()
+    this.count = placements.length
+    if (options.name !== undefined) this.name = options.name
+    const data = new Float32Array(placements.length * 5)
+    for (let i = 0; i < placements.length; i++) {
+      const p = placements[i]
+      data[i * 5] = cx(p.position); data[i * 5 + 1] = cy(p.position); data[i * 5 + 2] = cz(p.position)
+      data[i * 5 + 3] = p.yaw ?? 0
+      data[i * 5 + 4] = p.scale ?? 1
+    }
+    const made = placements.length > 0 ? _creator.createGlbScatter?.(this.id, kind.id, data, options.cell ?? 16, options.castShadows ?? false) : 0
+    this.draws = made ?? 0
+    if (made === undefined && placements.length > 0) {
+      // no engine call on this host: the old way, a clone per placement under this node
+      for (const p of placements) {
+        const m = kind.clone()
+        m.position = p.position
+        m.eulerAngles = [ 0, p.yaw ?? 0, 0 ]
+        m.scale = p.scale ?? 1
+        if (!(options.castShadows ?? false)) m.castShadows = false
+        this.add(m)
+      }
+    }
+  }
+}

package/src/gl/terrain/Terrain.ts

@@ -60,6 +60,9 @@ export type TerrainLayer = {
   /** Sample this layer triplanar in world space (cliff rock): no stretching on steep slopes; its
    *  normal map is then skipped. Default false. */
   triplanar?: boolean
+  /** The layer's MEAN COLOUR, for the plants: a grass blade's base takes the colour of the soil it stands in (the
+   *  vegetation tier's cards read the control map and these four colours). Unset on every layer = no tint. */
+  color?: ColorInput
 }
 
 export type TerrainOptions = {
@@ -864,6 +867,7 @@ export class Terrain {
       this._controlTex.wrapS = 0
       this._controlTex.wrapT = 0
       this.material.set("control", this._controlTex)
+      this._pushGroundTint()
       return
     }
     const r = region ?? { x0: 0, z0: 0, x1: this.sizeX - 1, z1: this.sizeZ - 1 }
@@ -873,6 +877,19 @@ export class Terrain {
     _creator.updateTexturePixels(this._controlTex._h.id, r.x0, r.z0, w, h, sub)
   }
 
+  /** The layers' colours to the vegetation tier (TerrainLayer.color), once the control map exists. */
+  private _pushGroundTint(): void {
+    if (!this._controlTex || !this.layers.some((l) => l.color !== undefined)) return
+    const data = new Float32Array(12)
+    const lin = (v: number): number => v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4
+    this.layers.forEach((l, i) => {
+      const c = l.color !== undefined ? Color.tryParse(l.color) : null
+      if (!c) return
+      data[i * 3] = lin(c[0]); data[i * 3 + 1] = lin(c[1]); data[i * 3 + 2] = lin(c[2])
+    })
+    _creator.foliageSetGroundTint?.(this.node.id, this._controlTex._h.id, data)
+  }
+
   private async _applyLayers(normals?: TerrainOptions["normals"]): Promise<void> {
     const m = this.material
     const tiling = [ 8, 8, 8, 8 ], rough = [ 1, 1, 1, 1 ], nscale = [ 0, 0, 0, 0 ], tri = [ 0, 0, 0, 0 ]

package/src/inject.ts

@@ -246,6 +246,8 @@ export type { LocomotionSet, LocomotionClip, LocomotionTuning, LocomotionState,
 export { Material } from "./gl/Material"
 export { Geometry } from "./gl/Geometry"
 export { InstancedMesh } from "./gl/InstancedMesh"
+export { Scatter } from "./gl/Scatter"
+export type { ScatterPlacement, ScatterOptions } from "./gl/Scatter"
 export type { InstanceTransform } from "./gl/InstancedMesh"
 export { Texture } from "./gl/Texture"
 export type { TextureLoadOptions } from "./gl/Texture"

package/src/runtime/device.ts

@@ -142,6 +142,35 @@ export const device = {
   set statsOverlay(on: boolean) {
     _creatorDevice.setStatsOverlay?.(!!on)
   },
+  /** Cap the frame rate: the host runs the frame — the tick, the 3D scene — at most `fps` times a
+   *  second. `0` removes the cap: the display's own rate (120 on a 120 Hz phone), or, with vsync
+   *  off, as fast as the host renders. A REQUEST, not a state the app owns: a phone asks its panel
+   *  for the rate (a 120 Hz panel at 60 shows every frame for a full period — even, cooler) and an
+   *  OEM may refuse the switch, in which case the host renders every second refresh instead; the
+   *  screen's own maximum always wins. The tick IS the frame here, so a cap of 30 is 30 Hz of game
+   *  logic and input sampling too — raise it for gameplay. Host state: it stays through a project
+   *  swap. A no-op on hosts whose loop has no pacing of its own (web, headless). */
+  setFrameRate(fps: number): void {
+    const n = +fps
+    _creatorDevice.setFrameRate?.(n > 0 && Number.isFinite(n) ? n : 0)
+  },
+  /** Vertical sync: `false` presents without waiting for the display's refresh — the lowest input
+   *  latency, tearing possible, and with no cap set (`setFrameRate(0)`) the loop renders as fast as
+   *  it can. Set a cap unless you are measuring. Desktop only: a mobile compositor never presents
+   *  outside the refresh. Returns whether the host took the request (`false` on a host without
+   *  the switch), so a settings menu can hide the toggle. */
+  setVsync(enabled: boolean): boolean {
+    if (!_creatorDevice.setVsync) return false
+    _creatorDevice.setVsync(!!enabled)
+    return true
+  },
+  /** The display's refresh rate in Hz: the fastest the screen offers the app — 120 on a 120 Hz
+   *  phone whatever mode a cap has put it in (an iPhone's 60 unless the app's Info.plist lifts the
+   *  floor), the monitor's current mode on desktop. The sensible choices of a frame-rate menu are
+   *  its divisors. 0 where the host cannot tell (web). */
+  get displayRefreshRate(): number {
+    return _creatorDevice.displayRefreshRate?.() ?? 0
+  },
   /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
    *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
    *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.3.1"
+export const SDK_VERSION = "2.4.1"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {