@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/ecs/game-component.ts

@@ -4,30 +4,30 @@ import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import type { z } from 'zod';
 import type { SystemPhaseName } from '../core/types';
-import type { WorldInstance, WorldKind } from '../runtime/game';
+import type { AdapterSurface, WorldInstance } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
 
 /**
- * Map a {@link WorldKind} to its native world node type (T7.2, D8 —
+ * Map a {@link AdapterSurface} to its native world node type (T7.2, D8 —
  * `docs/GAME-COMPONENT-GENERALIZATION.md` §2). `react` maps to `never`: react
  * entities host no GameComponents (they render from game state via the T7.4
  * state bridge instead).
  */
-export type NodeOf<K extends WorldKind> = K extends 'threejs'
+export type NodeOf<K extends AdapterSurface> = K extends 'threejs'
   ? THREE.Object3D
   : K extends 'pixijs'
     ? PIXI.Container
     : never;
 
-/** Map a {@link WorldKind} to its native Rapier rigid-body type. */
-export type BodyOf<K extends WorldKind> = K extends 'threejs'
+/** Map a {@link AdapterSurface} to its native Rapier rigid-body type. */
+export type BodyOf<K extends AdapterSurface> = K extends 'threejs'
   ? RAPIER3D.RigidBody
   : K extends 'pixijs'
     ? RAPIER2D.RigidBody
     : never;
 
-/** Map a {@link WorldKind} to its native Rapier collider type. */
-export type ColliderOf<K extends WorldKind> = K extends 'threejs'
+/** Map a {@link AdapterSurface} to its native Rapier collider type. */
+export type ColliderOf<K extends AdapterSurface> = K extends 'threejs'
   ? RAPIER3D.Collider
   : K extends 'pixijs'
     ? RAPIER2D.Collider
@@ -54,13 +54,97 @@ export type ColliderOf<K extends WorldKind> = K extends 'threejs'
  * State lives on `this` (instance properties). On HMR, the engine swaps the
  * prototype via Object.setPrototypeOf — instance state survives, method bodies
  * update to the new code.
+ *
+ * `update` is deliberately mandatory, not optional like `init`/`dispose`
+ * (owner decision, issue #101): components are for BEHAVIOR. If your
+ * subclass's `update(dt, ctx)` body is empty, that is a signal the class may
+ * not need to be a component at all — a plain state-holder with only
+ * `init`/event methods (score/hits counters, etc.) usually belongs as a
+ * plain object or a static-scenery/UI object instead (see the "GameComponents
+ * are for things with behavior only" rule).
+ */
+/**
+ * Cross-copy brand (`Symbol.for` is process-global, so every physical copy of
+ * the engine shares ONE symbol): `x.prototype instanceof GameComponent` is
+ * FALSE when a project resolves TWO copies of the engine at once — the
+ * published `@vgai/engine/*` subpaths next to the `@engine/*` source alias,
+ * exactly what a scaffolded project's node-side scripts do (meteor-dodge
+ * dry-run friction: `validate-scenes --components` reported every field of a
+ * pristine scaffold's `SceneCamera` as unknown). Structural checks
+ * (`isGameComponentClass`) test this brand as well as `instanceof`.
  */
-export abstract class GameComponent<K extends WorldKind = 'threejs'> {
+export const GAME_COMPONENT_BRAND = Symbol.for('vgai.GameComponent');
+
+/**
+ * HMR class lineage. A true component hot-swap deliberately replaces a live
+ * instance's prototype with the newly imported class, but other already-live
+ * project modules can still hold the previous class object. Native
+ * `instanceof PreviousClass` would then become false even though the object is
+ * still the same component under the same hot-reload lineage. That broke both
+ * ordinary trigger guards (`component instanceof PlayerController`) and the
+ * canonical React-state selector (`game.queryByComponent(PlayerController)`).
+ *
+ * Keep this as class-to-class lineage rather than a string/name registry:
+ * minified classes, aliases, and two unrelated components with the same name
+ * remain distinct. The WeakMap owns no game/entity state and introduces no
+ * second identity model; it records only the exact constructor pairs the
+ * existing HMR boundary has actually swapped.
+ */
+type HmrComponentConstructor = abstract new (...args: never[]) => object;
+
+const hmrLineages = new WeakMap<HmrComponentConstructor, Set<HmrComponentConstructor>>();
+
+/** @internal Called only by ComponentManager's successful HMR swap path. */
+export function linkGameComponentHmrClasses(
+  previous: HmrComponentConstructor,
+  next: HmrComponentConstructor,
+): void {
+  const previousLineage = hmrLineages.get(previous);
+  const nextLineage = hmrLineages.get(next);
+  const merged = new Set<HmrComponentConstructor>([previous, next]);
+  if (previousLineage) {
+    for (const member of previousLineage) merged.add(member);
+  }
+  if (nextLineage) {
+    for (const member of nextLineage) merged.add(member);
+  }
+  for (const member of merged) hmrLineages.set(member, merged);
+}
+
+function classesShareHmrLineage(a: HmrComponentConstructor, b: HmrComponentConstructor): boolean {
+  return a === b || hmrLineages.get(a)?.has(b) === true;
+}
+
+export abstract class GameComponent<K extends AdapterSurface = 'threejs'> {
   /** Which phase this component's update runs in. Override in subclasses. */
   static phase: SystemPhaseName = 'gameLogic';
 
+  /** See {@link GAME_COMPONENT_BRAND} — inherited by every subclass. */
+  static readonly [GAME_COMPONENT_BRAND] = true;
+
+  /**
+   * Preserve ordinary JavaScript `instanceof` across a true HMR prototype
+   * swap. Subclasses inherit this static hook, so `value instanceof
+   * PlayerController` first performs the native prototype-chain check and,
+   * only when that fails, accepts an exact constructor lineage previously
+   * linked by ComponentManager.hotSwap(). Non-HMR values retain byte-for-byte
+   * native semantics.
+   */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    // biome-ignore lint/complexity/noThisInStatic: Symbol.hasInstance is inherited; `this` must be the queried subclass, not the GameComponent base.
+    const expected = this as HmrComponentConstructor;
+    const nativeMatch = Function.prototype[Symbol.hasInstance].call(expected, value) as boolean;
+    if (nativeMatch) return true;
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return false;
+    const actual = (value as { constructor?: unknown }).constructor;
+    return (
+      typeof actual === 'function' &&
+      classesShareHmrLineage(expected, actual as HmrComponentConstructor)
+    );
+  }
+
   /**
-   * Runtime-checkable declaration of which {@link WorldKind} this component
+   * Runtime-checkable declaration of which {@link AdapterSurface} this component
    * is written for (T7.2, D8 §3 — `docs/GAME-COMPONENT-GENERALIZATION.md`).
    * TS's `K` type parameter is erased at runtime, so this static is what the
    * ComponentManager checks at attach time: a node whose world's kind
@@ -71,7 +155,7 @@ export abstract class GameComponent<K extends WorldKind = 'threejs'> {
    * any world components are legal in (every world except `'react'`, which
    * always throws regardless of `declaredKind` — see the ComponentManager).
    */
-  static declaredKind: WorldKind | 'any' = 'threejs';
+  static declaredKind: AdapterSurface | 'any' = 'threejs';
 
   /**
    * Optional Zod object schema for this component's authored fields. When set,
@@ -88,7 +172,7 @@ export abstract class GameComponent<K extends WorldKind = 'threejs'> {
   world!: WorldInstance;
 
   /**
-   * Typed accessor, threejs worlds only — kept for compatibility. On a
+   * Typed accessor, threejs roots only — kept for compatibility. On a
    * `GameComponent` (default `K`) this types as `THREE.Object3D`, so every
    * existing component compiles unchanged. On a non-threejs instance it
    * THROWS a descriptive error rather than ever returning a wrong-kind node —

package/src/humanoid/bake.operation.ts

@@ -0,0 +1,326 @@
+/**
+ * Package-contributed Project Command for baking the procedural humanoid into
+ * ordinary project assets. The editor discovers this module through
+ * @vgai/engine's package.json; the editor itself contains no humanoid branch.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { z } from 'zod';
+import { createHumanoidClipLibrary, retargetClipToHumanoid } from './clips';
+import { generateHumanoid } from './generate';
+import { HumanoidParamsSchema } from './schema';
+
+const InputSchema = z.object({
+  name: z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-_]{0,63}$/)
+    .default('humanoid')
+    .describe(
+      'Stable lowercase asset name used for the generated GLB, prefab, and provenance files.',
+    ),
+  params: HumanoidParamsSchema.default(HumanoidParamsSchema.parse({})).describe(
+    'Procedural body proportions.',
+  ),
+  clipSource: z
+    .string()
+    .optional()
+    .describe(
+      'Optional project-public GLB path containing Mixamo-named clips. When supplied, Idle, Walk, and Run are retargeted and baked into the generated humanoid GLB.',
+    ),
+  clipNames: z
+    .array(z.string())
+    .min(1)
+    .default(['Idle', 'Walk', 'Run'])
+    .describe('Exact standard clip names to retarget from clipSource.'),
+  dryRun: z
+    .boolean()
+    .default(false)
+    .describe('Generate and validate the complete output batch without writing project files.'),
+});
+
+const OutputFileSchema = z.object({
+  path: z.string(),
+  bytes: z.number(),
+  mediaType: z.string().optional(),
+  role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
+});
+
+const ResultSchema = z.object({
+  model: z.string(),
+  prefab: z.string(),
+  provenance: z.string(),
+  vertexCount: z.number(),
+  clips: z.array(z.string()),
+  files: z.array(OutputFileSchema),
+  totalBytes: z.number(),
+  dryRun: z.boolean(),
+});
+
+interface OutputWriter {
+  write(
+    files: ReadonlyArray<{
+      path: string;
+      content: string | Uint8Array;
+      mediaType?: string;
+      role?: 'asset' | 'prefab' | 'provenance' | 'other';
+    }>,
+    options?: { dryRun?: boolean },
+  ): Promise<{
+    files: z.infer<typeof OutputFileSchema>[];
+    totalBytes: number;
+    dryRun: boolean;
+  }>;
+}
+
+interface ProjectOperationContext {
+  projectRoot?: string;
+  projectOutputs?: OutputWriter;
+  signal?: AbortSignal;
+}
+
+const NODE_THREE_POLYFILL_KEYS = [
+  'self',
+  'ProgressEvent',
+  'createImageBitmap',
+  'FileReader',
+] as const;
+let nodeThreePolyfillDepth = 0;
+let nodeThreePreviousDescriptors: Record<
+  (typeof NODE_THREE_POLYFILL_KEYS)[number],
+  PropertyDescriptor | undefined
+> | null = null;
+
+/**
+ * Three's official GLTFLoader/GLTFExporter addons expect a small browser API
+ * surface even when invoked by this declared Node-only project operation.
+ * Install that surface for the duration of overlapping bakes and restore the
+ * editor-server process exactly when the last caller releases it.
+ */
+function installNodeThreePolyfills(): () => void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  if (nodeThreePolyfillDepth === 0) {
+    nodeThreePreviousDescriptors = Object.fromEntries(
+      NODE_THREE_POLYFILL_KEYS.map((key) => [key, Object.getOwnPropertyDescriptor(target, key)]),
+    ) as NonNullable<typeof nodeThreePreviousDescriptors>;
+    if (!target['self']) target['self'] = globalThis;
+    if (!target['ProgressEvent']) {
+      target['ProgressEvent'] = class {
+        readonly type: string;
+        constructor(type: string, init: Record<string, unknown> = {}) {
+          this.type = type;
+          Object.assign(this, init);
+        }
+      };
+    }
+    if (!target['createImageBitmap']) {
+      target['createImageBitmap'] = async () => ({ close() {} });
+    }
+    if (!target['FileReader']) {
+      target['FileReader'] = class {
+        result: string | ArrayBuffer | null = null;
+        onloadend: (() => void) | null = null;
+        readAsArrayBuffer(blob: Blob): void {
+          void blob.arrayBuffer().then((value) => {
+            this.result = value;
+            this.onloadend?.();
+          });
+        }
+        readAsDataURL(blob: Blob): void {
+          void blob.arrayBuffer().then((value) => {
+            this.result = `data:${blob.type || 'application/octet-stream'};base64,${Buffer.from(value).toString('base64')}`;
+            this.onloadend?.();
+          });
+        }
+      };
+    }
+  }
+  nodeThreePolyfillDepth++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    nodeThreePolyfillDepth--;
+    if (nodeThreePolyfillDepth !== 0 || !nodeThreePreviousDescriptors) return;
+    for (const key of NODE_THREE_POLYFILL_KEYS) {
+      const descriptor = nodeThreePreviousDescriptors[key];
+      if (descriptor) Object.defineProperty(target, key, descriptor);
+      else delete target[key];
+    }
+    nodeThreePreviousDescriptors = null;
+  };
+}
+
+async function resolvePublicFile(projectRoot: string, path: string): Promise<string> {
+  const relativePath = path.replace(/^\//, '');
+  const publicRoot = await realpath(resolve(projectRoot, 'public'));
+  const candidate = await realpath(resolve(publicRoot, relativePath));
+  if (candidate !== publicRoot && !candidate.startsWith(`${publicRoot}${sep}`)) {
+    throw new Error(`clipSource must resolve inside the project's public/ directory: ${path}`);
+  }
+  return candidate;
+}
+
+async function loadRetargetedClips(
+  projectRoot: string,
+  sourcePath: string,
+  names: string[],
+  rig: ReturnType<typeof generateHumanoid>,
+) {
+  const releasePolyfills = installNodeThreePolyfills();
+  try {
+    const absolute = await resolvePublicFile(projectRoot, sourcePath);
+    const bytes = await readFile(absolute);
+    const arrayBuffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const gltf = await new GLTFLoader().parseAsync(arrayBuffer, `${dirname(absolute)}${sep}`);
+    const library = createHumanoidClipLibrary(gltf.animations);
+    const clips = names.map((name) => {
+      const clip = retargetClipToHumanoid(library.get(name), rig);
+      clip.name = name;
+      return clip;
+    });
+    gltf.scene.traverse((object) => {
+      const mesh = object as typeof object & {
+        geometry?: { dispose(): void };
+        material?: { dispose(): void } | Array<{ dispose(): void }>;
+      };
+      mesh.geometry?.dispose();
+      for (const material of Array.isArray(mesh.material)
+        ? mesh.material
+        : mesh.material
+          ? [mesh.material]
+          : []) {
+        material.dispose();
+      }
+    });
+    return { clips, sourceSha256: createHash('sha256').update(bytes).digest('hex') };
+  } finally {
+    releasePolyfills();
+  }
+}
+
+async function exportGlb(
+  root: ReturnType<typeof generateHumanoid>['root'],
+  animations: Awaited<ReturnType<typeof loadRetargetedClips>>['clips'],
+): Promise<Uint8Array> {
+  const releasePolyfills = installNodeThreePolyfills();
+  try {
+    const result = await new Promise<ArrayBuffer>((resolveResult, reject) => {
+      new GLTFExporter().parse(
+        root,
+        (value) => {
+          if (value instanceof ArrayBuffer) resolveResult(value);
+          else reject(new Error('GLTFExporter returned JSON while binary output was requested.'));
+        },
+        reject,
+        {
+          binary: true,
+          animations,
+          onlyVisible: false,
+        },
+      );
+    });
+    return new Uint8Array(result);
+  } finally {
+    releasePolyfills();
+  }
+}
+
+export const operation = {
+  name: 'project.humanoid.bake',
+  summary: 'Bake a procedural humanoid into an ordinary GLB asset and prefab.',
+  description:
+    'Generates VGAI’s skinned procedural humanoid from body parameters. Optionally retargets ' +
+    'Mixamo-named clips from a project-public GLB, then atomically writes the generated GLB, ' +
+    'a normal .prefab.json referencing it, and reproducibility provenance. Use the prefab as ' +
+    'the authored scene object; do not regenerate the visible body every gameplay run. The ' +
+    'baked body keeps the multicolored engineering-reference material: it is not a styled ' +
+    'production character. A prominent player character should receive an intentional, ' +
+    'project-owned material/composition treatment unless that reference look is deliberate.',
+  input: InputSchema,
+  result: ResultSchema,
+  errors: [],
+  requires: { project: true },
+  host: 'node' as const,
+  mutates: true,
+  supportsDryRun: true,
+  longRunning: true,
+  permission: {
+    risk: 'write' as const,
+    summary: 'Writes or replaces generated model, prefab, and provenance files under public/.',
+  },
+  async impl(input: z.infer<typeof InputSchema>, ctx: ProjectOperationContext) {
+    if (!ctx.projectRoot || !ctx.projectOutputs) {
+      throw new Error('project.humanoid.bake requires a project root and generated-output writer.');
+    }
+    if (ctx.signal?.aborted) throw new Error('project.humanoid.bake was cancelled.');
+
+    const rig = generateHumanoid(input.params);
+    try {
+      const loaded = input.clipSource
+        ? await loadRetargetedClips(ctx.projectRoot, input.clipSource, input.clipNames, rig)
+        : { clips: [], sourceSha256: null };
+      const glb = await exportGlb(rig.root, loaded.clips);
+      const base = input.name;
+      const model = `public/models/generated/${base}.glb`;
+      const prefab = `public/prefabs/generated/${base}.prefab.json`;
+      const provenance = `public/models/generated/${base}.provenance.json`;
+      const modelUrl = `/models/generated/${base}.glb`;
+      const prefabDocument = {
+        version: 1,
+        name: base,
+        root: {
+          name: base,
+          mesh: { type: 'gltf', src: modelUrl },
+          ...(loaded.clips.length > 0 ? { animation: {} } : {}),
+          shadow: { enabled: true },
+        },
+      };
+      const provenanceDocument = {
+        version: 1,
+        generator: '@vgai/engine:project.humanoid.bake',
+        params: rig.params,
+        clipSource: input.clipSource ?? null,
+        clipSourceSha256: loaded.sourceSha256,
+        clips: loaded.clips.map((clip) => clip.name),
+        modelSha256: createHash('sha256').update(glb).digest('hex'),
+      };
+      const output = await ctx.projectOutputs.write(
+        [
+          {
+            path: model,
+            content: glb,
+            mediaType: 'model/gltf-binary',
+            role: 'asset',
+          },
+          {
+            path: prefab,
+            content: `${JSON.stringify(prefabDocument, null, 2)}\n`,
+            mediaType: 'application/json',
+            role: 'prefab',
+          },
+          {
+            path: provenance,
+            content: `${JSON.stringify(provenanceDocument, null, 2)}\n`,
+            mediaType: 'application/json',
+            role: 'provenance',
+          },
+        ],
+        { dryRun: input.dryRun },
+      );
+      return {
+        model,
+        prefab,
+        provenance,
+        vertexCount: rig.vertexCount,
+        clips: loaded.clips.map((clip) => clip.name),
+        ...output,
+      };
+    } finally {
+      rig.dispose();
+    }
+  },
+};