tactical-shooter/docs/visuals-architecture.md

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 — 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