b3c97e0d6c
- Agent orbs: THREE.LOD with 3 detail levels (32/16/8 segments) - Halo geometry: reduced from 64 to 24 segments - Particle systems: LOD-aware counts (500-1500 based on tier) - Agent label texture cache: reuse textures across agents - Stats.js integration for performance monitoring - Document minimum sovereign hardware requirements Refs #873
102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# Three.js LOD and Texture Audit — Issue #873
|
||
|
||
## Audit Summary
|
||
|
||
**Date:** 2026-04-13
|
||
**Issue:** #873 — Three.js LOD and Texture Audit for Local Hardware
|
||
**Target:** 60fps on base M1 Mac (8-core CPU, 7-core GPU, 8GB RAM)
|
||
|
||
## Changes Made
|
||
|
||
### 1. Agent LOD Implementation
|
||
|
||
**Before:** All agent orbs used `SphereGeometry(0.4, 32, 32)` regardless of distance.
|
||
**After:** Implemented `THREE.LOD` with three detail levels:
|
||
|
||
| Distance | Geometry | Segments | Triangles |
|
||
|----------|----------|----------|-----------|
|
||
| 0-15 units | High | 32x32 | ~2,048 |
|
||
| 15-30 units | Medium | 16x16 | ~512 |
|
||
| 30+ units | Low | 8x8 | ~128 |
|
||
|
||
**Impact:** ~75% triangle reduction for distant agents (4 agents × 3 levels).
|
||
|
||
### 2. Halo Geometry Optimization
|
||
|
||
**Before:** `TorusGeometry(0.6, 0.02, 16, 64)` — 64 segments
|
||
**After:** Reduced to 24 segments (12 on low-tier)
|
||
|
||
**Impact:** ~62% vertex reduction per halo.
|
||
|
||
### 3. Agent Label Texture Cache
|
||
|
||
**Before:** Each agent created its own CanvasTexture.
|
||
**After:** Implemented texture cache keyed by `name_color`. Reuses textures for agents with same name/color.
|
||
|
||
**Impact:** Reduced texture memory and GPU uploads.
|
||
|
||
### 4. Particle System LOD
|
||
|
||
| Tier | Main Particles | Dust Particles | Total |
|
||
|------|----------------|----------------|-------|
|
||
| High | 1,500 | 500 | 2,000 |
|
||
| Medium | 1,000 | 300 | 1,300 |
|
||
| Low | 500 | 150 | 650 |
|
||
|
||
**Impact:** 67% particle reduction on low-tier hardware.
|
||
|
||
### 5. Post-Processing Tiering
|
||
|
||
| Setting | High | Medium | Low |
|
||
|---------|------|--------|-----|
|
||
| Bloom Strength | 0.6 | 0.35 | 0.35 |
|
||
| Shadow Map | 2048px | 1024px | 512px |
|
||
| Pixel Ratio | 2x | devicePR | 1x |
|
||
|
||
### 6. Stats.js Integration
|
||
|
||
Added `three/addons/libs/stats.module.js` for real-time performance monitoring.
|
||
|
||
**Access:** `window.stats` in browser console. Shows FPS, render time, and draw calls.
|
||
|
||
## Minimum Sovereign Hardware Requirements
|
||
|
||
### Tier: Low (Target: 30fps)
|
||
- **CPU:** 4+ cores (Intel i5 / Apple M1 / AMD Ryzen 3)
|
||
- **GPU:** Integrated (Intel UHD 630 / Apple M1)
|
||
- **RAM:** 4GB
|
||
- **Browser:** Chrome 90+, Firefox 88+, Safari 15+
|
||
|
||
### Tier: Medium (Target: 45fps)
|
||
- **CPU:** 6+ cores (Intel i7 / Apple M1 Pro / AMD Ryzen 5)
|
||
- **GPU:** Entry discrete (GTX 1050 / Apple M1 Pro 14-core)
|
||
- **RAM:** 8GB
|
||
- **Browser:** Latest versions
|
||
|
||
### Tier: High (Target: 60fps)
|
||
- **CPU:** 8+ cores (Intel i9 / Apple M1 Max / AMD Ryzen 7)
|
||
- **GPU:** Mid-range discrete (RTX 3060 / Apple M1 Max 24-core)
|
||
- **RAM:** 16GB
|
||
- **Browser:** Latest versions
|
||
|
||
## Performance Validation Checklist
|
||
|
||
- [ ] Stats.js overlay showing 60fps with 5+ agents
|
||
- [ ] Draw calls < 100 per frame
|
||
- [ ] Triangle count < 500k per frame
|
||
- [ ] Texture memory < 256MB
|
||
- [ ] No frame spikes > 16.6ms (60fps budget)
|
||
|
||
## Future Optimizations
|
||
|
||
1. **Instanced Rendering:** Use `InstancedMesh` for repeated geometries (portals, runestones)
|
||
2. **Texture Atlasing:** Combine agent label textures into single atlas
|
||
3. **Basis/KTX2:** Compress textures with Basis Universal
|
||
4. **WebGL2 Compute:** Offload particle updates to compute shaders
|
||
5. **Occlusion Culling:** Implement for interior spaces
|
||
|
||
## Files Modified
|
||
|
||
- `app.js` — Agent LOD, particle optimization, stats.js integration
|
||
- `PERFORMANCE_AUDIT_873.md` — This document
|