# AASpriteStacker (@aastack/*) — Frontier AI Agent SDK Specification Zero-dependency, mobile-first, anti-aliased 6-DOF & 2.5D sprite-stacking rendering engine for WebGL2. ## Coordinate Convention - **World Space:** Right-handed Y-up (`+X` right, `+Y` up/altitude, `-Z` forward). - **Voxel Asset Space:** `[0..W, 0..L, 0..H]` (`+X` right, `+Y` nose/forward, `+Z` up/roof). - `mat4AssetToLocal` maps asset `(x, y, z)` to world `(x - pivotX, z - pivotZ, -(y - pivotY)) * voxelScale`. ## Quickstart (`@aastack/core`) ```ts import { AASpriteRenderer, SceneWorld, createIsometricCamera, loadSliceStripUrl, loadVoxUrl } from "@aastack/core"; // Presets: "dimetric-2to1" | "isometric" | "oblique-stack" | "topdown-3quarter" const world = new SceneWorld({ camera: createIsometricCamera({ preset: "dimetric-2to1", target: [0, 2.4, 0], orthoSize: 10.5 }), }); // background: "transparent" | "studio" | "solid" | "terrain" (use "transparent" to overlay existing 2D games!) const renderer = new AASpriteRenderer(canvas, { background: "transparent", quality: "ultra" }); // Drop-in loaders: loadSliceStripUrl(url, { id, slices }), loadVoxUrl(url, { id }), or compileBlueprint(...) world.registerAsset(await loadSliceStripUrl("/car_slices.png", { id: "car", slices: 24 })); world.applyPatch([ { op: "set", path: "style", value: "arcade-8bit" }, // "arcade-8bit" | "hd-2d" | "smooth-toy" | "retro-raw" { op: "set", path: "aaMode", value: "voxel-dda" }, // "voxel-dda" | "smooth-sdf" | "legacy" { op: "spawn", entity: { id: "hero", assetId: "car", pos: [0, 2.8, 0], rot: [0, 0, 0, 1], scale: 1, outline: true, aaPriority: "hero" } }, ]); function loop(dt: number) { world.stepClock(dt); renderer.render(world); } ``` ## First-Principles Iterative Hooks 1. **Patchable SceneIR:** `world.applyPatch(ops)` (`"set" | "spawn" | "remove" | "updateEntity"`), `world.undo()`, `world.redo()`. 2. **Deterministic Time-Travel:** `const snap = world.snapshot(); world.restore(snap);` 3. **Hot-Swappable Asset Registry:** `world.registerAsset(newAsset)` updates GPU 3D textures automatically by content hash; `renderer.evictAsset(assetId)` frees GPU textures per asset. 4. **Semantic Sockets:** `world.getSocketWorldPos("jet", "wingtipL")` & `world.getSocketWorldDir("jet", "thrusterL")`. 5. **Spatial & 2.5D Picking Queries (1:1 with Rendered Pixels):** `world.sampleTerrainHeight(x, z)`, `world.raycastEntities(ro, rd, maxDist)`, `projectWorldToScreen(pos, cam, w, h)`, and `unprojectScreenToGround(sx, sy, cam, w, h, groundY)`. 6. **Introspection & QA:** `renderer.getStats()` (FPS, frameMs, gpuMs, quality, DRS, DPR, drawCalls, isMobile) and `renderer.captureDataUrl(world)`. 7. **Live AA Quality & Background Softswitches:** `renderer.setQuality("eco" | "balanced" | "ultra", world)` toggles `2×` / `4×` / `8×` RGSS, DPR (`1.25×` / `1.5×` / `2.0×`), and half-res vs. full-res JFA outlines at runtime; `renderer.setBackground("transparent" | "studio" | "solid" | "terrain", rgb?)` switches backdrop mode with zero context rebuild. 8. **First-Class 2.5D Isometric / Oblique Cameras & Genre-Agnostic Shading:** `createIsometricCamera({ preset: "dimetric-2to1" | "isometric" | "oblique-stack" | "topdown-3quarter", pixelsPerUnit?, viewportHeightCss? })`, explicit `entity.normalSmoothness` (`0..1`), and `entity.aaPriority` (`"hero" | "auto"`). ## Live Agent Dev Bridge (`@aastack/bridge` + `@aastack/mcp`) - Opt-in browser client (`@aastack/bridge/client`): lazy-load `connectDevBridge({ world, renderer }, { title })` when `?bridge=1` is set (`ws://127.0.0.1:8787`, zero production bloat). - Strict Draft 2020-12 JSON Schemas + vendor-neutral adapters (`@aastack/bridge/schemas`): `toOpenAITools()`, `toAnthropicTools()`, `toGeminiFunctionDeclarations()`. - 3D Geometric Linter (`@aastack/bridge/linter`): `lintVolumeAsset()` detects floating disconnected voxel islands (3D BFS), out-of-bounds/detached sockets, empty volumes, and mobile VRAM budgets. - MCP Server (`@aastack/mcp` -> `node packages/mcp/dist/server.js`): embedded zero-dep RFC 6455 localhost WebSocket relay with multi-agent leader/follower port sharing. - **Live tools:** `aastack_live_sessions`, `aastack_live_state`, `aastack_live_patch`, `aastack_live_undo`, `aastack_live_redo`, `aastack_live_hot_swap_blueprint`, `aastack_live_query`, `aastack_live_snapshot`, `aastack_live_restore`, `aastack_live_capture` (native MCP `image/png`), `aastack_live_capture_views` (2x2 labeled PNG contact sheet: `turntable` or `scene`). - **Offline & Persistence tools:** `aastack_compile_blueprint`, `aastack_save_blueprint`, `aastack_export_scene`, `aastack_inspect_vox`, `aastack_carve_4view`, `aastack_validate_scene_ir`, `aastack_get_sdk_spec`. ## Asset Ingest Formats - **Declarative Blueprints (`@aastack/blueprint`):** `compileBlueprint({ id, size: [W,L,H], voxelScale, ops: [box|sphere|ellipsoid|capsule|wedge|torus|paint], sockets })`. Supports `subtract: true` (hollow cavities), `mirrorX: true`, `emissive: true`. - **MagicaVoxel `.vox`:** `parseVox(arrayBuffer, { id, voxelScale })`. - **Horizontal `slices.png` strips:** `loadSliceStripPixels(rgba, stripW, stripH, { id, slices })`. - **4-View Orthographic PNGs (Python CLI):** `python3 skills/aa-sprite-stacking/scripts/aa_views_to_slices.py views.png slices.png --slices 36 --sdf sdf.png --preview check.png`.