319ea08b24
- Add performance-monitor.js: stats.js overlay with FPS, frame time, draw calls, and agent LOD stats. Toggle with Shift+P. - Add lod-system-enhanced.js: THREE.LOD integration with tier-based mesh simplification (high/mid/low PBR materials), billboard sprites, frustum culling, and automatic performance tier detection. - Add texture-optimizer.js: WebP conversion, texture size limits by tier, mipmap control, memory budget tracking, and scene audit. - Add performance-benchmark.js: automated 10s benchmark with report generation and hardware requirement validation. - Add docs/MINIMUM_SOVEREIGN_HARDWARE.md: performance tiers, draw call budgets, and M1 Mac baseline requirements. - Update app.js: integrate PerformanceMonitor.update in game loop, pass renderer to LODSystem.init(). - Update index.html: include new performance scripts. Acceptance criteria: ✓ LOD for complex agent models (4 levels: high/mid/low/sprite) ✓ Texture audit utilities with compression recommendations ✓ Performance overlay showing frame times and draw calls ✓ Minimum sovereign hardware documentation Closes #873
132 lines
4.0 KiB
Markdown
132 lines
4.0 KiB
Markdown
# Minimum Sovereign Hardware Requirements
|
|
|
|
## The Nexus — Three.js Performance Baseline
|
|
|
|
**Document:** Performance audit for local-first deployment
|
|
**Target:** 60 FPS sustained with 5+ agent presences
|
|
**Reference Hardware:** Apple M1 Mac Mini (2020), 8GB RAM
|
|
|
|
---
|
|
|
|
## Performance Tiers
|
|
|
|
| Tier | Hardware | Target | Max Agents | Shadows | Pixel Ratio | Notes |
|
|
|------|----------|--------|------------|---------|-------------|-------|
|
|
| **Low** | Mobile / Integrated GPU | 30 FPS | 10 | Off | 1.0 | iPhone, Intel UHD |
|
|
| **Medium** | M1 Mac / Mid-range | **60 FPS** | 25 | Basic | 1.5 | **Baseline standard** |
|
|
| **High** | M2+/Dedicated GPU | 60+ FPS | 50+ | Soft PCF | 2.0 | Desktop workstations |
|
|
|
|
## Minimum Requirements (Sovereign Standard)
|
|
|
|
To run The Nexus locally without cloud dependency:
|
|
|
|
| Component | Minimum | Recommended |
|
|
|-----------|---------|-------------|
|
|
| **CPU** | Apple M1 / AMD Ryzen 5 3600 | Apple M2 Pro / AMD Ryzen 7 5800X |
|
|
| **RAM** | 8 GB | 16 GB |
|
|
| **GPU** | Apple M1 GPU (8-core) | Apple M2 Pro GPU (16-core) |
|
|
| **Storage** | 2 GB free | 5 GB free |
|
|
| **Browser** | Chrome 120+, Safari 17+, Firefox 121+ | Chrome 120+ |
|
|
| **WebGL** | WebGL 2.0 | WebGL 2.0 |
|
|
|
|
## Performance Optimizations Applied
|
|
|
|
### 1. Level of Detail (LOD)
|
|
- **Near (< 15m):** Full PBR mesh (32-segment sphere)
|
|
- **Mid (15-40m):** Simplified mesh (16-segment sphere)
|
|
- **Far (40-80m):** Low-poly mesh (8-segment sphere)
|
|
- **Distant (> 80m):** Billboard sprite with additive blending
|
|
- **Culled:** Agents beyond 120m or outside frustum hidden
|
|
|
|
### 2. Texture Optimization
|
|
- Max texture size: 1024px (medium tier)
|
|
- WebP format recommended for all textures
|
|
- Mipmaps enabled on medium+ tiers only
|
|
- Canvas-generated labels use `generateMipmaps: false`
|
|
|
|
### 3. Renderer Settings by Tier
|
|
|
|
```javascript
|
|
// Low (mobile/integrated)
|
|
renderer.setPixelRatio(1);
|
|
renderer.shadowMap.enabled = false;
|
|
renderer.toneMapping = THREE.NoToneMapping;
|
|
|
|
// Medium (M1 Mac baseline)
|
|
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5));
|
|
renderer.shadowMap.enabled = true;
|
|
renderer.shadowMap.type = THREE.BasicShadowMap;
|
|
|
|
// High (dedicated GPU)
|
|
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
|
|
renderer.shadowMap.enabled = true;
|
|
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
|
|
```
|
|
|
|
### 4. Draw Call Budget
|
|
|
|
| Scene Element | Draw Calls | Optimization |
|
|
|---------------|------------|--------------|
|
|
| Skybox | 1 | Shader-based, no texture |
|
|
| Floor | 1 | Single mesh |
|
|
| Agent (near) | 2 | Mesh + label |
|
|
| Agent (far) | 1 | Sprite only |
|
|
| Portals | 1-3 | Depends on complexity |
|
|
| **Total target** | **< 100** | With 5 agents |
|
|
|
|
## Benchmarking
|
|
|
|
Run the built-in benchmark:
|
|
|
|
```javascript
|
|
// In browser console
|
|
PerformanceBenchmark.run(10000); // 10-second test
|
|
PerformanceBenchmark.downloadReport(); // Save markdown report
|
|
```
|
|
|
|
### Expected Results (M1 Mac, 5 agents)
|
|
|
|
| Metric | Minimum | Target |
|
|
|--------|---------|--------|
|
|
| Average FPS | 45 | 60 |
|
|
| Frame Time | 22ms | 16.7ms |
|
|
| Draw Calls | < 150 | < 100 |
|
|
| Memory | < 128MB | < 100MB |
|
|
|
|
## Verification Checklist
|
|
|
|
Before deploying to sovereign hardware:
|
|
|
|
- [ ] Run benchmark with 5+ agents visible
|
|
- [ ] Confirm sustained 60 FPS for 10+ seconds
|
|
- [ ] Verify draw calls remain under 150
|
|
- [ ] Check memory usage stays under 128MB
|
|
- [ ] Test on target hardware (not just development machine)
|
|
- [ ] Validate LOD transitions are smooth
|
|
- [ ] Confirm crisis protocol works at all LOD levels
|
|
|
|
## Troubleshooting
|
|
|
|
### FPS Below 60 on M1
|
|
|
|
1. Check `PerformanceMonitor` (Shift+P) for draw calls
|
|
2. Reduce `LODSystem` thresholds: `LODSystem.forceTier('low')`
|
|
3. Disable post-processing effects
|
|
4. Reduce agent count or draw distance
|
|
|
|
### High Memory Usage
|
|
|
|
1. Run `TextureOptimizer.auditScene(scene)`
|
|
2. Check for uncompressed textures
|
|
3. Reduce texture size limits: `TextureOptimizer.SIZE_LIMITS.medium = 512`
|
|
|
|
### Stuttering
|
|
|
|
1. Check for garbage collection pauses
|
|
2. Reduce object creation in render loop
|
|
3. Enable `renderer.info.autoReset = false` and manual reset
|
|
|
|
---
|
|
|
|
*Sovereignty and service always.*
|