API Reference

Concise, exact TypeScript & MCP API reference for @aastack/core, @aastack/blueprint, and @aastack/mcp.


1. @aastack/core

Zero external runtime dependencies. All exports live in packages/core/src/index.ts.

Core Types (types.ts)

TypeDefinition
Vec2, Vec3, Quat, RGBTuple types: [number, number], [number, number, number], [x, y, z, w], [r, g, b] (0..255)
RenderStyle`"arcade-8bit" \"hd-2d" \"smooth-toy" \"retro-raw"`
AAMode`"legacy" \"voxel-dda" \"smooth-sdf" \"bandlimited"`
AAQuality`"eco" \"balanced" \"ultra"`
BackgroundMode`"terrain" \"studio" \"solid" \"transparent"`
ShadeStyle`"toon-aa" \"pbr-lite" \"unlit"`
CameraMode`"overhead" \"chase" \"cockpit" \"ortho" \"oblique" \"free"`
IsometricPreset`"dimetric-2to1" \"isometric" \"oblique-stack" \"topdown-3quarter"`
QualityTier`"auto" \"mobile" \"desktop" \"eco" \"balanced" \"ultra"`
DebugOverlay`"none" \"normals" \"depth" \"object-id"`
EntityState{ id, assetId, pos, rot, scale, outline?, normalSmoothness?, aaPriority?, castShadow?, emissiveBoost?, tag?, visible?, parentId?, parentSocket? }
SocketDef{ pos: Vec3; dir?: Vec3 } in voxel asset space [0..W, 0..L, 0..H]
ScenePatchOp{ op: "set"; path: string; value: unknown } \{ op: "spawn"; entity: EntityState } \{ op: "remove"; entityId: string } \{ op: "updateEntity"; entityId: string; patch: Partial<Omit<EntityState, "id">> }

SceneWorld (scene.ts)

Holds the serializable SceneDocument (SceneIR), asset registry, undo/redo stacks, and spatial queries.

const world = new SceneWorld(initial?: Partial<SceneDocument>);
Method / PropertyDescription
world.docCurrent SceneDocument (style, aaMode, samples, camera, lighting, terrain, splitCompare, debugOverlay, entities, ribbons, time, tick, seed)
world.registerAsset(asset: VolumeAsset)Registers or hot-swaps a VolumeAsset by asset.id; GPU textures update automatically when asset.hash changes
world.getAsset(id: string)Returns `VolumeAsset \undefined`
world.listAssets()Returns all registered VolumeAsset[]
world.applyPatch(ops: ScenePatchOp[], recordUndo = true)Applies atomic surgical edits to world.doc and pushes an undo entry when recordUndo is true
world.undo(): boolean / world.redo(): booleanSteps backward/forward through SceneIR patch history
world.stepClock(dt: number)Advances deterministic simulation time, tick, and terrain.waveTime
world.snapshot(): string / world.restore(json: string)Full deterministic JSON serialization & time-travel restore
world.getEntity(id: string)Returns `EntityState \undefined`
world.getEntityWorldMatrix(id, depth?, out?)Computes hierarchical Float32Array(16) world matrix (resolving parentId + parentSocket); pass out to avoid allocation
world.getVoxelToWorldMatrix(ent, out?)Computes Float32Array(16) mapping voxel coords [0..W, 0..L, 0..H] directly to world space; pass out for zero-GC rendering
world.getSocketWorldPos(entityId, socketName)Returns world-space `Vec3 \null` for a named asset socket
world.getSocketWorldDir(entityId, socketName)Returns normalized world-space `Vec3 \null` for a socket's local direction
world.sampleTerrainHeight(x, z)Returns exact elevation >= 0 (0 = ocean), matching TERRAIN_FS 1:1
world.raycastEntities(ro, rd, maxDist = 400)Exact 3D voxel DDA raycast against all visible entities; returns `SpatialHit \null (entityId, distance, point, normal, voxel`)

Standalone helper: sampleTerrainHeight(x, z, terrain) and createDefaultScene(seed?).

AASpriteRenderer (renderer.ts)

const renderer = new AASpriteRenderer(canvas: HTMLCanvasElement, opts?: {
  quality?: QualityTier;          // default "auto" ("eco" | "balanced" | "ultra" | "mobile" | "desktop")
  background?: BackgroundMode;    // default "terrain" ("transparent" | "studio" | "solid" | "terrain")
  backgroundColor?: RGB;          // RGB [0..255] used when background === "solid"
  adaptiveDpr?: boolean;          // default true (GPU/thermal DRS governor)
  maxDpr?: number;                // default 1.25 eco, 1.5 balanced (1.35 mobile), 2.0 ultra
  powerPreference?: "default" | "low-power" | "high-performance"; // default "default"
  preserveDrawingBuffer?: boolean; // default true (enables captureDataUrl)
});
Method / PropertyDescription
renderer.isReadytrue if WebGL2 context and all 6 shader programs linked cleanly
renderer.isMobileResolved mobile profile flag
renderer.setQuality(preset: AAQuality, world?)Live runtime AA quality softswitch ("eco" 2× / "balanced" 4× / "ultra" 8× Retina + full-res JFA)
renderer.getQuality(): AAQualityReturns active runtime AA quality preset
renderer.setBackground(mode: BackgroundMode, color?: RGB)Switches backdrop mode at runtime ("transparent", "studio", "solid", "terrain") without recreating WebGL2
renderer.getBackground(): BackgroundModeReturns active background mode
renderer.resizeToDisplay(cssW?, cssH?)Resizes backing buffer respecting DPR cap & adaptive DRS
renderer.render(world: SceneWorld)Renders all active passes (optional backdrop, OBB entities, 3D ribbons, JFA outlines + bloom + premultiplied transparent or opaque composite)
renderer.getStats(): EngineTelemetryReturns { fps, frameMs, gpuMs?, quality, canvasWidth, canvasHeight, dpr, drsScale, drawCalls, visibleEntities, totalEntities, isMobile, backend, activeSamples, tick, time }
renderer.captureDataUrl(world, mimeType?)Renders one deterministic frame and returns a PNG/WebP data URL for visual QA & MCP screenshots
renderer.evictAsset(assetId: string): booleanFrees GPU 3D textures for a single asset without disposing the renderer
renderer.dispose()Releases all WebGL2 textures, FBOs, buffers, VAOs, shader programs, timer queries, and context listeners

2.5D Isometric, Oblique & Picking Helpers (camera.ts)

FunctionDescription
createIsometricCamera(opts?)Builds a drop-in CameraState for "dimetric-2to1" (exact 2:1 pixel-art diamond grid), "isometric" (35.264° equal-axis axonometric), "oblique-stack" (un-foreshortened circular XZ footprints + pure vertical slice extrusion), or "topdown-3quarter" (55° RPG tilt); supports pixelsPerUnit + viewportHeightCss exact pixel locking
computeCameraViewProj(cam, aspect, viewOut?, projOut?, vpOut?)Canonical View-Projection matrix builder shared by WebGL2 rendering and CPU picking
projectWorldToScreen(worldPos, cam, w, h)Projects a 3D world point [X, Y, Z] to DOM/Canvas2D { x, y, depth, visible } coordinates
unprojectScreenToGround(sx, sy, cam, w, h, groundY = 0)Exact screen-to-ground-plane ray intersection across perspective, orthographic, dimetric, isometric, and oblique projections

Volume & Asset Loaders (volume.ts, loaders.ts)

FunctionDescription
createVolumeAsset(input)Builds a complete VolumeAsset (optional 3D EDT SDF via computeSdf?: boolean, smooth normals + AO, 3D RGB edge dilation, emissive mask, content hash) from raw rgba voxels
compute3DSdf(rgba, w, l, h, smoothStrength?)Exact O(N) 3-pass Felzenszwalb–Huttenlocher 3D Euclidean SDF with boundary air clamping
parseVox(buffer: ArrayBuffer, opts: VoxParseOptions)Zero-dependency MagicaVoxel .vox binary parser (SIZE, XYZI, RGBA, default palette, optional computeSdf)
loadVoxUrl(url: string, opts: VoxParseOptions)Async one-line drop-in loader fetching and compiling any MagicaVoxel .vox URL
loadSliceStripPixels(pixels, stripW, stripH, opts)Loads horizontal slices.png RGBA pixel buffers into a VolumeAsset
loadSliceStripFromImage(img, opts)Compiles an already-loaded HTMLImageElement or ImageBitmap horizontal slice strip into a VolumeAsset
loadSliceStripUrl(url: string, opts: SliceStripOptions)Async one-line browser drop-in loader fetching and compiling any horizontal slices.png strip URL

6-DOF Math, Frustum Culling & Mobile Touch (math.ts, mobile.ts)


2. @aastack/blueprint

Zero external runtime dependencies (depends only on @aastack/core).

compileBlueprint(spec: BlueprintSpec): VolumeAsset

interface BlueprintSpec {
  id: string;
  name?: string;
  size: [number, number, number]; // [W, L, H], max 256*256*128
  voxelScale?: number;            // default 1.0
  pivot?: Vec3;                   // default [W/2, L/2, H/2]
  smoothSdf?: number;             // default 0.14
  ops: BlueprintOp[];
  sockets?: Record<string, SocketDef>;
}
opParametersOptional Modifiers
"box"min: Vec3, max: Vec3color, emissive, subtract, mirrorX
"sphere"center: Vec3, radius: numbercolor, emissive, subtract, mirrorX
"ellipsoid"center: Vec3, radii: Vec3color, emissive, subtract, mirrorX
"capsule"a: Vec3, b: Vec3, rA: number, rB?: numbercolor, emissive, subtract, mirrorX
"wedge"min: Vec3, max: Vec3, taperAxis, shrinkAxis, minScale?color, emissive, mirrorX
"torus"`center: Vec3, majorRadius: number, minorRadius: number, axis: "x"\"y"\"z"`color, emissive
"paint"min: Vec3, max: Vec3, color: RGBemissive, mirrorX

Built-In Presets (presets.ts)


3. @aastack/bridge

Zero-dependency isomorphic package (sideEffects: false) providing strict schemas, 3D geometric linting, the vendor-neutral tool dispatcher, and the browser dev bridge client.

@aastack/bridge/schemas

@aastack/bridge/linter

@aastack/bridge/tools

@aastack/bridge/client


4. @aastack/mcp

Zero-dependency stdio JSON-RPC 2.0 MCP server + embedded localhost RFC 6455 WebSocket relay (node packages/mcp/dist/server.js) with automatic leader/follower multi-agent port sharing.