@energy8platform/golem 0.3.0 → 0.5.0

package/dist/lib/rig-gates.d.ts

@@ -50,17 +50,17 @@ export declare const GateConfig: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }, {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }>, "many">>;
@@ -84,9 +84,9 @@ export declare const GateConfig: z.ZodObject<{
         bone: string;
         prop: "x" | "y" | "rotation";
         whenSlotVisible: string;
-        space?: "local" | "world" | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        space?: "local" | "world" | undefined;
         required?: boolean | undefined;
     }>, "many">>;
     transitions: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -130,9 +130,9 @@ export declare const GateConfig: z.ZodObject<{
     distances: {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }[];
@@ -172,9 +172,9 @@ export declare const GateConfig: z.ZodObject<{
     distances?: {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }[] | undefined;
@@ -182,9 +182,9 @@ export declare const GateConfig: z.ZodObject<{
         bone: string;
         prop: "x" | "y" | "rotation";
         whenSlotVisible: string;
-        space?: "local" | "world" | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        space?: "local" | "world" | undefined;
         required?: boolean | undefined;
     }[] | undefined;
     transitions?: {

package/dist/lib/rig-runtime.d.ts

@@ -8,8 +8,8 @@
  * - play/tick/stop are a thin wrapper over an AnimationState (see rig-state.ts) kept for simple consumers
  *   (harness, viewer). Games should drive `state` directly for queues, priorities and overlays.
  */
-import { Container, Texture } from "pixi.js";
-import { type RigDocument, type Asset } from "./rig-format";
+import { Container, Sprite, Mesh, MeshPlane, Texture } from "pixi.js";
+import { type RigDocument, type Slot, type Attachment, type Asset } from "./rig-format";
 import { type Pose, type Affine } from "./rig-anim";
 import { AnimationState, type PlayResult } from "./rig-state";
 /** vertices per axis of a lattice-deformed region's render mesh (8 segments) */
@@ -23,6 +23,22 @@ export interface PlayOptions {
     onComplete?: () => void;
     onEvent?: (name: string, payload?: Record<string, unknown>) => void;
 }
+export interface RigRenderItem {
+    att: Attachment;
+    slot: Slot;
+    node: Sprite | MeshPlane | Mesh;
+    /** lattice-deformed region */
+    lattice?: {
+        plane: MeshPlane;
+        offsets: Float64Array;
+        applied: Float64Array;
+    };
+    /** skinned mesh */
+    skinned?: {
+        mesh: Mesh;
+        positions: Float32Array;
+    };
+}
 /** Build the asset-id → Texture map, loading each `src` once and cutting atlas frames (with rotation and trim). */
 export declare function createTextures(doc: RigDocument, loadSource: (src: string) => Promise<Texture>): Promise<Map<string, Texture>>;
 /**
@@ -32,9 +48,17 @@ export declare function createTextures(doc: RigDocument, loadSource: (src: strin
 export declare function atlasUV(asset: Asset, u: number, v: number, sourceW: number, sourceH: number): [number, number];
 export declare class RigPlayer {
     doc: RigDocument;
+    private inputPose;
+    private controlOverrides;
+    /** Manual inputs override animated controls until resetControls; values are clamped to declared ranges. */
+    setControls(values: Record<string, number>): void;
+    resetControls(): void;
     readonly view: Container<import("pixi.js").ContainerChild>;
     readonly state: AnimationState;
     private items;
+    private beforePose;
+    private afterPose;
+    private clipPoints;
     private skel;
     private textures;
     private pages;
@@ -49,6 +73,19 @@ export declare class RigPlayer {
         missingAnimation?: "warn" | "throw";
         onWarning?: (message: string) => void;
     });
+    /** Read-only render handles for in-page tools. Nodes remain owned by the player. */
+    get renderItems(): readonly Readonly<RigRenderItem>[];
+    /** Current document-space clipping polygons, keyed by path attachment id. */
+    get clipPolygons(): ReadonlyMap<string, readonly number[]>;
+    /**
+     * Modify resolved control outputs before skeleton evaluation, constraints and skinning.
+     * Callbacks run in registration order, each with its own map. Change control inputs via setControls.
+     */
+    onBeforePose(callback: (pose: Pose) => Pose): () => void;
+    /** Subscribe after the base pose has been rebuilt. Return value removes the callback. */
+    onAfterPose(callback: (player: RigPlayer) => void): () => void;
+    /** Rebuild the current pose without advancing playback; useful for reversible overlays. */
+    refreshPose(): void;
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     private pageTexture;
     /** Replace whatever is playing (no queueing). Resolves when the animation completes or is replaced. */

package/dist/lib/runtime.d.ts

@@ -2,8 +2,10 @@
  * `@energy8platform/golem/runtime` — the browser half: play a rig document in PixiJS v8.
  * Depends on pixi.js (peer) and zod only; no node, no tools, no editor.
  */
-export { RigPlayer, createTextures, atlasUV, MESH_GRID, type PlayOptions } from "./rig-runtime";
+export { RigPlayer, createTextures, atlasUV, MESH_GRID, type PlayOptions, type RigRenderItem } from "./rig-runtime";
 export { RigSymbol, type RigSymbolOptions, type SymbolSize, type SymbolViewLike, type TickerLike } from "./rig-symbol";
 export { AnimationState, type PlayResult, type PoseSink } from "./rig-state";
 export { parse, validate, migrateV1, RigDocument as RigDocumentSchema } from "./rig-format";
 export type { RigDocument, Bone, Slot, Asset, Attachment, Animation, Track, Key } from "./rig-format";
+export type { RigControl, ControlBinding } from "./rig-format";
+export { controlPose, resolveControls, sampleBinding } from "./rig-controls";

package/dist/lib/runtime.js

@@ -227,6 +227,7 @@ var Key = z.object({
 });
 var Interpolation = { interpolation: z.enum(["segment", "pchip"]).optional() };
 var Track = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("control"), id: Id, prop: z.literal("value"), ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("slot"), id: Id, prop: SlotProp, ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("deform"), id: Id, prop: DeformProp, ...Interpolation, keys: z.array(Key).min(1) }),
@@ -249,6 +250,25 @@ var Animation = z.object({
   /** if generated from a preset — keep params so the agent can re-tune instead of re-keying */
   preset: z.object({ name: z.string(), params: z.record(z.unknown()) }).optional()
 });
+var RigControl = z.object({
+  id: Id,
+  label: z.string().optional(),
+  min: z.number().finite(),
+  max: z.number().finite(),
+  default: z.number().finite()
+}).strict();
+var ControlValues = z.array(z.union([z.number().finite(), z.array(z.number().finite()).min(1)])).min(2);
+var ControlChannel = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, values: ControlValues }).strict(),
+  z.object({ target: z.literal("slot"), id: Id, prop: z.literal("alpha"), values: ControlValues }).strict(),
+  z.object({ target: z.literal("deform"), id: Id, prop: z.literal("vertices"), values: ControlValues }).strict()
+]);
+var ControlBinding = z.object({
+  id: Id,
+  axes: z.array(z.object({ control: Id, keys: z.array(z.number().finite()).min(2).max(32) }).strict()).min(1).max(2),
+  /** Flattened grid, first axis varies fastest. Linear / bilinear interpolation. */
+  channels: z.array(ControlChannel).min(1)
+}).strict();
 var Reference = z.object({
   src: z.string(),
   opacity: z.number().min(0).max(1).default(0.5),
@@ -274,7 +294,9 @@ var RigSchema = z.object({
   ik: z.array(IkConstraint).default([]),
   transform: z.array(TransformConstraint).default([]),
   path: z.array(PathConstraint).default([]),
-  animations: z.array(Animation)
+  animations: z.array(Animation),
+  controls: z.array(RigControl).optional(),
+  controlBindings: z.array(ControlBinding).optional()
 });
 var RigDocument = z.preprocess((input) => {
   const v = input?.version;
@@ -349,6 +371,8 @@ function validate(doc) {
   dup(doc.ik, "ik");
   dup(doc.transform, "transform");
   dup(doc.path, "path");
+  dup(doc.controls ?? [], "control");
+  dup(doc.controlBindings ?? [], "control binding");
   const bones = new Set(doc.bones.map((b) => b.id));
   const assets = new Map(doc.assets.map((a) => [a.id, a]));
   const slots = new Set(doc.slots.map((s) => s.id));
@@ -423,13 +447,47 @@ function validate(doc) {
     for (const b of c.bones) if (!bones.has(b)) errs.push(`path "${c.id}": unknown bone "${b}"`);
     if (!slots.has(c.target)) errs.push(`path "${c.id}": unknown target slot "${c.target}"`);
   }
+  const controls = new Map((doc.controls ?? []).map((c) => [c.id, c]));
+  const driven = /* @__PURE__ */ new Set();
+  for (const c of controls.values()) if (!(c.min < c.max && c.default >= c.min && c.default <= c.max))
+    errs.push(`control "${c.id}": require min < max and default within range`);
+  for (const b of doc.controlBindings ?? []) {
+    const prefix = `control binding "${b.id}"`;
+    if (new Set(b.axes.map((a) => a.control)).size !== b.axes.length) errs.push(`${prefix}: axes must use different controls`);
+    for (const axis of b.axes) {
+      const c = controls.get(axis.control);
+      if (!c) errs.push(`${prefix}: unknown control "${axis.control}"`);
+      else if (axis.keys[0] !== c.min || axis.keys.at(-1) !== c.max) errs.push(`${prefix}: keys must span the control's full range`);
+      if (axis.keys.some((v, i) => i > 0 && v <= axis.keys[i - 1])) errs.push(`${prefix}: keys must be strictly increasing`);
+    }
+    const count = b.axes.reduce((n, a) => n * a.keys.length, 1);
+    for (const ch of b.channels) {
+      const key = `${ch.target}.${ch.id}.${ch.prop}`;
+      if (driven.has(key)) errs.push(`${prefix}: channel ${key} already owned by a binding`);
+      driven.add(key);
+      if (ch.values.length !== count) errs.push(`${prefix}: ${key} needs ${count} grid values`);
+      if (ch.target === "deform") {
+        const att = attachments.get(ch.id);
+        if (!att || att.type === "region") errs.push(`${prefix}: vertices need a mesh or path attachment`);
+        else {
+          const n = att.weights ? att.weights.reduce((s, a) => s + a.length * 2, 0) : att.vertices.length;
+          if (ch.values.some((v) => !Array.isArray(v) || v.length !== n)) errs.push(`${prefix}: ${key} needs arrays of ${n} offsets`);
+        }
+      } else {
+        if (!(ch.target === "bone" ? bones : slots).has(ch.id)) errs.push(`${prefix}: unknown ${ch.target} "${ch.id}"`);
+        if (ch.values.some((v) => typeof v !== "number")) errs.push(`${prefix}: ${key} needs numeric values`);
+        if (ch.target === "slot" && ch.values.some((v) => typeof v === "number" && (v < 0 || v > 1))) errs.push(`${prefix}: alpha must be in 0..1`);
+      }
+    }
+  }
   for (const a of doc.animations) {
     const tracks = /* @__PURE__ */ new Set();
     for (const t of a.tracks) {
       const tid = trackId(t);
       if (tracks.has(tid)) errs.push(`animation "${a.id}": duplicate track ${tid}`);
       tracks.add(tid);
-      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : true;
+      if (driven.has(tid)) errs.push(`animation "${a.id}": ${tid} is controlled by a binding; animate its control instead`);
+      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : t.target === "control" ? controls.has(t.id) : true;
       if (!known) errs.push(`animation "${a.id}": unknown ${t.target} "${t.id}"`);
       const bound = t.target === "deform" ? DEFORM_BOUNDS[t.prop] : void 0;
       const att = t.target === "deform" ? attachments.get(t.id) : void 0;
@@ -437,6 +495,10 @@ function validate(doc) {
       for (const k of t.keys) {
         if (k.t <= prev && prev >= 0) errs.push(`animation "${a.id}" ${tid}: keys not strictly increasing`);
         if (k.t > a.duration) errs.push(`animation "${a.id}" ${tid}: key at ${k.t}s exceeds duration`);
+        if (t.target === "control") {
+          const c = controls.get(t.id);
+          if (typeof k.v !== "number" || !Number.isFinite(k.v) || c && (k.v < c.min || k.v > c.max)) errs.push(`animation "${a.id}" ${tid}: control key outside its finite range`);
+        }
         if (t.target === "slot" && t.prop === "attachment") {
           if (k.v !== null && typeof k.v !== "string") errs.push(`animation "${a.id}" ${tid}: attachment key must be an attachment id or null`);
           else if (typeof k.v === "string") {
@@ -475,6 +537,52 @@ function parse(input) {
   return doc;
 }
 
+// src/rig-controls.ts
+function controlPose(doc, values) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [id, value] of Object.entries(values)) {
+    const c = doc.controls?.find((c2) => c2.id === id);
+    if (!c) throw new Error(`unknown control "${id}"`);
+    if (!Number.isFinite(value)) throw new Error(`control "${id}" must be finite`);
+    out.set(`control:${id}:value`, Math.max(c.min, Math.min(c.max, value)));
+  }
+  return out;
+}
+function bracket(keys, value) {
+  let i = 0;
+  while (i < keys.length - 2 && value > keys[i + 1]) i++;
+  return [i, Math.max(0, Math.min(1, (value - keys[i]) / (keys[i + 1] - keys[i])))];
+}
+function sampleBinding(binding, values) {
+  const [x, u] = bracket(binding.axes[0].keys, values[0]);
+  const [y, v] = binding.axes[1] ? bracket(binding.axes[1].keys, values[1]) : [0, 0];
+  const width = binding.axes[0].keys.length, a = y * width + x;
+  const mix = (a2, b, u2) => a2 + (b - a2) * u2;
+  return binding.channels.map((ch) => {
+    const read = (i, j) => j === void 0 ? ch.values[i] : ch.values[i][j];
+    const at = (j) => {
+      const top = mix(read(a, j), read(a + 1, j), u);
+      return binding.axes[1] ? mix(top, mix(read(a + width, j), read(a + width + 1, j), u), v) : top;
+    };
+    return Array.isArray(ch.values[0]) ? ch.values[0].map((_, j) => at(j)) : at();
+  });
+}
+function resolveControls(doc, input) {
+  if (!doc.controlBindings?.length) return input;
+  const out = new Map(input), controls = new Map(doc.controls?.map((c) => [c.id, c]));
+  for (const b of doc.controlBindings) {
+    const values = b.axes.map((axis) => {
+      const c = controls.get(axis.control);
+      const value = input.get(`control:${c.id}:value`) ?? c.default;
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`control "${c.id}" must be finite`);
+      return Math.max(c.min, Math.min(c.max, value));
+    });
+    const sampled = sampleBinding(b, values);
+    b.channels.forEach((ch, i) => out.set(`${ch.target}:${ch.id}:${ch.prop}`, sampled[i]));
+  }
+  return out;
+}
+
 // src/rig-anim.ts
 var DEG2 = Math.PI / 180;
 var named = {
@@ -578,6 +686,7 @@ function blendPoses(from, to, w, restOf) {
 }
 function restValue(doc, key) {
   const [target, id, prop] = key.split(":");
+  if (target === "control") return doc.controls?.find((c) => c.id === id)?.default ?? 0;
   if (target === "bone") return doc.bones.find((b) => b.id === id).transform[prop];
   if (target === "slot") {
     const s = doc.slots.find((s2) => s2.id === id);
@@ -680,7 +789,9 @@ function updateSubtree(skel, root) {
     for (const k of kids.get(id) ?? []) stack.push(k.id);
   }
 }
-function evaluate(doc, pose) {
+function evaluate(doc, pose, modifiers) {
+  pose = resolveControls(doc, pose);
+  if (modifiers) for (const modify of modifiers) pose = modify(new Map(pose));
   const skel = { doc, pose, bones: /* @__PURE__ */ new Map(), attachment: /* @__PURE__ */ new Map() };
   for (const b of boneOrder(doc)) {
     const s = localOf(doc, pose, b);
@@ -1485,9 +1596,23 @@ var RigPlayer = class {
     this.state = new AnimationState(this, { ...opts, mix: opts.mix ?? 0.18 });
     this.setPose(/* @__PURE__ */ new Map());
   }
+  inputPose = /* @__PURE__ */ new Map();
+  controlOverrides = /* @__PURE__ */ new Map();
+  /** Manual inputs override animated controls until resetControls; values are clamped to declared ranges. */
+  setControls(values) {
+    this.controlOverrides = controlPose(this.doc, values);
+    this.setPose(this.inputPose);
+  }
+  resetControls() {
+    this.controlOverrides.clear();
+    this.setPose(this.inputPose);
+  }
   view = new Container();
   state;
   items = [];
+  beforePose = /* @__PURE__ */ new Set();
+  afterPose = /* @__PURE__ */ new Set();
+  clipPoints = /* @__PURE__ */ new Map();
   skel;
   textures;
   pages = /* @__PURE__ */ new Map();
@@ -1496,6 +1621,35 @@ var RigPlayer = class {
   /** slots the editor has selected; setPose draws them at GHOST_ALPHA at least */
   ghosts = /* @__PURE__ */ new Set();
   clipGraphics = /* @__PURE__ */ new Map();
+  /** Read-only render handles for in-page tools. Nodes remain owned by the player. */
+  get renderItems() {
+    return this.items;
+  }
+  /** Current document-space clipping polygons, keyed by path attachment id. */
+  get clipPolygons() {
+    return this.clipPoints;
+  }
+  /**
+   * Modify resolved control outputs before skeleton evaluation, constraints and skinning.
+   * Callbacks run in registration order, each with its own map. Change control inputs via setControls.
+   */
+  onBeforePose(callback) {
+    this.beforePose.add(callback);
+    return () => {
+      this.beforePose.delete(callback);
+    };
+  }
+  /** Subscribe after the base pose has been rebuilt. Return value removes the callback. */
+  onAfterPose(callback) {
+    this.afterPose.add(callback);
+    return () => {
+      this.afterPose.delete(callback);
+    };
+  }
+  /** Rebuild the current pose without advancing playback; useful for reversible overlays. */
+  refreshPose() {
+    this.setPose(this.inputPose);
+  }
   /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
   pageTexture(tex) {
     let page = this.pages.get(tex.source);
@@ -1550,7 +1704,11 @@ var RigPlayer = class {
   }
   /** Apply a pose (rest where silent) to the display objects. */
   setPose(pose) {
-    const skel = this.skel = evaluate(this.doc, pose);
+    this.inputPose = new Map(pose);
+    if (this.controlOverrides.size) pose = new Map([...pose, ...this.controlOverrides]);
+    this.clipPoints.clear();
+    const skel = this.skel = evaluate(this.doc, pose, this.beforePose);
+    pose = skel.pose;
     const clips = new Set(this.doc.slots.flatMap((s) => s.clip ? [s.clip] : []));
     for (const [id, g] of this.clipGraphics) if (!clips.has(id)) {
       g.destroy();
@@ -1568,7 +1726,9 @@ var RigPlayer = class {
       const vertices = attachmentWorldVertices(skel, att.slot, att);
       const n = Math.max(32, vertices.length * 4);
       const points = samplePath(vertices, true, att.lengths, true, Array.from({ length: n }, (_, i) => i / n), true);
-      g.clear().poly(points.flatMap((p) => [p.x, p.y]), true).fill(16777215);
+      const polygon = points.flatMap((p) => [p.x, p.y]);
+      this.clipPoints.set(id, polygon);
+      g.clear().poly(polygon, true).fill(16777215);
     }
     const m = new Matrix();
     const orderV = pose.get(pk("drawOrder", "order", "order"));
@@ -1589,6 +1749,7 @@ var RigPlayer = class {
       it.node.tint = rgbOf(color);
       it.node.zIndex = order.size ? order.get(s.id) ?? 0 : numOf(pose, pk("slot", s.id, "z"), s.z);
       if (it.skinned) {
+        it.node.setFromMatrix(m.identity());
         const v = attachmentWorldVertices(skel, s.id, it.att);
         const buf = it.skinned.mesh.geometry.getBuffer("aPosition");
         buf.data.set(v);
@@ -1621,6 +1782,7 @@ var RigPlayer = class {
         it.node.scale.y *= h / (this.textures.get(att.asset)?.height ?? h);
       }
     }
+    for (const callback of this.afterPose) callback(this);
   }
   /** World-space bone positions — used by editor gizmos and renderPreview overlays */
   bonePositions() {
@@ -1697,9 +1859,12 @@ export {
   RigPlayer,
   RigSymbol,
   atlasUV,
+  controlPose,
   createTextures,
   migrateV1,
   parse,
+  resolveControls,
+  sampleBinding,
   validate
 };
 //# sourceMappingURL=runtime.js.map