the-nexus/docs/performance-hardware-requirements.md

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

# 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)