lecodes-sdk 0.19.2 → 0.20.0

package/src/bridges.d.ts

@@ -251,11 +251,13 @@ declare global {
     animatorBind(animatorId: number, clipSetId: number, clipIndex: number, layer: number): number
     animatorBoundTracks(animatorId: number, slot: number): number
     // The layer's LOOP: member slots + positions (dims 1: x per member, 2: x,y; one member = a plain looping
-    // clip). The members share ONE cycle clock (aligned by their foot contacts, not by normalized time) and
-    // animatorSetBlendValue picks the mix (1D linear between neighbours / 2D gradient band). Setting it
-    // takes the layer over from whatever it shows — the previous loop and any one-shot on it go silent — with
-    // a transition of `fade`. Empty = no loop. speed = the members' rate.
-    animatorSetBlend(animatorId: number, layer: number, dims: 1 | 2, slots: Uint16Array, positions: Float32Array, fade: number, speed: number): void
+    // clip). The members share ONE cycle clock, each placed on it LINEARLY by `phases` — two floats per member,
+    // (offset, cycles): φ(t) = offset + cycles · t / duration, 0 at a left-foot-down (measured offline
+    // from the clip's foot marks). An empty array, or cycles <= 0 for a member = normalized time (0, 1) and no
+    // cycle to phase-match to — the clock never reads the clip's marks. animatorSetBlendValue picks the mix (1D linear between neighbours /
+    // 2D gradient band). Setting it takes the layer over from whatever it shows — the previous loop and any
+    // one-shot on it go silent — with a transition of `fade`. Empty = no loop. speed = the members' rate.
+    animatorSetBlend(animatorId: number, layer: number, dims: 1 | 2, slots: Uint16Array, positions: Float32Array, fade: number, speed: number, phases: Float32Array): void
     animatorSetBlendValue(animatorId: number, layer: number, x: number, y: number): void
     // Play a slot as the layer's one-shot, transitioned in over fadeIn (0 = cut) from whatever the layer
     // showed (playing a blend MEMBER brings the whole blend back instead). A non-looping one-shot hands the
@@ -322,6 +324,11 @@ declare global {
     // The earliest time in the slot where that hand-over costs no more than `tolerance` metres;
     // atContact snaps to the next foot-down at or after it. -1 = never that close.
     animatorSlotExit(animatorId: number, slot: number, target: number, tolerance: number, atContact: boolean, align: 0 | 1): number
+    // CYCLE ALIGNMENT by pose, no marks: given slot a's cycle (offA, cyclesA), the (offset, cycles) of slot b
+    // under which the two loops show the same pose at the same gait phase — b's cycle count searched over
+    // cyclesA × {1/3 … 3}, its offset on a fine grid. out = [offset, cycles, score (metres), margin (runner-up
+    // ≥ 0.2 cycle away minus the best; ~0 = ambiguous)]. Returns 1, or 0 when there is nothing to compare.
+    animatorSlotAlign(animatorId: number, a: number, b: number, offA: number, cyclesA: number, out: Float32Array): number
     // Contact spans as (side 0 left / 1 right, from, to, atX, atY, atZ) sextuplets (seconds, model space);
     // returns the span count, filling `out` up to its capacity.
     animatorSlotContacts(animatorId: number, slot: number, out: Float32Array): number
@@ -667,7 +674,7 @@ declare global {
     createAnchor(sceneId: number, physicalWidth: number, systemId: number): number
 
     // Particles. All emitter/curve config crosses as ONE Float32Array of [tag, payloadLen,
-    // ...payload] records, parsed once in creator-gl (PsTag in creator-gl/src/particles.h; the
+    // ...payload] records, parsed once in creator-particles (CPART_TAG_* in creator-particles.h; the
     // SDK mirror is in gl/Particles.ts, guarded by sdk/tests/particles-tags.test.ts). Unknown
     // tags skip by length. maxParticles 0 = default (1000).
     createParticleSystem(entityId: number, materialInstanceId: number, maxParticles: number): void

package/src/compile/__tests__/compile.test.ts

@@ -285,3 +285,15 @@ test("buildHeader / detectProjectKind signal the engine from bundled code", () =
   expect(detectProjectKind("const x = 1")).toBe("ui")
   expect(detectProjectKind("_creator.createARController()")).toBe("ar")
 })
+
+test("a .json project file is data — asset()/import gives the parsed value", async () => {
+  const js = await compileProject({
+    name: "Data", publicUrl: "https://le.codes", header: false,
+    entries: [
+      { path: "/main.ts", type: "text", text: 'toast(asset("./style.json").name)\n' },
+      { path: "/style.json", type: "text", text: '{ "name": "OSM Bright", "version": 8 }\n' },
+    ],
+  })
+  expect(js).toContain("OSM Bright")
+  expect(js).not.toContain('"./style.json"') // desugared to the import, not left as a string
+})

package/src/compile/compileProject.ts

@@ -108,6 +108,11 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
       }
     } else if (e.path.toLowerCase().endsWith(".svg")) {
       files[e.path] = `export default SvgSource(\`${e.text ?? ""}\`)`
+    } else if (e.path.toLowerCase().endsWith(".json")) {
+      // A .json project file is DATA, not code: `import data from "./x.json"` — and `asset("./x.json")`,
+      // which desugars to that import — yields the parsed value. The bundler would otherwise try to
+      // parse the file as JS. JSON is an expression, so a default export is the whole translation.
+      files[e.path] = `export default ${e.text?.trim() || "null"}`
     } else {
       files[e.path] = e.text ?? ""
     }

package/src/core/Aspect.ts

@@ -213,7 +213,7 @@ let fixedFallbackAcc = 0
 // The FIXED phase: dt = Time.fixedDt (1/60) every call, once per physics substep, on every host. The
 // engine drives it from inside its substep loop when it has the hook; otherwise (older wasm / Apple /
 // Android builds, the setLoop path) the SDK steps its own accumulator right after the early phase -
-// same step, same 4-substep cap, same drop-the-backlog rule as creator-gl's physics/world.cpp.
+// same step, same 4-substep cap, same drop-the-backlog rule as creator-physics' cphysFrameBegin.
 const fixedStep: PhaseFn = (dt) => { _phaseHooks.fixed?.(dt); fixedUpdaters.run("updateFixed", dt) }
 const fixedFallback = (): void => {
   const step = Time.fixedDt

package/src/gl/CameraPlace.ts

@@ -1,52 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
-   *  clicking it selects the node. Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}

package/src/gl/Locomotion.ts

@@ -29,7 +29,9 @@
 
 import { Aspect } from "../core/Aspect"
 import { Vec3, cx, cz, type Vec3Like } from "../math/vec"
-import { Animator, type FeetOptions, type WarpOptions } from "./animation/Animator"
+import { Animator } from "./animation/Animator"
+import type { FeetOptions } from "./animation/Feet"
+import type { WarpOptions } from "./animation/Warp"
 import { CharacterController } from "./CharacterController"
 import type { Node } from "./Node"
 
@@ -288,8 +290,8 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     for (const c of this.set.stops ?? []) this.enter(c, KIND.STOP)
     for (const c of this.set.turns ?? []) this.enter(c, KIND.TURN)
     for (const c of this.set.spins ?? []) this.enter(c, KIND.SPIN)
-    if (this.warp !== undefined) anim.warp = this.warp
-    anim.feet = this.feet === undefined ? { lock: true } : this.feet === true ? { lock: true, ik: true } : this.feet === false ? { lock: false, ik: false } : this.feet
+    if (this.warp !== undefined) anim.warp.set(this.warp)
+    anim.feet.set(this.feet === undefined ? { lock: true } : this.feet === true ? { lock: true, ik: true } : this.feet === false ? { lock: false, ik: false } : this.feet)
     this.pushTuning()
   }
 
@@ -303,7 +305,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     if (slot < 0) { console.warn(`Locomotion: no clip '${n}' on ${this.node.name || "the character"}`); return }
     this._names.set(slot, n)
     const o = typeof clip === "string" ? undefined : clip
-    const measured = anim.curves(n)
+    const measured = anim.clipInfo(n)
     const angle = o?.angle ?? (measured ? measured.turn * RAD2DEG : 0)
     const gait = kind === KIND.GAIT ? -1 : o?.gait ? GAITS.indexOf(o.gait) : -1
     _creator.locoSetEntry(this._loco, slot, kind, angle, o?.speed ?? 0, gait)
@@ -422,7 +424,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     const named = t ? t[this._gait] : undefined
     if (named !== undefined) return named * this._mag
     const clip = (this.set.gaits ?? [])[GAITS.indexOf(this._gait)]
-    const measured = clip !== undefined ? this.anim?.curves(name(clip))?.speed : undefined
+    const measured = clip !== undefined ? this.anim?.clipInfo(name(clip))?.speed : undefined
     return (measured ?? 0) * this._mag
   }
 

package/src/gl/Particles.ts

@@ -3,8 +3,8 @@
 //
 // All emitter/curve config crosses the bridge as ONE Float32Array of [tag, payloadLen, ...payload]
 // records (_creator.setParticleSystemConfig) — the constructor batches every option into a single
-// call, live setters send a one-record buffer. The tag values mirror PsTag in
-// creator-gl/src/particles.h (guarded by tests/particles-tags.test.ts).
+// call, live setters send a one-record buffer. The tag values mirror CPART_TAG_* in
+// creator-particles/include/creator-particles/creator-particles.h (guarded by tests/particles-tags.test.ts).
 //
 // Curves over a particle's lifetime are built with curve()/colorCurve() chains — see the builders
 // below. A builder's whole state is the flat `_data` array (the exact record payload), so the
@@ -18,7 +18,7 @@ import { Node } from "./Node"
 
 type Range<T> = T | { min: T, max: T }
 
-// --- config record tags (keep in sync with PsTag in creator-gl/src/particles.h) -----------------
+// --- config record tags (keep in sync with CPART_TAG_* in creator-particles.h) ------------------
 
 const TAG_SHAPE = 1
 const TAG_LIFETIME = 2