@vgai/engine 0.2.0 → 0.3.0

package/src/tools/define-tool.ts

@@ -0,0 +1,152 @@
+/**
+ * Project tools — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3 contract).
+ *
+ * A project tool is ONE file, `src/tools/<name>.tool.tsx`, discovered by
+ * folder scan (same physics as data assets, §3.1: zero registration, delete
+ * the file → gone). The file exports exactly two things:
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'tuning',          // stable slug — becomes the tab's test id
+ *   title: 'Tuning',       // the tab label (rendered after a ⚙ marker)
+ *   placement: 'dock',     // project-global dashboard tab (§3.2)
+ * });
+ * export default function Tuning() { … }   // plain React
+ * ```
+ *
+ * or, selection-scoped (W3 — §3.2's second placement):
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'spin',
+ *   title: 'Spin',
+ *   placement: 'inspector',                  // selection-scoped section
+ *   match: (node) => node?.kind === 'mesh',  // same contract as the
+ * });                                        // inspector-section registry
+ * export default function Spin({ node }: InspectorToolProps) { … }
+ * ```
+ *
+ * The editor renders dock tools as visually distinct tabs after a separator
+ * at the end of the bottom dock's tab row (§3.5); inspector tools render as
+ * a ⚙-marked section in the Inspector rail whenever `match` accepts the
+ * current selection. Both render inside an error boundary — a crashing tool
+ * never takes the editor down. Tools are EDITOR-ONLY: no game build bundles
+ * `src/tools/` (§4 — nothing in game code imports it), so dev/cheat surfaces
+ * can never leak into a tester serve.
+ *
+ * This module is deliberately react-free metadata (the engine core outside
+ * `src/react/` must not import react — `test/react-core-import-ban.test.ts`);
+ * the react-facing tool hooks live in `@engine/react/use-data`, and the
+ * editor-styled widget kit tools build panels from is `@editor/widgets`.
+ */
+
+import type { AuthoringAdapter, EditorNode } from '../adapter';
+
+/** The two placements (§3.2). Deliberately nothing else — no floating
+ *  windows, no in-game overlay host (§3.2 "deliberately NOT built"). */
+export type ToolPlacement = 'dock' | 'inspector';
+
+/** Fields every tool declares — see {@link defineTool} for the contract. */
+interface ToolConfigBase {
+  /**
+   * Stable slug for this tool: letters/digits/`-`/`_` only. It becomes the
+   * mount's `data-testid` (`bottom-tab-tool-<id>` for dock tools,
+   * `inspector-tool-<id>` for inspector tools), so keep it short and never
+   * rename it casually — automation and saved layouts key off it.
+   */
+  id: string;
+  /** Human label: the dock tab text, or the inspector section's header,
+   *  rendered after the ⚙ project-tool marker (§3.5). */
+  title: string;
+}
+
+/** A project-global dashboard tab in the bottom dock (§3.2, W4). */
+export interface DockToolConfig extends ToolConfigBase {
+  placement: 'dock';
+}
+
+/** A selection-scoped Inspector section (§3.2, W3). */
+export interface InspectorToolConfig extends ToolConfigBase {
+  placement: 'inspector';
+  /**
+   * When this section appears — the SAME contract as the editor's
+   * `inspector-section-registry`: called with the currently selected node
+   * (`null` in the no-selection/environment state) and the active authoring
+   * adapter; return `true` to render. Keep it cheap and pure — it runs on
+   * every inspector render. A `match` that throws is treated as `false`
+   * (with one console teaching error), never crashing the inspector.
+   */
+  match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
+}
+
+/** Metadata for a project tool — a discriminated union on `placement`. */
+export type ToolConfig = DockToolConfig | InspectorToolConfig;
+
+/**
+ * Props the editor passes to an INSPECTOR tool's default-exported component
+ * (dock tools receive no props). Everything richer (live game store, field
+ * addresses) arrives through the §3.3 hooks, not through more props.
+ */
+export interface InspectorToolProps {
+  /** The selected node your `match` accepted (`null` in the no-selection
+   *  state, if your `match` chose to accept it). */
+  node: EditorNode | null;
+  /** The selected node's stable id (`null` in the no-selection state). */
+  nodeId: string | null;
+}
+
+const TEMPLATE_EXAMPLE = 'the template worked example: src/tools/example.tool.tsx';
+
+/** Teaching-error helper (§6.5): every rejection names the fix and cites the
+ *  template example by path. */
+function toolError(problem: string, fix: string): Error {
+  return new Error(`defineTool: ${problem} — ${fix} (see ${TEMPLATE_EXAMPLE}).`);
+}
+
+/**
+ * Validate and freeze a project tool's metadata (docs/DATA-TOOLS-DESIGN.md
+ * §3.1). Call it once at module scope of a `src/tools/<name>.tool.tsx` file
+ * and export the result as `tool`, next to a default-exported React
+ * component — the editor's folder scan picks the file up automatically.
+ *
+ * Fails loud (§6.5 "errors teach") on anything malformed rather than letting
+ * a half-shaped tool render confusingly: bad `id`/`title`, an unknown
+ * placement, an inspector tool without a callable `match`.
+ *
+ * The returned config is frozen: tool metadata is a definition, not state
+ * (the same immutability rule data assets follow, §2.1).
+ */
+export function defineTool(config: ToolConfig): Readonly<ToolConfig> {
+  if (config === null || typeof config !== 'object') {
+    throw toolError(
+      'expected a config object',
+      "call it as defineTool({ id, title, placement: 'dock' })",
+    );
+  }
+  const { id, title, placement } = config;
+  if (placement !== 'dock' && placement !== 'inspector') {
+    throw toolError(
+      `unknown placement ${JSON.stringify(placement)}`,
+      "the placements are 'dock' (project-global bottom tab) and 'inspector' (selection-scoped section, §3.2)",
+    );
+  }
+  if (typeof id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(id)) {
+    throw toolError(
+      `invalid id ${JSON.stringify(id)}`,
+      'pass a non-empty slug of letters, digits, "-" or "_" — it becomes the tool\'s data-testid (bottom-tab-tool-<id> / inspector-tool-<id>)',
+    );
+  }
+  if (typeof title !== 'string' || title.trim() === '') {
+    throw toolError(`invalid title ${JSON.stringify(title)}`, 'pass a short human-readable label');
+  }
+  if (placement === 'inspector') {
+    if (typeof config.match !== 'function') {
+      throw toolError(
+        `placement 'inspector' requires a match function (got ${JSON.stringify(config.match)})`,
+        "pass match: (node) => boolean — e.g. match: (node) => node?.kind === 'mesh' — deciding which selections show this section",
+      );
+    }
+    return Object.freeze({ id, title, placement, match: config.match });
+  }
+  return Object.freeze({ id, title, placement });
+}

package/src/animation/anim-graph.ts

@@ -1,406 +0,0 @@
-import * as THREE from 'three';
-import type {
-  AnimGraphFile,
-  AnimLayer,
-  AnimState,
-  AnimTransition,
-  TransitionCondition,
-} from './anim-graph-types';
-import { evaluateBlendTree } from './blend-node';
-
-/**
- * Runtime animation graph for a single entity.
- *
- * This is the core custom code that Three.js doesn't provide.
- * Three.js AnimationMixer handles clip playback and crossfading.
- * This adds: state machines, parameter-driven transitions, blend trees.
- *
- * Weight management: all AnimationActions are pre-played at creation with
- * weight 0. Weights are set explicitly every frame — we never use Three.js's
- * fadeIn/fadeOut, which can cause total weight to dip below 1.0 and flash
- * the bind pose (T-pose).
- *
- * Usage:
- *   const graph = new AnimGraph(mixer, graphData, clips);
- *   graph.setParameter('speed', 5.0);
- *   graph.update(dt); // call each frame
- */
-export class AnimGraph {
-  private mixer: THREE.AnimationMixer;
-  private layers: LayerRuntime[] = [];
-  private parameters = new Map<string, number | boolean>();
-  private triggers = new Set<string>();
-
-  constructor(
-    mixer: THREE.AnimationMixer,
-    data: AnimGraphFile,
-    clips: Map<string, THREE.AnimationClip>,
-  ) {
-    this.mixer = mixer;
-
-    // Initialize parameters with defaults
-    for (const [name, param] of Object.entries(data.parameters)) {
-      this.parameters.set(name, param.default);
-    }
-
-    // Create runtime for each layer
-    for (const layerDef of data.layers) {
-      this.layers.push(new LayerRuntime(mixer, layerDef, clips));
-    }
-  }
-
-  /** The names of all declared parameters (for the AnimationAdapter to enumerate). */
-  parameterNames(): string[] {
-    return [...this.parameters.keys()];
-  }
-
-  /** Set a float/int/bool parameter */
-  setParameter(name: string, value: number | boolean) {
-    this.parameters.set(name, value);
-  }
-
-  /** Get a parameter value */
-  getParameter(name: string): number | boolean | undefined {
-    return this.parameters.get(name);
-  }
-
-  /** Fire a trigger (auto-resets after consumed by a transition) */
-  trigger(name: string) {
-    this.triggers.add(name);
-  }
-
-  /** Get the current state name for a layer (default: first layer) */
-  getCurrentState(layerIndex = 0): string {
-    return this.layers[layerIndex]?.currentState ?? '';
-  }
-
-  /** Update the animation graph. Call once per frame. */
-  update(dt: number) {
-    // Triggers persist until a transition actually consumes them — we do NOT
-    // clear every frame. A trigger fired mid-crossfade (when no transition can
-    // fire) survives until the layer is ready to act on it.
-    const consumed = new Set<string>();
-    for (const layer of this.layers) {
-      layer.update(dt, this.parameters, this.triggers, consumed);
-    }
-
-    // Clear only triggers that were consumed by a transition this frame.
-    for (const name of consumed) {
-      this.triggers.delete(name);
-    }
-
-    // Advance the mixer
-    this.mixer.update(dt);
-  }
-}
-
-/**
- * Runtime state for a single animation layer.
- */
-class LayerRuntime {
-  private mixer: THREE.AnimationMixer;
-  private states: Map<string, AnimState>;
-  private transitions: AnimTransition[];
-  private actionMap = new Map<string, THREE.AnimationAction>();
-  currentState: string;
-  private previousState = '';
-  private stateTime = 0;
-  private stateDuration = 0;
-  private transitioning = false;
-  private transitionElapsed = 0;
-  private transitionDuration = 0;
-
-  constructor(
-    mixer: THREE.AnimationMixer,
-    layerDef: AnimLayer,
-    clips: Map<string, THREE.AnimationClip>,
-  ) {
-    this.mixer = mixer;
-    this.states = new Map(Object.entries(layerDef.states));
-    this.transitions = layerDef.transitions;
-    this.currentState = layerDef.defaultState;
-
-    // Collect the (loop, speed) config each clip name is played with. A clip
-    // name is a key into a single shared THREE.AnimationAction (ensureAction
-    // dedupes by name), so two states — or a state and a blend-tree child —
-    // that reference the same clip with different loop/speed would silently
-    // let whichever state was processed first win, and the other's config
-    // would be dropped with no signal. Per-state clip config is deferred
-    // (no real need for it yet) — the correct behavior for now is a loud
-    // error at graph load, not silent last-write-wins.
-    const clipConfigs = new Map<string, { loop: boolean; speed: number; state: string }>();
-    for (const [stateName, state] of this.states) {
-      if (state.clip) {
-        this.registerClipConfig(
-          clipConfigs,
-          state.clip,
-          state.loop ?? true,
-          state.speed ?? 1,
-          stateName,
-        );
-      }
-      if (state.blendTree) {
-        for (const child of state.blendTree.children) {
-          this.registerClipConfig(clipConfigs, child.clip, true, 1, stateName);
-        }
-      }
-    }
-
-    // Create AnimationActions for all referenced clips.
-    // All actions are played immediately at weight 0 — they stay active in the
-    // mixer but contribute nothing visually until we raise their weight.
-    for (const [clipName, config] of clipConfigs) {
-      this.ensureAction(clipName, clips, config.loop, config.speed);
-    }
-
-    // Start default state
-    this.enterState(this.currentState, new Map());
-  }
-
-  /** Record a clip's (loop, speed) config, throwing if a prior state disagrees. */
-  private registerClipConfig(
-    configs: Map<string, { loop: boolean; speed: number; state: string }>,
-    clipName: string,
-    loop: boolean,
-    speed: number,
-    stateName: string,
-  ) {
-    const existing = configs.get(clipName);
-    if (existing && (existing.loop !== loop || existing.speed !== speed)) {
-      throw new Error(
-        `AnimGraph: clip "${clipName}" is configured inconsistently across states — ` +
-          `state "${existing.state}" uses loop=${existing.loop}/speed=${existing.speed}, ` +
-          `but state "${stateName}" uses loop=${loop}/speed=${speed}. ` +
-          `Per-state clip config is not supported: every state (and blend-tree child) that ` +
-          `plays a given clip must agree on its loop/speed.`,
-      );
-    }
-    if (!existing) configs.set(clipName, { loop, speed, state: stateName });
-  }
-
-  private ensureAction(
-    clipName: string,
-    clips: Map<string, THREE.AnimationClip>,
-    loop: boolean,
-    speed: number,
-  ) {
-    if (this.actionMap.has(clipName)) return;
-    const clip = clips.get(clipName);
-    if (!clip) return;
-
-    const action = this.mixer.clipAction(clip);
-    action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
-    action.clampWhenFinished = !loop;
-    action.timeScale = speed;
-    action.setEffectiveWeight(0);
-    action.play();
-    this.actionMap.set(clipName, action);
-  }
-
-  private enterState(stateName: string, parameters: Map<string, number | boolean>) {
-    const state = this.states.get(stateName);
-    if (!state) return;
-
-    this.currentState = stateName;
-    this.stateTime = 0;
-    this.transitioning = false;
-
-    // Zero all, then set the entering state to full weight
-    this.zeroAllWeights();
-
-    if (state.clip) {
-      const action = this.actionMap.get(state.clip);
-      if (action) {
-        action.reset();
-        action.setEffectiveWeight(1);
-        action.play();
-        this.stateDuration = action.getClip().duration;
-      }
-    }
-
-    if (state.blendTree) {
-      const weights = evaluateBlendTree(state.blendTree, parameters);
-      this.setWeights(weights, 1);
-      const heaviest = weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
-      const action = this.actionMap.get(heaviest.clip);
-      this.stateDuration = action?.getClip().duration ?? 1;
-    }
-  }
-
-  /** Zero all action weights. */
-  private zeroAllWeights() {
-    for (const action of this.actionMap.values()) {
-      action.setEffectiveWeight(0);
-    }
-  }
-
-  /** Set weights for a list of clip/weight pairs, multiplied by a scale factor. */
-  private setWeights(weights: { clip: string; weight: number }[], scale: number) {
-    for (const { clip, weight } of weights) {
-      const action = this.actionMap.get(clip);
-      if (action) {
-        action.setEffectiveWeight(weight * scale);
-      }
-    }
-  }
-
-  /** Get the weight list for a state (single clip at weight 1, or blend tree evaluated). */
-  private getStateWeights(
-    stateName: string,
-    parameters: Map<string, number | boolean>,
-  ): { clip: string; weight: number }[] {
-    const state = this.states.get(stateName);
-    if (!state) return [];
-    if (state.clip) return [{ clip: state.clip, weight: 1 }];
-    if (state.blendTree) return evaluateBlendTree(state.blendTree, parameters);
-    return [];
-  }
-
-  update(
-    dt: number,
-    parameters: Map<string, number | boolean>,
-    triggers: Set<string>,
-    consumed: Set<string>,
-  ) {
-    this.stateTime += dt;
-    const normalizedTime = this.stateDuration > 0 ? this.stateTime / this.stateDuration : 1;
-
-    // Zero all weights, then set them based on current (and previous) state.
-    // This guarantees total weight = 1.0 every frame — no bind-pose bleed.
-    this.zeroAllWeights();
-
-    if (this.transitioning) {
-      this.transitionElapsed += dt;
-      const alpha = Math.min(this.transitionElapsed / this.transitionDuration, 1);
-
-      // Crossfade: outgoing * (1 - alpha) + incoming * alpha — sums to exactly 1.0
-      this.setWeights(this.getStateWeights(this.previousState, parameters), 1 - alpha);
-      this.setWeights(this.getStateWeights(this.currentState, parameters), alpha);
-
-      if (alpha >= 1) {
-        this.transitioning = false;
-      }
-      return;
-    }
-
-    // Not transitioning — current state at full weight
-    this.setWeights(this.getStateWeights(this.currentState, parameters), 1);
-
-    // Check transitions
-    for (const transition of this.transitions) {
-      // Match: exact state or wildcard
-      if (transition.from !== '*' && transition.from !== this.currentState) continue;
-      // A wildcard transition must never re-enter the state we're already in —
-      // otherwise a wildcard whose condition stays true fires every single
-      // frame (performTransition resets the action to time 0 each time), so
-      // the state is "entered" over and over and its animation never advances
-      // past frame 0. An explicit from:X→to:X self-transition is a deliberate
-      // restart and is allowed to fire.
-      if (transition.from === '*' && transition.to === this.currentState) continue;
-
-      // Check exit time
-      if (transition.exitTime !== undefined && normalizedTime < transition.exitTime) continue;
-
-      // Check conditions
-      if (
-        transition.conditions &&
-        !this.checkConditions(transition.conditions, parameters, triggers)
-      ) {
-        continue;
-      }
-
-      // Transition! Mark any trigger conditions as consumed so the graph
-      // clears them after all layers have had a chance to react this frame.
-      if (transition.conditions) {
-        for (const cond of transition.conditions) {
-          if (cond.op === 'trigger') consumed.add(cond.param);
-        }
-      }
-      this.performTransition(transition, parameters);
-      return;
-    }
-  }
-
-  private checkConditions(
-    conditions: TransitionCondition[],
-    parameters: Map<string, number | boolean>,
-    triggers: Set<string>,
-  ): boolean {
-    for (const cond of conditions) {
-      if (cond.op === 'trigger') {
-        if (!triggers.has(cond.param)) return false;
-        continue;
-      }
-
-      const paramVal = parameters.get(cond.param);
-      if (paramVal === undefined) return false;
-
-      const a = Number(paramVal);
-      const b = Number(cond.value ?? 0);
-
-      switch (cond.op) {
-        case '>':
-          if (!(a > b)) return false;
-          break;
-        case '<':
-          if (!(a < b)) return false;
-          break;
-        case '>=':
-          if (!(a >= b)) return false;
-          break;
-        case '<=':
-          if (!(a <= b)) return false;
-          break;
-        case '==':
-          if (paramVal !== cond.value && a !== b) return false;
-          break;
-        case '!=':
-          if (paramVal === cond.value || a === b) return false;
-          break;
-      }
-    }
-    return true;
-  }
-
-  private performTransition(transition: AnimTransition, parameters: Map<string, number | boolean>) {
-    const toState = this.states.get(transition.to);
-    if (!toState) return;
-
-    this.previousState = this.currentState;
-    this.currentState = transition.to;
-    this.stateTime = 0;
-    this.transitioning = true;
-    this.transitionElapsed = 0;
-    this.transitionDuration = transition.duration;
-
-    // Reset incoming actions to time=0 so they start fresh.
-    // No fadeIn/fadeOut — weights are managed explicitly in update().
-    if (toState.clip) {
-      const action = this.actionMap.get(toState.clip);
-      if (action) {
-        action.reset();
-        action.play();
-      }
-    }
-    if (toState.blendTree) {
-      for (const child of toState.blendTree.children) {
-        const action = this.actionMap.get(child.clip);
-        if (action) {
-          action.reset();
-          action.play();
-        }
-      }
-    }
-
-    // Estimate state duration for exitTime calculations
-    if (toState.clip) {
-      const action = this.actionMap.get(toState.clip);
-      this.stateDuration = action?.getClip().duration ?? 1;
-    } else if (toState.blendTree) {
-      const weights = evaluateBlendTree(toState.blendTree, parameters);
-      const heaviest = weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
-      const action = this.actionMap.get(heaviest.clip);
-      this.stateDuration = action?.getClip().duration ?? 1;
-    }
-  }
-}

package/src/animation/anim-system.ts

@@ -1,28 +0,0 @@
-import type * as THREE from 'three';
-import type { AnimGraph } from './anim-graph';
-
-/**
- * Registry of active animation graphs, keyed by Object3D (the entity).
- *
- * AnimGraph wraps a THREE.AnimationMixer (a class instance), so it can't live in
- * a flat data store — we keep a simple Map<Object3D, AnimGraph> and update each
- * one every frame. Each runtime owns its own map (see createGameRuntime) so that
- * multiple concurrent runtimes never cross-contaminate each other's graphs.
- *
- * Usage:
- *   const animGraphs: AnimGraphMap = new Map();
- *   animGraphs.set(playerObject3D, new AnimGraph(mixer, data, clips));
- *   // In system runner:
- *   systems.add('animation', (dt) => animationSystem(animGraphs, dt));
- */
-export type AnimGraphMap = Map<THREE.Object3D, AnimGraph>;
-
-/**
- * Updates all active animation graphs.
- * Call this in the ANIMATION phase.
- */
-export function animationSystem(graphs: AnimGraphMap, dt: number) {
-  for (const graph of graphs.values()) {
-    graph.update(dt);
-  }
-}