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.

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
- Zero production bloat:
@aastack/corestays 100% pure. Apps lazy-load@aastack/bridge/clientonly when?bridge=1is present (or the dev toggle is clicked), so normal visitors download 0 bytes of bridge, linter, or schema code. - Multi-agent port sharing: The zero-dependency RFC 6455 WebSocket relay runs inside
@aastack/mcponws://127.0.0.1:8787(override viaAASTACK_BRIDGE_PORT). If a second IDE window or agent starts another@aastack/mcpprocess, it automatically attaches as a follower peer to the active leader on the same port—zeroEADDRINUSEconflicts. - Vendor-neutral schemas:
@aastack/bridge/schemasexports Draft 2020-12 JSON Schemas plus one-line adapters (toOpenAITools(),toAnthropicTools(),toGeminiFunctionDeclarations()) so any future in-browser BYOK AI Studio plugs into the exact sameexecuteEngineTool()contract.
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
| Tool | What It Does |
|---|---|
aastack_live_sessions | Lists all connected browser tabs (sessionId, title, viewport, FPS, active RenderStyle) |
aastack_live_state | Inspects live SceneDocument, registered assets, sockets, and WebGL2 EngineTelemetry |
aastack_live_patch | Validates & applies atomic ScenePatchOp[] with automatic pre-patch undo snapshot and toast label |
aastack_live_undo / aastack_live_redo | Steps backward/forward across shared human + agent history |
aastack_live_hot_swap_blueprint | Validates, 3D-lints, compiles, and hot-swaps a BlueprintSpec JSON live into the running GPU canvas with zero reload |
aastack_live_query | Exact 1:1 CPU/GPU terrainHeight, raycast, and semantic socket (pos + dir) queries |
aastack_live_capture | Renders 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_views | Renders 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_restore | Deterministic time-travel capture and restore |
Offline Validation, 3D Linting & Explicit Persistence
| Tool | What It Does |
|---|---|
aastack_compile_blueprint | Schema-validates, runs the 3D geometric linter, and compiles a BlueprintSpec JSON |
aastack_save_blueprint | Validates, 3D-lints, and writes a clean Git-diffable .blueprint.json inside the workspace |
aastack_export_scene | Snapshots the live browser scene (or validates an explicit scene) and writes a clean .scene.json inside the workspace |
aastack_inspect_vox | Parses & lints a MagicaVoxel .vox binary inside the workspace |
aastack_carve_4view | Runs aa_views_to_slices.py on a 4-view orthographic PNG |
aastack_validate_scene_ir | Validates a SceneDocument + ScenePatchOp[] against strict schemas and mobile entity budgets |
aastack_get_sdk_spec | Loads 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:
EMPTY_VOLUME(error): Catches blueprints whose CSG ops produce0solid voxels.FLOATING_VOXEL_ISLAND(warning): Exact 3D 6-connected-component BFS reporting the voxel count and[min..max]bounding box of every detached floating part.SOCKET_OUT_OF_BOUNDS/SOCKET_DETACHED(warning): Flags sockets outside[0..W, 0..L, 0..H]or floating> 4voxels outside the primary hull's bounding box (while cleanly permitting interior sockets like hollow-ring"center"or"cockpitCam").SPARSE_GRID/MOBILE_VRAM_BUDGET(warning): Guards mobile 3D texture memory (> 512 KB) and entity fill-rate budgets (> 64visible OBBs).
5. Security Boundaries
- The WebSocket relay binds strictly to
127.0.0.1and checks the HTTPOriginheader against127.0.0.1/localhost/null(rejecting all external websites with403 Forbidden), with optionalAASTACK_BRIDGE_TOKENauthentication. - All MCP disk reads and writes (
aastack_save_blueprint,aastack_export_scene,savePath,aastack_inspect_vox,aastack_carve_4view) are confined strictly inside the workspace root (../path traversal is rejected).