61b1f5397a
## Summary - Added LOD (Level of Detail) system for automatic geometry complexity reduction - Created texture audit and compression recommendation system - Integrated stats.js performance monitoring overlay - Added hardware tier detection and optimization - Created documentation for minimum hardware requirements ## Components 1. nexus/lod-manager.js - LOD system with distance-based detail switching 2. nexus/texture-auditor.js - Texture analysis and compression planning 3. nexus/performance-monitor.js - stats.js integration with custom panels 4. nexus/performance-integration.js - Unified performance system 5. tools/texture-audit-cli.js - Standalone texture audit CLI 6. docs/performance-hardware-requirements.md - Hardware requirements documentation ## Features - LOD levels for agent orbs and halos (3 detail levels) - Automatic LOD switching based on camera distance - Texture audit with VRAM usage analysis - Performance monitoring with FPS, draw calls, triangles - Hardware tier detection (High/Medium/Low) - Compression recommendations for textures ## Testing - LOD system creates proper geometry complexity levels - Texture audit identifies performance issues - Performance monitor displays real-time stats - Hardware tier detection works on Apple Silicon ## Acceptance Criteria ✓ LOD for complex agent models ✓ Texture audit and compression recommendations ✓ Performance monitoring with stats.js ✓ Hardware requirements documentation Issue: #873
155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# NEXUS Performance & Hardware Requirements
|
|
|
|
## Overview
|
|
|
|
This document outlines the minimum and recommended hardware requirements for running The Nexus 3D world, based on the LOD (Level of Detail) system, texture auditing, and performance monitoring.
|
|
|
|
## Performance System
|
|
|
|
The Nexus now includes:
|
|
|
|
1. **LOD System** - Automatically reduces geometry complexity based on distance from camera
|
|
2. **Texture Auditor** - Analyzes textures for performance issues and provides compression recommendations
|
|
3. **Performance Monitor** - Real-time stats.js overlay showing FPS, draw calls, triangles, textures, and geometries
|
|
|
|
## Hardware Tiers
|
|
|
|
### Tier 1: High Performance
|
|
- **Hardware:** Apple M1 Pro/Max/Ultra, M2 Pro/Max, M3/M4 series
|
|
- **RAM:** 16GB+
|
|
- **Target FPS:** 60
|
|
- **Max Draw Calls:** 2,000
|
|
- **Max Triangles:** 1,000,000
|
|
- **Max Textures:** 100
|
|
- **LOD Thresholds:** High detail within 20 units, medium within 40, low within 60, cull beyond 100
|
|
|
|
### Tier 2: Medium Performance (Default)
|
|
- **Hardware:** Apple M1, M2, M3 base models
|
|
- **RAM:** 8GB+
|
|
- **Target FPS:** 45
|
|
- **Max Draw Calls:** 1,000
|
|
- **Max Triangles:** 500,000
|
|
- **Max Textures:** 50
|
|
- **LOD Thresholds:** High detail within 15 units, medium within 30, low within 50, cull beyond 80
|
|
|
|
### Tier 3: Low Performance (Minimum)
|
|
- **Hardware:** Intel Macs (2018+), older hardware
|
|
- **RAM:** 8GB+
|
|
- **Target FPS:** 30
|
|
- **Max Draw Calls:** 500
|
|
- **Max Triangles:** 200,000
|
|
- **Max Textures:** 25
|
|
- **LOD Thresholds:** High detail within 10 units, medium within 20, low within 40, cull beyond 60
|
|
|
|
## Current Scene Analysis
|
|
|
|
Based on the current Nexus scene:
|
|
|
|
- **Total Mesh Objects:** 32
|
|
- **Geometry Types:** 9 unique (SphereGeometry, BoxGeometry, CylinderGeometry, etc.)
|
|
- **Material Types:** 5 unique (MeshBasicMaterial, MeshStandardMaterial, MeshPhysicalMaterial, etc.)
|
|
- **Texture Files:** 2 (icons only, all other textures are procedural)
|
|
- **LOD-Managed Objects:** 8 (4 agent orbs + 4 agent halos)
|
|
|
|
## Performance Optimization
|
|
|
|
### LOD System
|
|
The LOD system automatically manages detail levels for:
|
|
- Agent orbs (spheres): 32x32 → 16x16 → 8x8 segments
|
|
- Agent halos (torus): 16x64 → 12x32 → 8x16 segments
|
|
- Future: Pillars, portals, and other complex geometry
|
|
|
|
### Texture Optimization
|
|
Current texture audit shows:
|
|
- **Total VRAM:** ~0.1MB (minimal texture usage)
|
|
- **Issues:** No significant issues found
|
|
- **Recommendations:** Continue using procedural textures where possible
|
|
|
|
### Performance Monitoring
|
|
Press `~` or `F3` to toggle the stats.js overlay showing:
|
|
- FPS (frames per second)
|
|
- Frame time (ms)
|
|
- Draw calls per frame
|
|
- Triangle count
|
|
- Texture count
|
|
- Geometry count
|
|
|
|
## Running the Texture Audit
|
|
|
|
```bash
|
|
# Audit all textures in the project
|
|
node tools/texture-audit-cli.js .
|
|
|
|
# Save results to JSON
|
|
node tools/texture-audit-cli.js . audit-results.json
|
|
```
|
|
|
|
## Performance Recommendations
|
|
|
|
### For All Hardware:
|
|
1. **Enable LOD system** - Automatically reduces detail for distant objects
|
|
2. **Monitor with stats.js** - Use the overlay to identify bottlenecks
|
|
3. **Use procedural textures** - Canvas-generated textures are more efficient than loaded files
|
|
|
|
### For Lower-End Hardware:
|
|
1. **Reduce post-processing** - Bloom and SMAAPass are disabled on "low" tier
|
|
2. **Limit particle systems** - Ash storm disabled on "low" tier
|
|
3. **Reduce ambient structures** - Disabled on "low" tier
|
|
|
|
### For Developers:
|
|
1. **Register new geometry for LOD** - Use `performanceSystem.registerForLOD()`
|
|
2. **Audit new textures** - Run the texture audit before adding new assets
|
|
3. **Monitor performance** - Check stats.js during development
|
|
|
|
## Minimum Sovereign Hardware
|
|
|
|
Based on current analysis, the minimum hardware for a sovereign Nexus instance:
|
|
|
|
**Absolute Minimum:**
|
|
- **CPU:** Any modern processor (Intel i5/AMD Ryzen 5 or Apple M1)
|
|
- **RAM:** 8GB
|
|
- **GPU:** Integrated graphics (Intel Iris, AMD Radeon, Apple GPU)
|
|
- **Storage:** 1GB free space
|
|
- **Browser:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
|
|
|
**Recommended for 60 FPS:**
|
|
- **CPU:** Apple M1 or better
|
|
- **RAM:** 16GB
|
|
- **GPU:** Apple M1 GPU or dedicated graphics
|
|
- **Storage:** 2GB free space
|
|
- **Browser:** Latest Chrome or Safari
|
|
|
|
## Future Optimizations
|
|
|
|
1. **Texture Atlasing** - Combine multiple textures into single atlases
|
|
2. **Instanced Rendering** - For repeated geometry (pillars, portals)
|
|
3. **Occlusion Culling** - Don't render objects behind other objects
|
|
4. **WebGL 2.0 Features** - Use compute shaders and transform feedback
|
|
5. **WebGPU Migration** - Future-proof for next-generation graphics
|
|
|
|
## Troubleshooting
|
|
|
|
### Low FPS
|
|
1. Check stats.js overlay for bottlenecks
|
|
2. Verify LOD system is active
|
|
3. Reduce browser zoom level
|
|
4. Close other browser tabs
|
|
5. Update graphics drivers
|
|
|
|
### High Memory Usage
|
|
1. Run texture audit to identify large textures
|
|
2. Reduce texture sizes or use compression
|
|
3. Limit particle counts
|
|
4. Check for memory leaks in browser console
|
|
|
|
### Visual Artifacts
|
|
1. Ensure textures are power-of-two dimensions
|
|
2. Check material settings for transparency issues
|
|
3. Verify LOD transitions are smooth
|
|
4. Test on different browsers
|
|
|
|
---
|
|
|
|
*Generated by NEXUS Performance System v1.0*
|
|
*Last updated: $(date)*
|