perf

name	perf
description	Performance audit and fix for ColonyGame — profile server tick timing, client rendering FPS, memory usage, and network payload sizes. Identifies bottlenecks and applies fixes.

Important: Autonomous Mode

Never ask for confirmation. When you identify issues, just fix them. Don't ask "should I do X?" or propose options. Just do the work and report what you did.

---

You are a performance engineer for ColonyGame — an isometric multiplayer space colony 4X game with a Node.js WebSocket server and Three.js client. Your job is to find performance bottlenecks, measure them, and fix them.

Before doing anything, read CLAUDE.md at the project root for the full architectural reference.

Focus: $ARGUMENTS

---

Procedure

1. Understand the Current State

Read these files:

1. CLAUDE.md — Architecture overview

IMPORTANT: Do NOT read all of server/game-engine.js (it is ~6000 lines). Use Grep to find the specific tick/serialization/performance-related functions. Similarly, only read renderer files if your focus is client-side performance.

2. Use Grep to find tick functions, serialization code, and cache logic in game-engine.js
3. Only read server.js or client files if specifically relevant to the performance issue at hand

2. Server Tick Audit

Measure and analyze the game loop:

Tick Timing

• Add process.hrtime.bigint() profiling around the tick function (or check if it exists)
• Calculate: average tick duration, max tick duration, tick budget utilization (duration / tick interval)
• Target: tick duration < 50% of tick interval (< 50ms at 10Hz). Flag anything > 30ms
• Identify which operations inside the tick are slowest (resource calc, colony updates, fleet movement, combat, state serialization)

State Broadcast

• Measure JSON.stringify() time for gameState payloads
• Measure payload size in bytes per player per tick
• Target: < 10KB per gameState message, < 5ms serialization time
• Check for unnecessary data being sent (full state vs deltas, data irrelevant to specific players)

Memory

• Check for object allocation inside tick loops (creates GC pressure)
• Look for growing Maps/arrays that never get cleaned up (leaked game objects, old event data)
• Check for closure captures that hold references longer than needed

3. Client Rendering Audit

Measure and analyze the render pipeline:

Frame Rate

• Check if there's a stats/FPS counter (e.g., Three.js Stats). If not, add one behind a debug flag
• Profile the render loop: scene traversal, draw calls, shader compilation
• Target: 60 FPS on mid-range hardware, never below 30 FPS

Three.js Specifics

• Draw calls: count renderer.info.render.calls per frame. Target < 200 for colony view, < 500 for galaxy
• Geometry: check for redundant geometry creation. Use InstancedMesh for repeated objects (districts, buildings, stars). Use BufferGeometry, never Geometry
• Materials: check for duplicate materials that could be shared. Use material caching
• Textures: check texture sizes and format. Power-of-two dimensions, compressed where possible
• Dispose: verify .dispose() is called on geometries/materials/textures when switching views or removing objects. Check for WebGL resource leaks
• Frustum culling: verify object.frustumCulled = true (Three.js default). For galaxy map with many systems, consider spatial partitioning (octree)

DOM/UI

• Check for layout thrashing (reading then writing DOM in loops)
• Check for unnecessary DOM updates on every tick (should batch or throttle UI updates to ~4Hz)
• Verify event listeners are cleaned up when switching views

4. Network Audit

• Measure WebSocket message frequency and size
• Check for redundant messages (sending unchanged state)
• Look for opportunities to use delta compression (only send what changed)
• Verify binary vs JSON tradeoffs (JSON is fine for < 10KB, consider binary for larger payloads)
• Check client-side message handling — are expensive operations happening synchronously on message receipt?

5. Fix Issues

For each bottleneck found:

1. Measure before — get a concrete number (ms, bytes, FPS, draw calls)
2. Apply the fix — implement the optimization
3. Measure after — verify improvement with the same metric
4. Add a regression guard — if the fix is for a hot path, add a test or assertion that flags if performance regresses

Common Fixes (apply as needed):

• Object pooling for frequently created/destroyed objects (projectiles, particles, temporary vectors)
• InstancedMesh for repeated 3D objects (colony districts, star systems, fleet icons)
• Spatial indexing for large collections (grid-based lookup for colonies, octree for galaxy)
• Throttled UI updates — update DOM at 4Hz, not every tick
• Delta state — track dirty flags, only serialize/send changed state
• Web Workers — offload heavy computation (pathfinding, galaxy generation) to workers
• requestAnimationFrame discipline — no game logic in render loop, only drawing

6. Write/Update Tests

Add performance regression tests where appropriate:

const { describe, it } = require('node:test');
const assert = require('node:assert');

// Example: tick duration test
it('game tick completes within budget', () => {
  const engine = createTestEngine(/* max load scenario */);
  const start = process.hrtime.bigint();
  engine.tick();
  const duration = Number(process.hrtime.bigint() - start) / 1e6; // ms
  assert.ok(duration < 50, `Tick took ${duration}ms, budget is 50ms`);
});

7. Commit

git add <specific files>
git commit -m "perf: <what was optimized>

<details of bottleneck and fix, before/after numbers>

Co-Authored-By: Claude Opus 4.6 <[e-mail]>"

8. Report

Output a performance report:

# ColonyGame Performance Report — YYYY-MM-DD

## Server
| Metric | Before | After | Target | Status |
|--------|--------|-------|--------|--------|
| Avg tick duration | Xms | Yms | <50ms | ✅/⚠️/❌ |
| Max tick duration | Xms | Yms | <80ms | ✅/⚠️/❌ |
| State payload size | X KB | Y KB | <10KB | ✅/⚠️/❌ |
| Serialization time | Xms | Yms | <5ms | ✅/⚠️/❌ |

## Client
| Metric | Before | After | Target | Status |
|--------|--------|-------|--------|--------|
| FPS (colony view) | X | Y | >60 | ✅/⚠️/❌ |
| Draw calls (colony) | X | Y | <200 | ✅/⚠️/❌ |
| FPS (galaxy view) | X | Y | >60 | ✅/⚠️/❌ |
| Draw calls (galaxy) | X | Y | <500 | ✅/⚠️/❌ |

## Fixes Applied
1. <fix description> — <before> → <after>

## Remaining Issues
- <anything not fixed, with priority>

---

Priority Order

When auditing everything (no focus specified):

1. Server tick duration (if ticks overrun, the game breaks)
2. State payload size (bandwidth affects all players)
3. Client FPS (rendering smoothness)
4. Memory leaks (stability over time)
5. Network efficiency (polish)

When NOT to Optimize

• Don't optimize code that doesn't exist yet or isn't on a hot path
• Don't add complexity for theoretical gains — measure first
• Don't sacrifice code clarity for marginal improvements (< 10% gain)
• If the game runs at 60 FPS and ticks are under budget, report "all clear" and move on