AI-First Engine Architecture & Live Agent Bridge (@aastack/bridge + @aastack/mcp)

AASpriteStacker is designed from inception to be frontier-AI native without putting a single AI API key, vendor SDK, or bloated abstraction inside @aastack/core.

Instead of assuming a model must "one-shot" a game in a single prompt, the engine exposes six first-principles iterative hooks paired with a zero-dependency localhost WebSocket dev bridge so any coding agent can inspect, patch, hot-swap blueprints, visually self-critique 2×2 multi-angle renders, and persist clean Git-diffable JSON over multiple turns.

Live 2×2 Multi-Angle Contact Sheet Captured via @aastack/mcp

A real 960×600 2×2 diagnostic contact sheet (Chase, Overhead, Side 3/4, Normals Debug) returned directly as a native MCP image/png content block from live WebGL2 Chromium immediately after an agent hot-swapped golden forward canards onto the fighter jet with zero page reload.


1. Architecture: Isomorphic @aastack/bridge + Live @aastack/mcp

flowchart LR
  AGENT["Frontier Agent<br/>(Antigravity / Claude Code / Cursor / Codex / Gemini CLI)"]
  MCP["@aastack/mcp<br/>Stdio JSON-RPC + Zero-Dep RFC 6455 WS Relay<br/>(ws://127.0.0.1:8787, Leader/Follower Sharing)"]
  BRIDGE["@aastack/bridge (Isomorphic, 0 deps)<br/>JSON Schemas · 3D Geometric Linter · Tool Dispatcher"]
  BROWSER["Live Browser Tab (?bridge=1)<br/>connectDevBridge() + 'Agent Live' Pill + 1-Click Undo"]
  DISK["Workspace Disk (Confined)<br/>*.blueprint.json / *.scene.json"]

  AGENT <-->|"MCP stdio (JSON + image/png)"| MCP
  MCP <-->|"Shared Schemas & Linter"| BRIDGE
  MCP <-->|"Localhost WS (Loopback + Origin Allowlist)"| BROWSER
  BROWSER -->|"executeEngineTool()"| BRIDGE
  MCP -->|"Explicit Save/Export"| DISK

2. Connecting Your Coding Agent (@aastack/mcp)

Build the monorepo once:

npm install
npm run build

Register @aastack/mcp in your MCP client config (Antigravity, Claude Code, Cursor, Codex, Gemini CLI):

{
  "mcpServers": {
    "aastack": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/AASpriteStacker/packages/mcp/dist/server.js"]
    }
  }
}

Then open your app with ?bridge=1:

npm run dev:serve
# Open: http://127.0.0.1:8765/examples/flight-6dof/index.html?bridge=1

A compact "Agent Live" pill appears in the top-left corner showing connection status, a toast of each live agent edit, and a 1-click Undo button backed by world.undo().


3. Full MCP Tool Surface (18 Tools)

Live Browser Co-Editing & Visual Self-Critique

ToolWhat It Does
aastack_live_sessionsLists all connected browser tabs (sessionId, title, viewport, FPS, active RenderStyle)
aastack_live_stateInspects live SceneDocument, registered assets, sockets, and WebGL2 EngineTelemetry
aastack_live_patchValidates & applies atomic ScenePatchOp[] with automatic pre-patch undo snapshot and toast label
aastack_live_undo / aastack_live_redoSteps backward/forward across shared human + agent history
aastack_live_hot_swap_blueprintValidates, 3D-lints, compiles, and hot-swaps a BlueprintSpec JSON live into the running GPU canvas with zero reload
aastack_live_queryExact 1:1 CPU/GPU terrainHeight, raycast, and semantic socket (pos + dir) queries
aastack_live_captureRenders a single PNG (≤ 1024px) with optional temporary style / cameraMode / debugOverlay, returned as a native MCP image/png block + telemetry JSON (+ optional savePath)
aastack_live_capture_viewsRenders a 2×2 labeled PNG contact sheet (preset: "turntable" for 0°/90°/180°/270° or preset: "scene" for Chase/Overhead/Side 3/4/Normals Debug), cleanly restoring prior camera & state
aastack_live_snapshot / aastack_live_restoreDeterministic time-travel capture and restore

Offline Validation, 3D Linting & Explicit Persistence

ToolWhat It Does
aastack_compile_blueprintSchema-validates, runs the 3D geometric linter, and compiles a BlueprintSpec JSON
aastack_save_blueprintValidates, 3D-lints, and writes a clean Git-diffable .blueprint.json inside the workspace
aastack_export_sceneSnapshots the live browser scene (or validates an explicit scene) and writes a clean .scene.json inside the workspace
aastack_inspect_voxParses & lints a MagicaVoxel .vox binary inside the workspace
aastack_carve_4viewRuns aa_views_to_slices.py on a 4-view orthographic PNG
aastack_validate_scene_irValidates a SceneDocument + ScenePatchOp[] against strict schemas and mobile entity budgets
aastack_get_sdk_specLoads llms-full.txt directly into agent context

4. Automated 3D Geometric Linter (@aastack/bridge/linter)

Every BlueprintSpec compilation and live hot-swap automatically runs a < 1 ms geometric & mobile-budget check so frontier models self-correct in 1 turn:


5. Security Boundaries