Skip to main content

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

When DEBUG_GATHERING = true:

Combat Debug Output

When DEBUG_COMBAT = true:

Network Debugging

WebSocket Inspector

Use browser DevTools to inspect WebSocket traffic:
  1. Open DevTools (F12)
  2. Go to Network tab
  3. Filter by WS (WebSockets)
  4. Click the WebSocket connection
  5. View Messages tab

Common Messages


Performance Profiling

Chrome DevTools

  1. Open DevTools (F12)
  2. Go to Performance tab
  3. Click Record
  4. Perform actions in-game
  5. Stop recording
  6. 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