# Project: FreeExile Asset Campaign & Graphics Optimization Pipeline 2026

## Architecture
- **Asset Pipeline Architecture (`tools/asset_pipeline/`)**:
  - `animation_pipeline.py`: Master sprite and atlas generator. Produces albedo, tangent-space normal maps, and manifest JSON. (492 lines <= 500 cap).
  - `mipmap_utils.py`: Modular mipmap chain generator (Pillow Lanczos, PoT downsampling to 1x1).
  - `lod_generator.py`: Generates LOD-0 (100%), LOD-1 (50%), LOD-2 (25%) sprite sheets (empirical LOD-2 size: 2.38% - 18.46% <= 40%).
  - `texture_compressor.py`: Batch PNG to WebP compressor targeting >= 50% VRAM / disk savings (empirical size: 4.23% - 39.61% <= 50%).
  - `viewport_culling_utils.py`: Pure mathematical frustum / AABB intersection testing for isometric entities (10,000 entities in 44.8ms).
  - `design_pipeline_manager.py`: Two-stage technical and aesthetic QA gate scanner and reporter.
- **Client Graphics & Metal Engine**:
  - `monster_palette_instancing.metal`: GPU instancing shader rendering 200+ instances per draw call with 128-byte SIMD data and 2D palette LUT.
  - Draw call reduction: 50 on-screen entities batched into <= 8 draw calls (< 30 budget).
- **Server AoI & Network Sync**:
  - SpatialGrid-based AoI animation state broadcast filtering.
  - Bitmask delta compression for active animation states (93.1% bandwidth reduction).
  - HTTP ETag / 304 conditional request caching for asset manifests.
- **Design Requests (DRQ) Management**:
  - `docs/design_requests/inbox/`: 21 standardized DRQ files across all 6 departments.
  - `docs/design_requests/templates/DESIGN_REQUEST_TEMPLATE.md`: Canonical template with 9 metadata keys.

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | DRQ Inbox Standardization | 21 DRQs across 6 departments in `docs/design_requests/inbox/` | M1 | ORIGINAL_REQUEST §R1 |
| 2 | Design Pipeline Manager Validation | `design_pipeline_manager.py report` tracks >= 20 DRQs | M1 | ORIGINAL_REQUEST §R1, §R4 |
| 3 | Sprite LOD Generator | `tools/asset_pipeline/lod_generator.py` (LOD 100%, 50%, 25%, LOD-2 <= 40%) | M2 | ORIGINAL_REQUEST §R2 |
| 4 | WebP Texture Compressor | `tools/asset_pipeline/texture_compressor.py` (batch PNG -> WebP <= 50% size) | M2 | ORIGINAL_REQUEST §R2 |
| 5 | Viewport Culling Utility & Tests | `tools/asset_pipeline/viewport_culling_utils.py` with passing pytest tests | M2 | ORIGINAL_REQUEST §R2 |
| 6 | Sprite Mipmap Integration | Mipmap chain generator integrated into `animation_pipeline.py` via `mipmap_utils.py` | M2 | ORIGINAL_REQUEST §R2 |
| 7 | Metal GPU Instancing Guidance | 200+ instance draw call batching guidance in `monster_palette_instancing.metal` | M2 | ORIGINAL_REQUEST §R2 |
| 8 | Server AoI & Delta Compression Docs | AoI state filtering, delta compression, ETag caching in tech report | M2 | ORIGINAL_REQUEST §R2 |
| 9 | Rendering Optimization Tech Report | `docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md` (326 lines >= 300 lines + benchmarks) | M2 | ORIGINAL_REQUEST §R2 |
| 10 | Mob & Boss Animation Atlases | 6 states x 8 directions for 12 mobs + 2 bosses (albedo + normal + manifest) | M3 | ORIGINAL_REQUEST §R3 |
| 11 | 15 Skill Animation Atlases | 5 classes x 3 skills with 5-element color palettes (Kim, Mộc, Thủy, Hỏa, Thổ) | M3 | ORIGINAL_REQUEST §R3 |
| 12 | Combat VFX Particles | Hit impact particle, death dissolve VFX, damage number particle atlas | M3 | ORIGINAL_REQUEST §R3 |
| 13 | Passive Tree / Meridian Node Sprites | 5 node types + background constellation texture | M4 | ORIGINAL_REQUEST §R3 |
| 14 | Dungeon Tileset & Boss Arena Floors | Stone wall (4 vars), stone floor (4 vars), lava & bone arena floors | M4 | ORIGINAL_REQUEST §R3 |
| 15 | 5 New NPCs with Assets | >= 5 NPCs with avatar (128x128), standee (PoT), portrait (256x256) | M4 | ORIGINAL_REQUEST §R3 |
| 16 | 12 Canonical Currency Icons | 5 tiers Bloodstones, Bone Relics, Salvage Dust, 6 Crafting Orbs | M5 | ORIGINAL_REQUEST §R3 |
| 17 | Trade & Tooltip UI Panels | Trade/Bazaar UI panels, item tooltip frame, inventory equip slots | M5 | ORIGINAL_REQUEST §R3 |
| 18 | 6 Animated Status Effect Icons | Burn, Freeze, Stun, Poison, Bleed, Shock animated frame sets | M5 | ORIGINAL_REQUEST §R3 |
| 19 | Loading Screen & Parallax Banners | 1024x1024 full-bleed loading screen, 3 login parallax layers | M5 | ORIGINAL_REQUEST §R3 |
| 20 | Agent Orb Activation VFX | 3 tiers (Sơ Cấp, Trung Cấp, Vô Song) activation VFX | M5 | ORIGINAL_REQUEST §R3 |
| 21 | Automated QA Gate & Forensic Verification | Pass all 2^n, budget, B mean > 128, and pipeline audits | M6 | ORIGINAL_REQUEST §R4 |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| E2E | E2E Testing Track | TEST_INFRA.md, 28 tests in test_asset_campaign_and_pipeline_e2e.py, TEST_READY.md | none | DONE |
| M1 | DRQ Inbox Generation & Pipeline Audit | Generate 21 DRQs across 6 departments, verify with manager report | none | DONE |
| M2 | Graphics Cost-Reduction R&D & Tooling | lod_generator, texture_compressor, viewport_culling, mipmaps, tech report | none | DONE |
| M3 | Critical Asset Production (Atlases, Skills, VFX) | 12 mobs + 2 bosses atlases, 15 skill atlases, combat VFX | M2 | DONE |
| M4 | High Priority Asset Production (Passive, Maps, NPCs) | 5 passive nodes, dungeon & arena tiles, 5 NPCs | M2 | DONE |
| M5 | Medium & Low Asset Production (Currencies, UI, VFX) | Currencies, Trade UI, status effects, loading screen, parallax, orb VFX | M2 | DONE |
| M6 | QA Technical Gate, Verification & Acceptance | Pipeline report, 2^n audits, normal checks, tests, forensic audit | M1, M3, M4, M5 | DONE |

## Code Layout
- `tools/asset_pipeline/`:
  - `animation_pipeline.py` (492 lines <= 500 hard cap)
  - `mipmap_utils.py` (87 lines <= 350 cap)
  - `lod_generator.py` (155 lines <= 350 cap)
  - `texture_compressor.py` (161 lines <= 350 cap)
  - `viewport_culling_utils.py` (184 lines <= 350 cap)
  - `design_pipeline_manager.py` (<= 500 lines)
- `tests/unit/`:
  - `test_viewport_culling.py` (12 tests)
  - `test_asset_pipeline_tools.py` (14 tests)
  - `test_m3_critical_assets.py` (96 tests)
  - `test_m4_high_priority_assets.py` (47 tests)
  - `test_med_low_priority_assets.py` (48 tests)
  - `test_challenger_graphics_optimization_stress.py` (17 tests)
- `tests/e2e/`:
  - `test_asset_campaign_and_pipeline_e2e.py` (28 tests)
- `docs/design_requests/inbox/`:
  - 21 DRQ files across 6 departments
- `docs/research/`:
  - `RENDERING_OPTIMIZATION_TECH_REPORT.md` (326 lines >= 300 lines)
- `client/webapp/assets/`:
  - `animations/`: 14 mob/boss atlases (1024x1024 PoT, normal B mean > 246, manifest JSON)
  - `skills/`: 15 skill atlases with 5-element color palettes (512x512 PoT, normal B mean > 248)
  - `savage_vfx/`: 3 combat VFX + 3 agent orb VFX (512x512 & 256x256 PoT, normal B mean > 241, repaired atlas normal B mean = 250.58)
  - `ui/passive_tree/`: 5 node sprites + constellation background (1024x1024)
  - `map/`: 4 dungeon walls + 4 dungeon floors + 2 arena floors with normal maps
  - `characters/`: 5 new NPCs (avatar, portrait, standee, standee normal)
  - `currencies/`: 12 canonical currencies + normal maps + composite atlases
  - `ui/`: trade panel, tooltip frame, inventory equip slots
  - `ui/status_effects/`: 6 animated status effects
  - `loading/`: 1024x1024 loading screen
  - `banners/`: 3 login parallax layers