@vgai/engine 0.4.0 → 0.4.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "The vgai game engine — core loop, GameComponent model, physics, scene loader, adapter seam.",
   "homepage": "https://github.com/volter-ai/vgai-engine#readme",
@@ -15,8 +15,18 @@
     "access": "public"
   },
   "vgai": {
-    "operations": [
-      "./src/humanoid/bake.operation.ts"
+    "tools": [
+      {
+        "entry": "./tools/humanoid-bake.tool.ts",
+        "contributions": [
+          {
+            "id": "humanoid-builder",
+            "point": "workspace.document",
+            "title": "Humanoid Builder",
+            "entry": "./src/react/humanoid-bake.document.tsx"
+          }
+        ]
+      }
     ]
   },
   "exports": {
@@ -26,6 +36,7 @@
   },
   "files": [
     "src",
+    "tools",
     "dist",
     "schemas"
   ],
@@ -55,10 +66,14 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@vgai/editor-sdk": "*",
     "react": ">=18",
     "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
+    "@vgai/editor-sdk": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },

package/src/adapter/vgai-scene-game-adapter.ts

@@ -32,6 +32,7 @@ import { createTransformWriter } from '../physics/transform-writer';
 import { createTriggerDispatch } from '../physics/trigger-dispatch';
 import { RenderBatchSystem } from '../render/render-batch-system';
 import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
+import { type ViewportShadingMode, ViewportShadingRenderer } from '../render/viewport-shading';
 import {
   createDebugRegistry,
   type DebugRegistry,
@@ -53,11 +54,7 @@ import { hasUserData, setUserData } from '../scene/user-data';
 import { type AudioContext as GameAudio, setupAudio } from '../setup/setup-audio';
 import { setupParticles } from '../setup/setup-particles';
 import { setupPhysics, updatePhysicsDebug } from '../setup/setup-physics';
-import {
-  applyRendererSettings,
-  applyScenePostProcessing,
-  createSceneView,
-} from '../setup/setup-renderer';
+import { applySceneRenderPipeline, createSceneView } from '../setup/setup-renderer';
 import {
   createAudioSystemAdapter,
   createInputManagerAdapter,
@@ -120,6 +117,8 @@ export interface VgaiMountedGame extends MountedGame {
   readonly firstParty: true;
   readonly ctx: GameContext;
   readonly composer: EffectComposer | null;
+  /** Render-only developer view; native game materials are restored before the frame returns. */
+  setViewportShadingMode(mode: ViewportShadingMode): void;
   /** Warm-restart: dispose the current game, re-run a new setup on the same ctx. */
   hotReload(newSetup: GameSetupFn, editorPreview?: EditorPreview): Promise<void>;
   /**
@@ -231,6 +230,8 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       !headless && rendererContext && typeof rendererContext.getExtension === 'function'
         ? createWebGLGpuTimer(rendererContext)
         : null;
+    const viewportShading = new ViewportShadingRenderer();
+    let viewportShadingMode: ViewportShadingMode = 'solid';
 
     // --- System runner (engine-level systems) ---
     const systems = createSystemRunner(host.game?.profiler.systemObserver, 'threejs');
@@ -274,7 +275,15 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         (dt) => {
           if (host.game?.profiler.enabled) gpuTimer?.begin();
           try {
-            composer.render(dt);
+            viewportShading.render(
+              scene,
+              viewportShadingMode,
+              () => composer.render(dt),
+              // Scene authoring can temporarily attach editor infrastructure
+              // (gizmos/helpers on their own layer) to this same native scene.
+              // Only replace materials the actual game camera can render.
+              (mesh) => camera.layers.test(mesh.layers),
+            );
           } finally {
             gpuTimer?.end();
           }
@@ -489,13 +498,9 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       if (headless) return;
       const scope = inst.environment?.rendering as RenderScope | undefined;
       const settings = resolveRenderSettings(scope);
-      // live renderer settings (shadows, resolution scale)
-      applyRendererSettings(renderer, scope);
-      // post-processing master switch: (re)build when the scene defines effects OR
-      // the master is off (to strip the default bloom pass down to a plain scene).
-      if (inst.environment?.postProcessing || !settings['postProcessing']) {
-        applyScenePostProcessing(composer, renderer, scene, camera, inst.environment);
-      }
+      // Always apply the whole authored scene pipeline. Tone mapping is an
+      // authored setting even when the scene has no post-processing effects.
+      applySceneRenderPipeline(composer, renderer, scene, camera, inst.environment);
       // transparent batching: collapse static/mover meshes sharing a signature
       if (settings['autoBatch']) {
         batchSystem = new RenderBatchSystem(scene, settings);
@@ -701,6 +706,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       }
       safeStep('input.dispose', () => input.dispose());
       safeStep('gpuTimer.dispose', () => gpuTimer?.dispose());
+      safeStep('viewportShading.dispose', () => viewportShading.dispose());
     };
 
     const hotReload = async (
@@ -820,6 +826,9 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       systems: systemAdapters,
       ctx,
       composer: headless ? null : composer,
+      setViewportShadingMode: (mode) => {
+        viewportShadingMode = mode;
+      },
       hotReload,
       frame: {
         runPhase: (phase, dt) => systems.runPhase(phase, dt),

package/src/react/humanoid-bake.document.tsx

@@ -0,0 +1,337 @@
+import type { ToolContributionProps } from '@vgai/editor-sdk/contributions';
+import { useState } from 'react';
+
+type ProportionKey =
+  | 'legLength'
+  | 'armLength'
+  | 'torsoLength'
+  | 'shoulderWidth'
+  | 'hipWidth'
+  | 'headSize'
+  | 'limbThickness'
+  | 'torsoGirth';
+
+const PROPORTIONS: ReadonlyArray<{
+  key: ProportionKey;
+  label: string;
+  min: number;
+  max: number;
+  hint: string;
+}> = [
+  { key: 'legLength', label: 'Leg length', min: 0.5, max: 2, hint: 'Hip height and stride' },
+  { key: 'armLength', label: 'Arm length', min: 0.5, max: 2, hint: 'Upper arm and forearm' },
+  { key: 'torsoLength', label: 'Torso length', min: 0.5, max: 2, hint: 'Spine and neck' },
+  { key: 'shoulderWidth', label: 'Shoulder width', min: 0.5, max: 2, hint: 'Clavicle breadth' },
+  { key: 'hipWidth', label: 'Hip width', min: 0.5, max: 2, hint: 'Pelvis breadth' },
+  { key: 'headSize', label: 'Head size', min: 0.5, max: 2, hint: 'Head and neck scale' },
+  { key: 'limbThickness', label: 'Limb thickness', min: 0.4, max: 2.5, hint: 'Arm and leg build' },
+  { key: 'torsoGirth', label: 'Torso girth', min: 0.4, max: 2.5, hint: 'Torso and pelvis build' },
+];
+
+const initialProportions: Record<ProportionKey, number> = {
+  legLength: 1,
+  armLength: 1,
+  torsoLength: 1,
+  shoulderWidth: 1,
+  hipWidth: 1,
+  headSize: 1,
+  limbThickness: 1,
+  torsoGirth: 1,
+};
+
+type Outcome = Awaited<ReturnType<ToolContributionProps['client']['runProjectTool']>>;
+
+function SliderRow({
+  definition,
+  value,
+  onChange,
+}: {
+  definition: (typeof PROPORTIONS)[number];
+  value: number;
+  onChange(value: number): void;
+}) {
+  return (
+    <label style={sliderRowStyle}>
+      <span>
+        <strong style={{ display: 'block', fontSize: 12 }}>{definition.label}</strong>
+        <span style={hintStyle}>{definition.hint}</span>
+      </span>
+      <input
+        type="range"
+        min={definition.min}
+        max={definition.max}
+        step={0.01}
+        value={value}
+        onChange={(event) => onChange(Number(event.target.value))}
+        style={{ width: '100%', accentColor: 'var(--vgai-accent)' }}
+      />
+      <input
+        className="vgai-input"
+        type="number"
+        min={definition.min}
+        max={definition.max}
+        step={0.01}
+        value={value}
+        onChange={(event) => onChange(Number(event.target.value))}
+        style={numberStyle}
+      />
+    </label>
+  );
+}
+
+export default function HumanoidBuilder({ tool, client }: ToolContributionProps) {
+  const [name, setName] = useState('humanoid');
+  const [height, setHeight] = useState('');
+  const [proportions, setProportions] = useState<Record<ProportionKey, number>>(initialProportions);
+  const [clipSource, setClipSource] = useState('');
+  const [clipNames, setClipNames] = useState('Idle, Walk, Run');
+  const [running, setRunning] = useState<'validate' | 'bake' | null>(null);
+  const [outcome, setOutcome] = useState<Outcome | null>(null);
+
+  const run = async (dryRun: boolean) => {
+    setRunning(dryRun ? 'validate' : 'bake');
+    setOutcome(null);
+    try {
+      const params: Record<string, number> = { ...proportions };
+      if (height.trim() !== '') params['height'] = Number(height);
+      setOutcome(
+        await client.runProjectTool(
+          tool.name,
+          {
+            name,
+            params,
+            ...(clipSource.trim() ? { clipSource: clipSource.trim() } : {}),
+            clipNames: clipNames
+              .split(',')
+              .map((item) => item.trim())
+              .filter(Boolean),
+            dryRun,
+          },
+          { confirm: true },
+        ),
+      );
+    } finally {
+      setRunning(null);
+    }
+  };
+
+  const result = outcome?.ok ? (outcome.data as Record<string, unknown>) : null;
+
+  return (
+    <main style={rootStyle} data-testid="humanoid-builder">
+      <header style={{ marginBottom: 22 }}>
+        <div style={eyebrowStyle}>@vgai/engine contribution</div>
+        <h2 style={{ margin: '8px 0 4px', fontSize: 22 }}>Humanoid Builder</h2>
+        <p style={{ ...hintStyle, maxWidth: 740, lineHeight: 1.5 }}>
+          Shape a reusable skinned humanoid, optionally bake standard clips, then add the generated
+          prefab to a scene. The reference material is intentionally diagnostic—not a finished
+          character style.
+        </p>
+      </header>
+
+      <div style={columnsStyle}>
+        <section style={panelStyle}>
+          <h3 style={sectionHeadingStyle}>Asset</h3>
+          <label style={fieldStyle}>
+            <span style={fieldLabelStyle}>Asset name</span>
+            <input
+              className="vgai-input"
+              value={name}
+              onChange={(event) => setName(event.target.value)}
+              style={inputStyle}
+            />
+            <span style={hintStyle}>Lowercase filename used for the GLB and prefab.</span>
+          </label>
+          <label style={fieldStyle}>
+            <span style={fieldLabelStyle}>Standing height</span>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+              <input
+                className="vgai-input"
+                type="number"
+                min={0.3}
+                max={4}
+                step={0.01}
+                value={height}
+                placeholder="Natural"
+                onChange={(event) => setHeight(event.target.value)}
+                style={{ ...inputStyle, flex: 1 }}
+              />
+              <span style={hintStyle}>metres</span>
+            </div>
+            <span style={hintStyle}>Leave blank to use the proportions’ natural height.</span>
+          </label>
+
+          <h3 style={{ ...sectionHeadingStyle, marginTop: 24 }}>Animation</h3>
+          <label style={fieldStyle}>
+            <span style={fieldLabelStyle}>Clip source</span>
+            <input
+              className="vgai-input"
+              value={clipSource}
+              placeholder="/models/animations.glb (optional)"
+              onChange={(event) => setClipSource(event.target.value)}
+              style={inputStyle}
+            />
+            <span style={hintStyle}>A GLB inside this project’s public/ directory.</span>
+          </label>
+          <label style={fieldStyle}>
+            <span style={fieldLabelStyle}>Clips to bake</span>
+            <input
+              className="vgai-input"
+              value={clipNames}
+              onChange={(event) => setClipNames(event.target.value)}
+              style={inputStyle}
+            />
+            <span style={hintStyle}>Comma-separated exact clip names.</span>
+          </label>
+        </section>
+
+        <section style={panelStyle}>
+          <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
+            <h3 style={sectionHeadingStyle}>Body proportions</h3>
+            <button
+              className="vgai-btn"
+              data-variant="ghost"
+              data-size="compact"
+              type="button"
+              onClick={() => setProportions(initialProportions)}
+            >
+              Reset
+            </button>
+          </div>
+          <div style={{ display: 'grid', gap: 11 }}>
+            {PROPORTIONS.map((definition) => (
+              <SliderRow
+                key={definition.key}
+                definition={definition}
+                value={proportions[definition.key]}
+                onChange={(value) =>
+                  setProportions((current) => ({ ...current, [definition.key]: value }))
+                }
+              />
+            ))}
+          </div>
+        </section>
+      </div>
+
+      <footer style={footerStyle}>
+        <div style={{ display: 'flex', gap: 8 }}>
+          <button
+            className="vgai-btn"
+            data-variant="ghost"
+            data-size="default"
+            type="button"
+            disabled={running !== null}
+            aria-busy={running === 'validate'}
+            onClick={() => void run(true)}
+          >
+            {running === 'validate' ? 'Validating…' : 'Validate without writing'}
+          </button>
+          <button
+            className="vgai-btn"
+            data-variant="solid"
+            data-size="default"
+            type="button"
+            disabled={running !== null}
+            aria-busy={running === 'bake'}
+            onClick={() => void run(false)}
+          >
+            {running === 'bake' ? 'Baking…' : 'Bake humanoid'}
+          </button>
+        </div>
+        <span style={hintStyle}>
+          Outputs go to public/models/generated and public/prefabs/generated.
+        </span>
+      </footer>
+
+      {outcome && (
+        <section style={{ ...panelStyle, marginTop: 14 }} aria-live="polite">
+          {outcome.ok ? (
+            <>
+              <h3 style={sectionHeadingStyle}>
+                {result?.['dryRun'] ? 'Validation passed' : 'Humanoid baked'}
+              </h3>
+              <div style={resultGridStyle}>
+                <span style={hintStyle}>Model</span>
+                <code>{String(result?.['model'] ?? '')}</code>
+                <span style={hintStyle}>Prefab</span>
+                <code>{String(result?.['prefab'] ?? '')}</code>
+                <span style={hintStyle}>Vertices</span>
+                <span>{String(result?.['vertexCount'] ?? '')}</span>
+                <span style={hintStyle}>Clips</span>
+                <span>
+                  {Array.isArray(result?.['clips']) ? result['clips'].join(', ') || 'None' : 'None'}
+                </span>
+              </div>
+            </>
+          ) : (
+            <>
+              <h3 style={sectionHeadingStyle}>Could not bake humanoid</h3>
+              <div style={{ color: 'var(--vgai-danger)' }}>
+                {outcome.error.code}: {outcome.error.message}
+              </div>
+            </>
+          )}
+        </section>
+      )}
+    </main>
+  );
+}
+
+const rootStyle: React.CSSProperties = {
+  padding: 24,
+  maxWidth: 1080,
+  margin: '0 auto',
+  color: 'inherit',
+  fontFamily: 'var(--vgai-font-sans)',
+};
+const columnsStyle: React.CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: 'minmax(260px, 0.8fr) minmax(430px, 1.4fr)',
+  gap: 14,
+  alignItems: 'start',
+};
+const panelStyle: React.CSSProperties = {
+  padding: 16,
+  border: '1px solid var(--vgai-boundary-default)',
+  borderRadius: 'var(--vgai-radius-lg)',
+  background: 'var(--vgai-surface-panel)',
+};
+const sectionHeadingStyle: React.CSSProperties = { margin: '0 0 14px', fontSize: 14 };
+const eyebrowStyle: React.CSSProperties = {
+  color: 'var(--vgai-content-muted)',
+  fontSize: 10,
+  fontWeight: 700,
+  textTransform: 'uppercase',
+  letterSpacing: '0.1em',
+};
+const fieldStyle: React.CSSProperties = { display: 'grid', gap: 6, marginTop: 14 };
+const fieldLabelStyle: React.CSSProperties = { fontSize: 12, fontWeight: 600 };
+const hintStyle: React.CSSProperties = { color: 'var(--vgai-content-muted)', fontSize: 11 };
+const inputStyle: React.CSSProperties = {
+  boxSizing: 'border-box',
+  width: '100%',
+};
+const numberStyle: React.CSSProperties = { ...inputStyle, width: 68 };
+const sliderRowStyle: React.CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: '130px minmax(110px, 1fr) 68px',
+  alignItems: 'center',
+  gap: 10,
+};
+const footerStyle: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 12,
+  marginTop: 14,
+  padding: 14,
+  border: '1px solid var(--vgai-boundary-default)',
+  borderRadius: 'var(--vgai-radius-lg)',
+  background: 'var(--vgai-surface-raised)',
+};
+const resultGridStyle: React.CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: '70px minmax(0, 1fr)',
+  gap: '8px 12px',
+  alignItems: 'baseline',
+};

package/src/render/viewport-shading.ts

@@ -0,0 +1,116 @@
+import * as THREE from 'three';
+
+/** Temporary developer-facing shading modes. These never become scene data. */
+export type ViewportShadingMode = 'solid' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+
+type MaterialPair = {
+  unlit: THREE.MeshBasicMaterial;
+  wireframe: THREE.MeshBasicMaterial;
+};
+
+function materialColor(material: THREE.Material): THREE.Color {
+  const color = (material as THREE.Material & { color?: THREE.Color }).color;
+  return color?.clone() ?? new THREE.Color(0xbec7d1);
+}
+
+function textureOf(material: THREE.Material, key: 'map' | 'alphaMap'): THREE.Texture | null {
+  return (
+    (material as THREE.Material & { map?: THREE.Texture | null; alphaMap?: THREE.Texture | null })[
+      key
+    ] ?? null
+  );
+}
+
+/**
+ * Applies a render-only material view and restores every native material in a
+ * `finally` block. Gameplay and authoring therefore always observe the real
+ * materials; only renderer work inside {@link render} sees the diagnostic view.
+ */
+export class ViewportShadingRenderer {
+  private readonly _derived = new Map<THREE.Material, MaterialPair>();
+  private readonly _normals = new THREE.MeshNormalMaterial();
+  private readonly _overdraw = new THREE.MeshBasicMaterial({
+    color: 0xffffff,
+    transparent: true,
+    opacity: 0.08,
+    depthTest: false,
+    depthWrite: false,
+    blending: THREE.AdditiveBlending,
+    side: THREE.DoubleSide,
+    toneMapped: false,
+  });
+
+  render(
+    scene: THREE.Scene,
+    mode: ViewportShadingMode,
+    draw: () => void,
+    include: (mesh: THREE.Mesh) => boolean = () => true,
+  ): void {
+    if (mode === 'solid') {
+      draw();
+      return;
+    }
+
+    const originals: Array<{
+      mesh: THREE.Mesh;
+      material: THREE.Material | THREE.Material[];
+    }> = [];
+    scene.traverse((object) => {
+      const mesh = object as THREE.Mesh;
+      if (!mesh.isMesh || !mesh.material || !include(mesh)) return;
+      originals.push({ mesh, material: mesh.material });
+      mesh.material = Array.isArray(mesh.material)
+        ? mesh.material.map((material) => this._materialFor(material, mode))
+        : this._materialFor(mesh.material, mode);
+    });
+
+    try {
+      draw();
+    } finally {
+      for (const { mesh, material } of originals) mesh.material = material;
+    }
+  }
+
+  dispose(): void {
+    for (const pair of this._derived.values()) {
+      pair.unlit.dispose();
+      pair.wireframe.dispose();
+    }
+    this._derived.clear();
+    this._normals.dispose();
+    this._overdraw.dispose();
+  }
+
+  private _materialFor(
+    material: THREE.Material,
+    mode: Exclude<ViewportShadingMode, 'solid'>,
+  ): THREE.Material {
+    if (mode === 'normals') return this._normals;
+    if (mode === 'overdraw') return this._overdraw;
+
+    let pair = this._derived.get(material);
+    if (!pair) {
+      const common: THREE.MeshBasicMaterialParameters = {
+        color: materialColor(material),
+        map: textureOf(material, 'map'),
+        alphaMap: textureOf(material, 'alphaMap'),
+        alphaTest: material.alphaTest,
+        opacity: material.opacity,
+        transparent: material.transparent,
+        side: material.side,
+        depthTest: material.depthTest,
+        depthWrite: material.depthWrite,
+        vertexColors: Boolean(
+          (material as THREE.Material & { vertexColors?: boolean }).vertexColors,
+        ),
+        fog: (material as THREE.Material & { fog?: boolean }).fog ?? true,
+      };
+      pair = {
+        unlit: new THREE.MeshBasicMaterial(common),
+        wireframe: new THREE.MeshBasicMaterial({ ...common, wireframe: true }),
+      };
+      this._derived.set(material, pair);
+    }
+    return pair[mode];
+  }
+}

package/src/setup/setup-renderer.ts

@@ -534,3 +534,39 @@ export function applyScenePostProcessing(
     composer.addPass(new EffectPass(camera, ...effects));
   }
 }
+
+/**
+ * Apply every authored scene-level renderer setting through one path.
+ *
+ * Tone mapping is part of the scene environment, not conditional on the
+ * presence of post-processing effects. Keeping renderer settings and the
+ * composer rebuild together prevents editor/runtime drift for scenes that
+ * only author exposure or a tone-mapping mode.
+ */
+export function applySceneRenderPipeline(
+  composer: EffectComposer,
+  renderer: THREE.WebGLRenderer,
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  env?: SceneEnvironment,
+  options?: {
+    basePixelRatio?: number;
+    objectMap?: Map<string, THREE.Object3D>;
+    entityTags?: Map<string, string[]>;
+  },
+): void {
+  applyRendererSettings(
+    renderer,
+    env?.rendering as RenderScope | undefined,
+    options?.basePixelRatio,
+  );
+  applyScenePostProcessing(
+    composer,
+    renderer,
+    scene,
+    camera,
+    env,
+    options?.objectMap,
+    options?.entityTags,
+  );
+}