lecodes-sdk 1.0.0 → 1.1.0

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 -----------------------------------------------------------------------------
@@ -286,6 +290,15 @@ 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).
@@ -477,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)
@@ -530,6 +544,8 @@ 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) {
@@ -620,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
@@ -635,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()
@@ -650,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)
@@ -686,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

@@ -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

package/src/gl/animation/AnimationClip.ts

@@ -82,6 +82,8 @@ export class AnimationClip {
   readonly _index: number
   /** @internal events: seconds + name, sorted (the engine gets them normalized via setClipEvents). */
   _events: { t: number, name: string }[] = []
+  /** @internal anchor spans per bone, seconds (the engine gets them normalized via setClipAnchors). */
+  _anchors: { bone: string, donor: string, spans: { from: number, to: number, socket: string, rotation: number, pin: number }[] }[] = []
 
   private constructor(set: number, index: number, info: ClipInfo) {
     this._set = set
@@ -119,6 +121,48 @@ export class AnimationClip {
     _creator.setClipEvents(this._set, this._index, new Float32Array(this._events.map((e) => (d > 0 ? e.t / d : 0))))
   }
 
+  /** ANCHOR SPANS for a bone — what an anchored IK chain ending in `bone` rides while this clip plays
+   *  (`IK.TwoBone` with `anchor`; the sockets come from `anim.sockets(...)`). `donor` names the socket
+   *  set of the gun the take was AUTHORED on ('' = the live set: no delta); `spans` = `[from, to,
+   *  socket, rotation?, pin?]` in SECONDS — the socket the hand is on through that window (`''` = free:
+   *  it rides the joint itself), `rotation` 0..1 how much of the socket's turn it takes (default 1),
+   *  `pin` 0..1 how much it sits ON the socket instead of keeping its own relation to it (default 0: a
+   *  magazine is REACHED, and the take's motion is what carries the hand there).
+   *  Gaps between spans = the chain's own socket, pinned by the chain's `anchorPin` — that is where a
+   *  hand holding the gun is nailed to the grip, so the layers below cannot slide it. A clip WITHOUT
+   *  anchors takes no part: the hand keeps the take's own relation to the gun. Part of the clip, like
+   *  events; `AnimationClip.from` carries them re-timed. Chainable.
+   *    reload.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag'], [2.4, 2.7, 'bolt']] }) */
+  anchors(bone: string, def: { donor?: string, spans?: readonly (readonly [number, number, string, number?, number?])[] }): this {
+    const spans = (def.spans ?? []).map(([ from, to, socket, rotation, pin ]) => ({
+      from: Math.min(Math.max(0, from), this.duration), to: Math.min(Math.max(0, to), this.duration), socket,
+      rotation: rotation ?? 1, pin: pin ?? 0,
+    })).filter((s) => s.to > s.from).sort((a, b) => a.from - b.from)
+    const rec = { bone, donor: def.donor ?? "", spans }
+    const i = this._anchors.findIndex((a) => a.bone === bone)
+    if (i >= 0) this._anchors[i] = rec
+    else this._anchors.push(rec)
+    this._pushAnchors(rec)
+    return this
+  }
+  /** Drop a bone's anchor spans. */
+  clearAnchors(bone: string): this {
+    this._anchors = this._anchors.filter((a) => a.bone !== bone)
+    _creator.setClipAnchors?.(this._set, this._index, bone, "", "", new Float32Array(0))
+    return this
+  }
+  private _pushAnchors(a: { bone: string, donor: string, spans: { from: number, to: number, socket: string, rotation: number, pin: number }[] }): void {
+    const d = this.duration
+    const spans = new Float32Array(a.spans.length * 4)
+    a.spans.forEach((s, i) => {
+      spans[i * 4] = d > 0 ? s.from / d : 0
+      spans[i * 4 + 1] = d > 0 ? s.to / d : 0
+      spans[i * 4 + 2] = s.rotation
+      spans[i * 4 + 3] = s.pin
+    })
+    _creator.setClipAnchors?.(this._set, this._index, a.bone, a.donor, a.spans.map((s) => s.socket).join("\n"), spans)
+  }
+
   /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
   static load(source: string | FetchResponse, clip?: string | number): Promise<AnimationClip> {
     return AnimationClip._loadSet(source).then(([setId, infos]) => {
@@ -200,6 +244,14 @@ export class AnimationClip {
     out._events = windowed
       ? clip._events.filter((ev) => ev.t >= st - 1e-6 && ev.t <= e + 1e-6).map((ev) => ({ t: Math.min(Math.max(0, ev.t - st), e - st), name: ev.name }))
       : clip._events.map((ev) => ({ ...ev }))
+    // the anchor spans too: clipped to the window and re-timed (a mirrored clip keeps its bone names —
+    // mirror the sockets yourself if a hand's anchors must swap sides)
+    for (const a of clip._anchors) {
+      const spans = windowed
+        ? a.spans.map((s) => ({ ...s, from: Math.max(0, s.from - st), to: Math.min(e - st, s.to - st) })).filter((s) => s.to > s.from)
+        : a.spans.map((s) => ({ ...s }))
+      if (spans.length > 0 || a.donor) out.anchors(a.bone, { donor: a.donor, spans: spans.map((s) => [ s.from, s.to, s.socket, s.rotation ] as const) })
+    }
     return out
   }
 

package/src/gl/animation/Animator.ts

@@ -17,9 +17,12 @@
 // default. A clip may be replaced at any time; a one-shot on a layer with no loop holds its last frame.
 //
 // The surface, top to bottom: clips → playing → root motion → the feet and the warp (`anim.feet`,
-// `anim.warp` — locomotion's post-processing of the pose) → level of detail → engine-facing.
+// `anim.warp` — locomotion's post-processing of the pose) → sockets (what IK chains ride) → level of
+// detail → engine-facing.
 
 import { Aspect } from "../../core/Aspect"
+import { Vec3, type Vec3Like } from "../../math/vec"
+import { Quat, type QuatLike } from "../../math/quat"
 import type { Node } from "../Node"
 import type { AnimationClip } from "./AnimationClip"
 import { Core, type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
@@ -122,6 +125,41 @@ export class Animator extends Aspect<"anim", Node> {
    *  turn too); on for a rig whose root carries the heading (`lecodes assets retarget --root-rotation yaw`). */
   get rootRotation(): boolean { return this._rootRotation }
   set rootRotation(on: boolean) { this._rootRotation = on; if (this._rootMotion) this._c.setRootMotion(true, on) }
+  /** The body's WORLD velocity this frame (m/s): what `anim.warp`'s stride and orientation fit the clips
+   *  to. A `Locomotion` feeds it itself; when you drive the gait by hand set it every frame (the
+   *  CharacterController's velocity, or your own). Reads back the last value fed. */
+  get motion(): readonly [number, number, number] { return this._motion }
+  set motion(v: { x: number, y: number, z: number } | readonly [number, number, number]) {
+    const [ x, y, z ] = Array.isArray(v) ? v as readonly [number, number, number] : [ (v as { x: number }).x, (v as { y: number }).y, (v as { z: number }).z ]
+    this._motion = [ x, y, z ]
+    this._c.setMotion(x, y, z)
+  }
+  private _motion: readonly [number, number, number] = [ 0, 0, 0 ]
+
+  // ---- sockets (what anchored IK chains ride — IK.ts) ---------------------------------------------
+  /** SOCKETS: named frames on a bone of this rig — a weapon's grip / magazine / bolt empties, placed in
+   *  the scene editor. A NODE socket is read by the engine every frame (a socket on a moving part
+   *  follows it); a `{ position, quaternion }` one is fixed in the bone's space. The default set is the
+   *  LIVE one (the weapon in the hands); `set: 'tr15'` names a DONOR set — the same sockets on the gun a
+   *  take was authored on, which a clip's `anchors()` refer to. Chainable.
+   *    arms.anim.sockets('ik_hand_gun', { grip_r: w.gripR, grip_l: w.gripL, mag: w.mag })
+   *    arms.anim.sockets('ik_hand_gun', { grip_l: { position: [0.03, -0.12, -0.05] } }, { set: 'tr15' }) */
+  sockets(joint: Node | string, table: Record<string, Node | { position?: Vec3Like, quaternion?: QuatLike }>, options: { set?: string } = {}): this {
+    const bone = typeof joint === "string" ? this.node.bone(joint) : joint
+    if (!bone) { console.warn(`Animator.sockets: no bone '${String(joint)}' under ${this.node.name || "the node"}`); return this }
+    const set = options.set ?? ""
+    for (const [ name, at ] of Object.entries(table)) {
+      if (typeof (at as Node).id === "number") this._c.setSocket(set, name, bone.id, (at as Node).id, null)
+      else {
+        const o = at as { position?: Vec3Like, quaternion?: QuatLike }
+        const p = new Vec3(o.position ?? [ 0, 0, 0 ]), q = o.quaternion ? new Quat(o.quaternion) : Quat.identity
+        this._c.setSocket(set, name, bone.id, 0, new Float32Array([ p.x, p.y, p.z, q.x, q.y, q.z, q.w ]))
+      }
+    }
+    return this
+  }
+  /** Drop a socket (the live set, or `set`). */
+  removeSocket(name: string, set = ""): this { this._c.removeSocket(set, name); return this }
 
   // ---- level of detail --------------------------------------------------------------------------
   /** `'auto'` (default): a character small on screen or out of view is evaluated every 2nd / 4th frame
@@ -130,9 +168,11 @@ export class Animator extends Aspect<"anim", Node> {
   get lod(): "auto" | "full" { return this._lod }
   set lod(v: "auto" | "full") { this._lod = v; _pushLod(this.node) }
 
-  // ---- engine-facing (a Locomotion, a bench) --------------------------------------------------
+  // ---- engine-facing (a Locomotion, a bench, the IK aspects) ----------------------------------
   /** The native animator's id — 0 until something is played or bound. */
   get _id(): number { return this._c.id }
+  /** @internal the engine-facing core (IK.ts) */
+  get _core(): Core { return this._c }
   /** Bind a clip to the base layer without playing it; its native slot (-1 = no such clip). */
   _slot(clip: string | number): number { return this._c.slotIndex(clip) }
 }