lecodes-cli 0.18.1 → 0.19.0

package/runtime/sdk/gl/Scene.ts

@@ -8,6 +8,7 @@
 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 { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { _requestCameraPermission } from "../plugins/permission"
@@ -115,6 +116,14 @@ export type SceneOptions = {
    *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
    *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
   anisotropy?: number
+  /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
+   *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
+   *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
+   *  1..8 is where white lands as a multiple of SDR white — the "HDR brightness" of a console
+   *  calibration screen, where 1.5–2 is the norm; default 1 keeps a white wall at the UI's white,
+   *  faithful but dim next to what "HDR on" is expected to look like. Engine-wide like `anisotropy`;
+   *  `device.hdr` is the runtime form and tells you whether the display has any headroom at all. */
+  hdr?: { strength?: number; paperWhite?: number }
 }
 
 // Route aspect update(dt) through the render-synced native phases (render() early = before physics,
@@ -132,6 +141,13 @@ const installRenderSyncedFrames = (): void => {
     _creator.setEarlyUpdate((dt: number) => { glState.frame++; early(dt) })
     _creator.setLateUpdate(late)
     return true
+  }, (fixed) => {
+    // The fixed phase runs INSIDE the engine's substep loop (physics/world.cpp) when the host has the
+    // hook; each substep moves bodies natively, so the frame stamp bumps per step too. Feature-detected:
+    // an older host returns false and the dispatcher steps its own 1/60 accumulator.
+    if (typeof _creator.setFixedUpdate !== "function") return false
+    _creator.setFixedUpdate((dt: number) => { glState.frame++; fixed(dt) })
+    return true
   })
   // Time.scale / Time.paused reach the engine's own clocks (physics, animators, particles) through
   // setTimeScale; a host without it keeps running its sims at wall-clock speed (feature-detected).
@@ -188,6 +204,10 @@ export class Scene implements Presentable {
     // Before anything else in this constructor that could load a texture: the value has to be in
     // place by the time assets bind their samplers.
     if (options.anisotropy !== undefined) _creator.setTextureAnisotropy?.(options.anisotropy)
+    if (options.hdr) {
+      if (options.hdr.strength !== undefined) device.hdr.strength = options.hdr.strength
+      if (options.hdr.paperWhite !== undefined) device.hdr.paperWhite = options.hdr.paperWhite
+    }
     if (options.renderScale !== undefined || options.dynamicResolution) {
       this.setRenderOptions(options.renderScale ?? 1, options.dynamicResolution ?? false)
     }

package/runtime/sdk/gl/Shape.ts

@@ -22,7 +22,11 @@ import { cx, cy, cz, type Vec3Like } from "../math/vec"
 import type { Node } from "./Node"
 
 /** Which geometry a Shape uses — the one-of the fields below encode (see `_build`'s order). */
-export type ShapeKind = "auto" | "box" | "sphere" | "cylinder" | "capsule" | "mesh" | "convex"
+export type ShapeKind = "auto" | "box" | "sphere" | "cylinder" | "capsule" | "mesh" | "convex" | "heightfield"
+
+/** What a terrain node carries for `Shape { heightfield: true }` (gl/Terrain.ts `_data`). */
+type TerrainData = { sizeX: number, sizeZ: number, cellSize: number, heights: Float32Array, holes: Uint8Array | null }
+const terrainOf = (node: Node): TerrainData | null => (node as unknown as { _terrain?: { _data: TerrainData } })._terrain?._data ?? null
 
 /** A node-local AABB, in the node's OWN frame (its own transform excluded), before world scale. */
 export type ShapeBounds = { min: [number, number, number], max: [number, number, number] }
@@ -60,6 +64,10 @@ export class Shape extends Aspect<"shape", Node> {
    *  only (a dynamic body can't be a triangle mesh; Physics throws). `'convex'` = convex hull of the
    *  vertices, works for dynamic bodies too. A Model uses its bind pose (skinned parts skipped). */
   mesh?: boolean | "convex"
+  /** The node's terrain (`Terrain.create(...).node`) as a Jolt height field — the exact drawn grid,
+   *  holes included (docs/terrain-plan.md). Static / kinematic / picking / character ground only,
+   *  like `mesh: true`. `terrain.commit()` pushes edits into the live shape. */
+  heightfield?: boolean
   /**
    * The shape's centre, relative to the node's origin — world units in the node's ROTATED frame
    * (the node's scale is ignored, exactly like the explicit dimensions above). Default [0, 0, 0].
@@ -140,6 +148,7 @@ export class Shape extends Aspect<"shape", Node> {
 
   /** Which geometry this shape currently uses (the `_build` dispatch, as a name). */
   get kind(): ShapeKind {
+    if (this.heightfield) return "heightfield"
     if (this.mesh === "convex") return "convex"
     if (this.mesh) return "mesh"
     if (this.sphere !== undefined) return "sphere"
@@ -238,8 +247,14 @@ export class Shape extends Aspect<"shape", Node> {
     if (!this.raycast && this._bodyId) _creator.physicsSetPickable(this._bodyId, false)
   }
 
-  /** @internal true for an exact triangle mesh — Physics refuses a dynamic body on it. */
-  get _isTriangleMesh(): boolean { return this.mesh === true }
+  /** @internal true for an exact triangle mesh or a height field — Physics refuses a dynamic body on it. */
+  get _isTriangleMesh(): boolean { return this.mesh === true || this.heightfield === true }
+
+  /** @internal the height range a heightfield shape can encode (`Terrain.commit` rebuilds past it). */
+  _heightfieldRange: [number, number] | null = null
+
+  /** @internal rebuild the geometry in place (a terrain edit that left the encodable range). */
+  _rebuildShape(): void { this._rebuild() }
 
   // Rebuild the geometry in place: the body keeps its id, velocity and world transform (Physics
   // holds that id, so re-creating the body instead would strand it). A shape a CharacterController
@@ -290,7 +305,8 @@ export class Shape extends Aspect<"shape", Node> {
     this._autoOrigin = null
     this._sig = this._signature()
     let id = 0
-    if (this.mesh) id = this._buildMesh(this.mesh === "convex")
+    if (this.heightfield) id = this._buildHeightField()
+    else if (this.mesh) id = this._buildMesh(this.mesh === "convex")
     else if (this.sphere !== undefined) id = _creator.physicsBuildSphere(this.sphere)
     else if (this.cylinder) id = _creator.physicsBuildCylinder(this.cylinder.halfHeight, this.cylinder.radius)
     else if (this.capsule) id = _creator.physicsBuildCapsule(this.capsule.halfHeight, this.capsule.radius)
@@ -321,7 +337,23 @@ export class Shape extends Aspect<"shape", Node> {
   private _signature(): string {
     const v = (a: Vec3Like | undefined) => (a ? `${cx(a)},${cy(a)},${cz(a)}` : "")
     const t = (o: { halfHeight: number, radius: number } | undefined) => (o ? `${o.halfHeight},${o.radius}` : "")
-    return `${v(this.box)}|${this.sphere ?? ""}|${t(this.cylinder)}|${t(this.capsule)}|${this.mesh ?? ""}|${v(this.origin)}`
+    return `${v(this.box)}|${this.sphere ?? ""}|${t(this.cylinder)}|${t(this.capsule)}|${this.mesh ?? ""}|${this.heightfield ? "hf" : ""}|${v(this.origin)}`
+  }
+
+  // heightfield: the terrain on this node hands its grid over; the engine keeps its own copy and
+  // pads it to Jolt's block grid. No terrain / no host support = no collider (0), with a warning.
+  private _buildHeightField(): number {
+    const t = terrainOf(this.node)
+    if (!t) { console.warn(`Shape { heightfield }: "${this.node.name}" carries no Terrain — no collider`); return 0 }
+    if (!_creator.physicsBuildHeightField) { console.warn("Shape { heightfield } needs a newer host — the terrain has no collider"); return 0 }
+    const s = this.node.worldScale
+    let lo = Infinity, hi = -Infinity
+    for (let i = 0; i < t.heights.length; i++) { const h = t.heights[i]; if (h < lo) lo = h; if (h > hi) hi = h }
+    const range = Math.max(1, hi - lo), margin = Math.max(2, range * 0.25)
+    this._heightfieldRange = [ lo - margin, hi + margin ]   // mirrors creator-gl physicsBuildHeightField's headroom
+    const id = _creator.physicsBuildHeightField(t.heights, t.sizeX, t.sizeZ, t.cellSize, t.holes, s.x, s.y, s.z)
+    if (!id) console.warn(`Shape { heightfield }: the engine refused "${this.node.name}"'s grid (all holes?)`)
+    return id
   }
 
   // mesh: a Mesh node hands its CPU geometry over; anything else is tried as a GLB root (the host