lecodes-cli 0.18.2 → 0.19.0

package/runtime/sdk/gl/Scene.ts

@@ -141,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).

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