the-nexus/docs/MINIMUM_SOVEREIGN_HARDWARE.md

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

// 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:

// 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.