Getting Started with AASpriteStacker

This guide walks you through installing the workspace, building your first anti-aliased 6-DOF or 2.5D scene, creating assets across all four supported pipelines, and deploying cleanly to both desktop and mobile browsers.


1. Setup & Workspace Commands

Clone the repository and install dev dependencies (typescript and esbuild; runtime packages have zero dependencies):

git clone https://github.com/dmsimon1/AASpriteStacker.git
cd AASpriteStacker
npm install
npm run build

Useful root scripts:

CommandPurpose
npm run buildBuilds all 4 workspaces (@aastack/{core,blueprint,bridge,mcp}) + bundles examples/flight-6dof & examples/minimal-2d
npm run build:siteBuilds the full static aasprite.com website into site/dist/
npm run typecheckStrict TypeScript project-reference check across all workspaces
npm testRebuilds and runs the Node test suite (tests/*.test.mjs)
npm run test:pyRuns the Python carving & AA quality suite (.venv/bin/python tests/test_aa_stacker.py)
npm run test:allRuns both TypeScript and Python test suites
npm run dev:serveStarts a local static HTTP server at http://127.0.0.1:8765

2. Drop-In 2.5D Isometric & Oblique Overlay (Shortest Path)

Want to drop anti-aliased sprite stacks straight on top of an existing 2D tilemap, Canvas2D, PixiJS, or Phaser game? Set background: "transparent", pick a first-class 2.5D projection preset via createIsometricCamera() ("dimetric-2to1", "isometric", "oblique-stack", or "topdown-3quarter"), and use our one-line URL loaders (loadSliceStripUrl or loadVoxUrl):

import {
  AASpriteRenderer,
  SceneWorld,
  createIsometricCamera,
  loadSliceStripUrl,
  quatFromYawPitchRoll,
  unprojectScreenToGround,
} from "@aastack/core";

const renderer = new AASpriteRenderer(canvas, { background: "transparent", quality: "ultra" });
const world = new SceneWorld({
  // Presets: "dimetric-2to1" (2:1 diamond grid) | "isometric" (35.264°) | "oblique-stack" (SpriteStack/Nium) | "topdown-3quarter"
  camera: createIsometricCamera({ preset: "dimetric-2to1", target: [0, 2.4, 0], orthoSize: 10.5 }),
});

const car = await loadSliceStripUrl("/car_slices.png", { id: "car", slices: 24 });
// Or MagicaVoxel: const car = await loadVoxUrl("/car.vox", { id: "car" });
world.registerAsset(car);
world.applyPatch([
  { op: "set", path: "aaMode", value: "voxel-dda" },
  { op: "spawn", entity: { id: "hero", assetId: "car", pos: [0, 2.8, 0], rot: quatFromYawPitchRoll(0.6, 0, 0), scale: 1, outline: true } },
]);

// Click-to-tile ground picking works identically across dimetric, true iso, oblique, and perspective:
const hit = unprojectScreenToGround(mouseX, mouseY, world.doc.camera, canvas.clientWidth, canvas.clientHeight, 0);

// Runtime AA quality softswitch ("eco" 2x | "balanced" 4x | "ultra" 8x Retina + full-res JFA):
renderer.setQuality("ultra", world);
renderer.render(world);

Try it live at /iso/ or inspect the complete starter in examples/minimal-2d/.


3. Building a Full 6-DOF Scene (@aastack/core)

Create an HTML page with a <canvas id="gl"> and wire up SceneWorld + AASpriteRenderer:

import {
  AASpriteRenderer,
  SceneWorld,
  quatFromYawPitchRoll,
} from "@aastack/core";
import {
  compileBlueprint,
  createFighterJetBlueprint,
} from "@aastack/blueprint";

const canvas = document.getElementById("gl") as HTMLCanvasElement;
const world = new SceneWorld({ seed: 42 });
const renderer = new AASpriteRenderer(canvas, {
  quality: "auto",      // "auto" | "mobile" | "desktop" | "ultra"
  adaptiveDpr: true,    // dynamic resolution scaling on mobile GPUs
});

// 1. Register volumetric assets (auto-uploads 3D RGBA, SDF, Normal/AO, Emissive textures)
world.registerAsset(compileBlueprint(createFighterJetBlueprint("jet-asset")));

// 2. Configure render style, camera, and spawn entities via declarative patches
world.applyPatch([
  { op: "set", path: "style", value: "arcade-8bit" }, // or "hd-2d" | "smooth-toy" | "retro-raw"
  { op: "set", path: "terrain.enabled", value: true },
  {
    op: "set",
    path: "camera",
    value: {
      mode: "chase",
      pos: [0, 34, 18],
      target: [0, 28, -12],
      up: [0, 1, 0],
      fovDeg: 52,
      orthoSize: 24,
      near: 0.4,
      far: 500,
    },
  },
  {
    op: "spawn",
    entity: {
      id: "player",
      assetId: "jet-asset",
      pos: [0, 28, 0],
      rot: quatFromYawPitchRoll(0, 0, 0),
      scale: 1.0,
      outline: true,
      castShadow: true,
      tag: "player",
    },
  },
]);

// 3. Render loop
let last = performance.now();
function loop(now: number) {
  const dt = Math.min(0.05, (now - last) / 1000);
  last = now;
  world.stepClock(dt);

  const player = world.getEntity("player")!;
  player.rot = quatFromYawPitchRoll(world.doc.time * 0.8, 0.1, Math.sin(world.doc.time) * 0.4);

  renderer.render(world);
  requestAnimationFrame(loop);
}
requestAnimationFrame(loop);

Orthographic 2.5D Mode (Classic Top-Down / Isometric)

Want classic isometric/top-down sprite stacking with silky anti-aliasing and zero wobble? Just switch the camera to "ortho" and turn off terrain (or keep terrain enabled for top-down islands):

world.applyPatch([
  { op: "set", path: "terrain.enabled", value: false },
  {
    op: "set",
    path: "camera",
    value: {
      mode: "ortho",
      pos: [0, 42, 42],
      target: [0, 0, 0],
      up: [0, 1, 0],
      fovDeg: 45,
      orthoSize: 18,
      near: 0.1,
      far: 300,
    },
  },
]);

3. Asset Pipelines (4 Ways to Create Volumetric Sprites)

AASpriteStacker supports four first-class asset workflows — mix and match freely in the same scene:

Pipeline A: Declarative Voxel + 3D SDF Blueprints (@aastack/blueprint)

Best for procedural craft, rapid iteration, Git-diffable assets, hollow cavities, and AI-assisted creation.

import { compileBlueprint } from "@aastack/blueprint";
import type { BlueprintSpec } from "@aastack/blueprint";

const turretSpec: BlueprintSpec = {
  id: "plasma-turret",
  name: "Plasma Turret",
  size: [20, 20, 16],
  voxelScale: 0.25,
  pivot: [10, 10, 2],
  ops: [
    // Armored base
    { op: "box", min: [4, 4, 0], max: [15, 15, 4], color: [64, 74, 92] },
    // Rounded dome with hollow visor cutout
    { op: "sphere", center: [10, 10, 8], radius: 5.5, color: [88, 100, 122] },
    { op: "box", min: [7, 13, 7], max: [12, 16, 10], subtract: true },
    // Glowing cyan sensor eye inside hollow cavity
    { op: "sphere", center: [10, 13.5, 8.5], radius: 1.4, color: [52, 232, 255], emissive: true },
    // Mirrored twin cannons (+Y is nose/forward)
    { op: "capsule", a: [5.5, 10, 8], b: [5.5, 18.5, 8], rA: 1.1, rB: 0.85, color: [255, 82, 40], mirrorX: true },
  ],
  sockets: {
    muzzleL: { pos: [5.5, 19.0, 8.0], dir: [0, 1, 0] },
    muzzleR: { pos: [14.5, 19.0, 8.0], dir: [0, 1, 0] },
  },
};

const asset = compileBlueprint(turretSpec);
world.registerAsset(asset);

Supported BlueprintOp primitives: box, sphere, ellipsoid, capsule, wedge, torus, paint — with subtract: true (CSG cutout), mirrorX: true (X-axis symmetry), and emissive: true (bloom mask).

Pipeline B: MagicaVoxel .vox Files (parseVox)

Zero-dependency binary parser supporting SIZE, XYZI, RGBA, and default palette fallback:

import { parseVox } from "@aastack/core";

const res = await fetch("./assets/spaceship.vox");
const buf = await res.arrayBuffer();
const asset = parseVox(buf, {
  id: "spaceship",
  voxelScale: 0.25,
  sockets: { engine: { pos: [12, 0, 6], dir: [0, -1, 0] } },
});
world.registerAsset(asset);

Pipeline C: Classic Horizontal slices.png Strips (loadSliceStripPixels)

100% compatible with existing sprite-stack strips (including danielwh2/sprite-stacking assets):

import { loadSliceStripPixels } from "@aastack/core";

const img = await createImageBitmap(await (await fetch("./slices.png")).blob());
const c = new OffscreenCanvas(img.width, img.height);
const ctx = c.getContext("2d")!;
ctx.drawImage(img, 0, 0);
const pixels = ctx.getImageData(0, 0, img.width, img.height).data;

const asset = loadSliceStripPixels(pixels, img.width, img.height, {
  id: "cottage",
  slices: 32,
  voxelScale: 0.3,
});
world.registerAsset(asset);

Pipeline D: 4-View Orthographic PNGs (Python Carver CLI + Browser Look-Dev Studio)

Turn a 2×2 or 1×4 orthographic turnaround (Front / Right / Back / Left PNG) into an edge-dilated slice strip, 3D SDF atlas, smooth normals atlas, comparison sheet, and standalone interactive HTML viewer:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

.venv/bin/python skills/aa-sprite-stacking/scripts/aa_views_to_slices.py \
  views.png out/slices.png \
  --slices 36 \
  --sdf out/sdf.png \
  --normals out/normals.png \
  --preview out/comparison.png \
  --html out/viewer.html \
  --export-dirs 16

Add --round for cylindrical/turned silhouettes (lighthouses, rockets, barrels, towers) to fuse an analytic circular cross-section into the 3D SDF.


4. Switching Styles & Running Live A/B Comparisons

Switch art direction at runtime:

world.applyPatch([
  { op: "set", path: "style", value: "smooth-toy" }, // "arcade-8bit" | "hd-2d" | "smooth-toy" | "retro-raw"
]);

Enable the built-in split-screen A/B curtain (Retro 1× on the left vs. AA on the right):

world.applyPatch([
  {
    op: "set",
    path: "splitCompare",
    value: { enabled: true, splitX: 0.5, leftMode: "legacy", rightMode: "voxel-dda" },
  },
]);

5. Mobile Multi-Touch Integration

Use createTouchController from @aastack/core for rock-solid concurrent steering + action buttons on phones and tablets:

import { createTouchController } from "@aastack/core";

const touch = createTouchController({
  steerZone: document.getElementById("stage")!,
  stickBase: document.getElementById("stickBase"),
  stickKnob: document.getElementById("stickKnob"),
  maxRadius: 48,
});

// Inside your simulation tick:
const steerX = touch.state.steering ? touch.state.steerX : keyboardX;
const steerY = touch.state.steering ? touch.state.steerY : keyboardY;

Be sure your CSS sets touch-action: none on the stage container, viewport-fit=cover in <meta name="viewport">, safe-area padding (env(safe-area-inset-*)), and ≥ 44×44 px touch targets under @media (pointer: coarse).


6. Connecting a Frontier Coding Agent Live (?bridge=1)

To let Antigravity, Claude Code, Cursor, Codex, or Gemini CLI patch your live browser scene, hot-swap blueprints, and inspect 2×2 PNG contact sheets with zero production overhead, lazy-load @aastack/bridge/client only when ?bridge=1 is present:

if (new URLSearchParams(window.location.search).get("bridge") === "1") {
  const { connectDevBridge } = await import("@aastack/bridge/client");
  connectDevBridge(
    { world, renderer, onSyncUI: () => syncUI() },
    { title: "My AASpriteStacker Game" },
  );
}

Then register packages/mcp/dist/server.js in your MCP config and open your page with ?bridge=1. See docs/ai-integration.md for the full 18-tool reference and security boundaries.


7. Using the Shaders in Godot 4 or Unity URP

See skills/aa-sprite-stacking/references/engines.md for drop-in single-draw-call RGSS Voxel DDA and 3D SDF shaders for Godot 4, Unity URP, WebGL2, and Canvas 2D.