Architecture & How It Works

This document explains the graphics algorithms, coordinate conventions, volumetric preprocessing, WebGL2 rendering passes, and mobile performance architecture that power AASpriteStacker (@aastack/*).


1. Why Classic Sprite Stacking Breaks — And Our Fix

Classic sprite stacking renders $H$ horizontal slices of a voxel model as stacked 2D quads shifted by (0, -z) on screen. That approach fails in five well-known ways:

  1. Rotation Pixel Crawl & 1px Post Dropout: Nearest-neighbor sampling at arbitrary angles causes staircase swimming and makes 1-voxel-thin structures (antennas, masts, wingtips) blink in and out of existence.
  2. Vertical-Wall Alpha Buildup: Turning on naive bilinear filtering across $H$ stacked slices compounds partial edge alpha: $\alpha_{\text{wall}} = 1 - (1 - \alpha)^H \to 1$, producing bloated, muddy vertical silhouettes.
  3. Black Bilinear Halos: Standard transparent pixels store (0, 0, 0, 0). Hardware linear/trilinear filtering interpolates toward black at every silhouette edge.
  4. Cardinal-Angle 1-Voxel Drift: Tiny floating-point epsilon (sin(π) ≈ 1.22e-16) causes asymmetric rounding or spurious initial DDA steps at 90°/180° on even-sized sprites.
  5. No True 6-DOF Perspective: Vertical 2D quad stacks separate into visible gaps ("pancaking") as soon as you pitch or roll the camera, and cannot depth-interleave cleanly with terrain, volumetric clouds, or trails.

AASpriteStacker replaces 2D slice quads with GPU-native 3D volumetric raycasting inside tight 12-triangle Oriented Bounding Box (OBB) proxies, combined with exact volumetric preprocessing and 2D screen-space SDF post-processing.


2. Coordinate Systems & Transform Contract

Every package in @aastack/* follows one strict right-handed convention:

```text

localX = (vx - pivotX) * voxelScale

localY = (vz - pivotZ) * voxelScale

localZ = -(vy - pivotY) * voxelScale

```

Determinant is +voxelScale³ (strictly orientation-preserving, right-handed).


3. Volumetric Preprocessing (packages/core/src/volume.ts)

Regardless of how an asset enters the engine (declarative Blueprint CSG, MagicaVoxel .vox, slices.png strip, or 4-view soft visual-hull carve), createVolumeAsset() builds four GPU-ready 3D textures plus a fast content hash:

Input Voxels (RGBA8)
   ├──► 1. O(N) 3-Pass Felzenszwalb–Huttenlocher 3D EDT ──► 3D SDF (float32 + packed R8)
   │        (clamped to exterior air boundary so roof/wall caps always carry outward normals)
   ├──► 2. Central-Difference SDF Gradient + Multi-Offset AO ──► Smooth Normals + AO (RGBA8)
   ├──► 3. 3D RGB Edge Dilation (6-neighbor flood into α=0) ──► Halo-Free Albedo (RGBA8)
   └──► 4. Explicit / Warm-Luma Emissive Mask ──► Emissive 3D Texture (R8)

Key Details


4. The 4-Pass WebGL2 ES 3.00 Render Pipeline (packages/core/src/renderer.ts & shaders.ts)

Every frame executes cleanly in 4 deterministic passes using only standard WebGL2 ES 3.00 formats (RGBA8, R8, DEPTH_COMPONENT24) — zero float-FBO extensions required, ensuring identical behavior on iOS Safari, Android Chrome, and desktop GPUs:

flowchart LR
  P0["Pass 0: Terrain & Sky<br/>(Fullscreen Raymarch + Exact Water Bisection)"]
  P1["Pass 1: 6-DOF Entities<br/>(Back-Face OBB Proxies + RGSS DDA/SDF + gl_FragDepth)"]
  P2["Pass 2: 3D Ribbons<br/>(Depth-Tested Contrails & Dual Thruster Plumes)"]
  P3["Pass 3: 4-Pass 16-bit JFA<br/>(Object-ID SDF Outlines + Bloom + RenderStyle Grade)"]

  P0 -->|"Scene Color + Aux + Depth"| P1
  P1 -->|"Back-to-Front Alpha + Exact Depth"| P2
  P2 -->|"FBO Color + Aux (ObjID, Emis, Legacy, Cov)"| P3
  P3 -->|"Default Framebuffer"| OUT["Display Canvas"]

Pass 0: Decoupled Backdrop (transparent | solid | studio | optional terrain)

Pass 1: 6-DOF Anti-Aliased Entities (ENTITY_OBB_VS / ENTITY_OBB_FS)

Pass 2: Depth-Tested 3D Ribbons (RIBBON_VS / RIBBON_FS)

Pass 3: 16-Bit Packed RGBA8 JFA Outlines, Bloom & Premultiplied Composite (JFA_INIT_FS, JFA_STEP_FS, COMPOSITE_FS)

Standalone Engine Reference Shaders (shaders/)

Copy-paste single-quad 4× RGSS 3D Voxel DDA reference shaders for non-WebGL2 engines live directly in:


5. How the Live RenderStyle Softswitch Works

SceneDocument.style compiles to a single integer uniform (uStyle: 0=arcade-8bit, 1=hd-2d, 2=smooth-toy, 3=retro-raw) shared by TERRAIN_FS, ENTITY_OBB_FS, and COMPOSITE_FS:


6. Mobile-First Performance Architecture

Mobile browsers are treated as a primary target, not an afterthought:

  1. Auto Tier Detection (AASpriteRenderer): Detects coarse pointers ((pointer: coarse)) or compact viewports (< 760px) to select isMobile, capping DPR at 1.5×, RGSS hero samples at 4×, and terrain ray step multiplier at 1.35×.
  2. Dynamic Resolution Scaling (DRS) Governor: Tracks rolling CPU/submit frame time (rollingMs). If frame time exceeds 15.5 ms on mobile, drsScale steps gently down (floor 0.68); when headroom returns below 8.5 ms, it climbs back to 1.0.
  3. Power & Tab Conservation: Demos pair visibilitychange with content-visibility: auto + contentvisibilityautostatechange (with IntersectionObserver fallback) so off-screen or backgrounded canvases burn 0% GPU.
  4. Multi-Touch Ergonomics (packages/core/src/mobile.ts): createTouchController tracks independent pointerIds so a floating left-hand virtual thumbstick operates concurrently with right-hand BOOST / ROLL buttons (≥ 44×44 px touch targets, touch-action: none, env(safe-area-inset-*) notch clearance).