Debugging & Performance Tools
Hyperscape includes built-in debugging tools for monitoring performance, inspecting game state, and troubleshooting issues.FPS Debug Panel
Toggle with F5
Press F5 to toggle the FPS debug panel on/off:Panel Contents
The debug panel shows:- FPS - Frames per second (target: 60 FPS)
- Frame Time - Milliseconds per frame (target: <16.67ms)
- Memory Usage - Heap size and allocation rate
- Entity Count - Active entities in the world
- Network Stats - Ping, packet loss, bandwidth
Performance Targets
Console Logging
Debug Flags
Enable detailed logging for specific systems:Gathering Debug Output
WhenDEBUG_GATHERING = true:
Combat Debug Output
WhenDEBUG_COMBAT = true:
Network Debugging
WebSocket Inspector
Use browser DevTools to inspect WebSocket traffic:- Open DevTools (F12)
- Go to Network tab
- Filter by WS (WebSockets)
- Click the WebSocket connection
- View Messages tab
Common Messages
Performance Profiling
Chrome DevTools
- Open DevTools (F12)
- Go to Performance tab
- Click Record
- Perform actions in-game
- Stop recording
- Analyze flame graph
Key Areas to Profile
- Rendering - Three.js draw calls
- Physics - PhysX simulation
- Networking - WebSocket message processing
- ECS Systems - Entity updates
Common Bottlenecks
Entity Inspection
World Entity Query
Access the world object in console:System Inspection
Error Logging
Client Errors
Client errors are logged to console and can be reported:Server Errors
Server errors are logged with structured data:Testing Tools
Visual Testing Framework
Hyperscape uses real gameplay testing with Playwright:Screenshot Assertions
Related Documentation
- Development Guide - Setting up dev environment
- Testing Strategy - Writing tests
- Performance Optimization - Improving FPS
- Troubleshooting - Common issues