# Phase 3 — Visuals & Performance Architecture

## Scope
Art pass, baked lighting, performance profiling, LOD + occlusion culling for the competitive tactical shooter.
|
|## Dependency Chain (Kanban)
|
|```
|t_p3_artkit  (modular wall/floor kit + PBR materials 1K + art style guide)  ✅ DONE
|    └── t_p3_lighting  (LightmapGI baked lighting + reflection probes)
|           └── t_p3_profile  (perf budget + LOD + occlusion culling)
|```
|
|## Deliverables
|
|- **Art style guide**: [docs/art-style-guide.md](docs/art-style-guide.md) — visual direction, modular grid specs, material palette, mapping guidelines
|- **Modular kit scenes**: `client/assets/scenes/modular/` — 11 CSG-based wall/floor/structural pieces + kit_demo showcase scene
|- **PBR materials**: `client/assets/materials/` — 7 StandardMaterial3D .tres files
|- **1K textures**: `client/assets/textures/` — 28 procedural PBR maps (basecolor, normal, roughness, metallic × 7 materials)
|- **Project config**: `client/project.godot` — Godot 4 Forward+ renderer, 128-tick physics, LightmapGI defaults

## Art Style

- **Valorant-direction**, not AAA photorealistic
- Clean silhouettes, team-colored zones (CT/blue, T/red-orange)
- 1K PBR textures (base color, normal, roughness, metallic)
- CC0-licensed or custom-created assets

## Lighting Strategy

- LightmapGI for all static geometry
- Reflection probes at corridor junctions and open areas
- No SDFGI or real-time GI
- Lightmap texel density: 4-8 per unit walls/floors, 8-16 for focal surfaces

## Performance Budget

| Metric | Target |
|--------|--------|
| Frame time | 16ms (60fps) |
| GPU budget | 8ms |
| CPU budget | 6ms |
| Draw calls | 1500-2000 per frame |
| VRAM | 2GB texture pool |
| LOD0 tris/wall | 500-2000 |

## Deliverables (t_p3_profile — Performance Budget & Profiling)

### Performance Budget Document
- **docs/performance-budget.md** — full frame budget breakdown, LOD thresholds, occlusion culling specs, profiling methodology, and pass/fail criteria

### Visibility Ranges (CSG LOD equivalent)
All 11 modular kit scenes now have distance-based visibility ranges:
- Walls/endcaps: visible up to 50m (fade over 5m)
- Floors: visible up to 60m (fade over 10m)
- Pillars/beams: visible up to 30m (fade over 3m)
- Accent panels: visible up to 20m (fade over 2m)
- Doorway/window walls: visible up to 40m (fade over 5m)

These are the immediate optimization for CSG-based geometry. When maps are built from the modular kit, ~30-50% of distant pieces are automatically culled.

### Occlusion Culling
- **client/scripts/generate_occluders.gd** — `@tool` script that auto-generates OccluderInstance3D nodes from wall/pillar CSG geometry
- **Project settings** enable occlusion culling at 128^3 voxel resolution
- Expected benefit: 30-50% reduction in visible geometry on structured indoor maps

### Profiling Tools
- **client/scripts/profiling/profile_scene.gd** — standalone headless profiler that captures per-frame metrics (frame time, GPU time, draw calls, tris, VRAM) and evaluates against budget; produces CSV output + summary stats (P50/P95/P99)
- Usage: `godot --headless --script scripts/profiling/profile_scene.gd --scene res://tools/test_map.tscn`

### CSG → Mesh Baking Pipeline
- **client/scripts/convert_csg_to_mesh.gd** — `@tool` script that converts CSG nodes to MeshInstance3D with LOD slot framework, enabling traditional mesh LOD for the final optimization pass
- Collision shape preservation, visibility range inheritance

### Project Configuration
- Forward+ renderer explicitly configured
- Occlusion culling enabled (128^3 voxels, 6 rays/octant)
- LOD settings tuned for competitive FPS scales
- All costly post-processing disabled (SSAO, SSR, glow, volumetric fog, TAA)
- MSAA x2 + debanding for clean image at minimal GPU cost

## LOD Strategy

- 3 LOD levels per modular asset
- LOD1 at 15m (50% tris), LOD2 at 40m (25% tris), LOD3 at 80m
- Occlusion culling via OccluderInstance3D auto-generation

## Reference Hardware

- GTX 1050 / RX 560 class GPU (or integrated graphics)
- Godot Forward+ renderer