Colyseus Multiplayer Patterns for Starwards

Overview

Starwards uses Colyseus v0.15 for real-time multiplayer state synchronization. Understanding decorators, rooms, and state sync prevents bugs.

Core principle: State is the source of truth. Commands modify state. Clients receive automatic updates.

Architecture

Client (Browser)
  ↓ WebSocket connection
Room (Server)
  ↓ owns
State (Schema)
  ↓ syncs to
Client State (Mirror)

Flow:

Client sends command → Room
Room modifies State
Colyseus patches → Client
Client state updates automatically
UI reacts to state changes

The @gameField Decorator

Purpose: Marks properties for automatic Colyseus synchronization

Location:

modules/core/src/game-field.ts

Usage:

typescript

import { gameField } from '../game-field';

class Shield extends SystemState {
  // Primitive types
  @gameField('float32') strength = 1000;
  @gameField('float32') power = 1.0;
  @gameField('boolean') broken = false;

  // Nested Schema
  @gameField(ShieldDesign) design = new ShieldDesign();

  // Arrays
  @gameField([Emitter]) emitters = new ArraySchema<Emitter>();

  // Maps
  @gameField({ map: Target }) targets = new MapSchema<Target>();
}

Types:

```
'float32'
```
- 32-bit float (precision loss vs 64-bit number!)
```
'float64'
```
- 64-bit float
```
'int8'
```
,
```
'int16'
```
,
```
'int32'
```
- Signed integers
```
'uint8'
```
,
```
'uint16'
```
,
```
'uint32'
```
- Unsigned integers
```
'boolean'
```
- Boolean
```
'string'
```
- String
```
SchemaClass
```
- Nested Schema
```
[SchemaClass]
```
- Array of Schema
```
{map: SchemaClass}
```
- Map of Schema

Critical @gameField Rules

Rule 1: @gameField Must Be Last Decorator

typescript

// CORRECT order
@range([0, 1])           // 1st
@tweakable('number')     // 2nd
@gameField('float32')    // 3rd - LAST
power = 1.0;

// WRONG order
@gameField('float32')    // Can't be first
@range([0, 1])
power = 1.0;

Why: Decorators execute bottom-to-top. @gameField must wrap the final property.

Rule 2: Initialize Collections

typescript

// CORRECT
@gameField([Thruster])
thrusters = new ArraySchema<Thruster>();

@gameField({map: Spaceship})
ships = new MapSchema<Spaceship>();

// WRONG
@gameField([Thruster])
thrusters: ArraySchema<Thruster>;  // Not initialized!

Why: Colyseus needs instances, not undefined.

Rule 3: Use Correct Types

typescript

// CORRECT
@gameField('float32') speed = 0;      // 32-bit float
@gameField('int16') count = 0;        // 16-bit int

// WRONG
@gameField('number') speed = 0;       // No 'number' type
@gameField('float') speed = 0;        // No 'float' type (use float32/float64)

Why: Colyseus schema types are explicit.

Rule 4: Don't Sync Everything

typescript

// Only sync state that clients need
@gameField('float32') health = 100;   // ✅ Clients need this
@gameField('float32') damage = 10;    // ❌ Internal calculation, don't sync

// Derive internally
get damage() {
  return this.weapon.baseDamage * this.effectiveness;
}

Why: Less sync = better performance.

Float32 Precision Gotcha

Problem: JavaScript numbers are 64-bit, Colyseus

float32

is 32-bit

typescript

@gameField('float32') speed = 123.456789;
console.log(speed);  // 123.46 (precision lost!)

Solution: Use

toBeCloseTo()

in tests

typescript

// WRONG
expect(ship.speed).toBe(123.456789);

// CORRECT
expect(ship.speed).toBeCloseTo(123.46, 1);

State vs Non-State

State (synced):

typescript

class ShipState extends Schema {
  @gameField('float32') health = 100;   // Synced
  @gameField(Reactor) reactor!: Reactor;  // Synced
}

Non-State (server only):

typescript

class ShipManager {
  updateRate = 60;                      // Not synced
  lastUpdate = Date.now();              // Not synced

  update(dt: number) {
    this.state.health -= 10 * dt;       // Modify state → syncs
  }
}

Rule: Only Schema classes with @gameField sync. Plain properties don't sync.

Commands: Client → Server

Two patterns:

1. JSON Pointer (Dynamic)

Client:

typescript

room.send({
  type: '/Spaceship/ship-1/reactor/power',
  value: 0.8
});

Server (auto-handled in ShipRoom):

typescript

// No code needed - JSON Pointer auto-applies to state

Use when: Simple property updates, GM interface, debugging

2. Typed Commands (Optimized)

Define (in core):

typescript

export const setShieldPower: StateCommand<number, ShipState, void> = {
  cmdName: 'setShieldPower',
  setValue: (state, value) => {
    state.shield.power = value;
  }
};

Server (register in room):

typescript

this.onMessage(setShieldPower.cmdName, cmdReceiver(this.manager, setShieldPower));

Client (send):

typescript

const send = cmdSender(room, setShieldPower, undefined);
send(0.5);  // Type-safe!

Use when: High-frequency commands, complex validation, type safety

Room Architecture

AdminRoom

Purpose: Game management, map selection, start/stop

State:

AdminState

(has SpaceState)

Clients: GM interface, admin panel

Commands:

startGame

stopGame

loadMap

SpaceRoom

Purpose: Space-level gameplay, physics simulation

State:

SpaceState

(all space objects)

Clients: Tactical displays, overview screens

Managed by:

GameManager

SpaceManager

ShipRoom (per ship)

Purpose: Individual ship control

State:

ShipState

(ship systems)

Clients: Ship stations (weapons, engineering, etc.)

roomId: Equals

shipId

(

ship-0

ship-1

, etc.)

Commands: JSON Pointer only (for flexibility)

State Sync Patterns

Pattern 1: Server Modifies, Clients React

Server:

typescript

class ShieldManager {
  update(dt: number) {
    // Modify state → auto-syncs
    this.state.shield.strength += rechargeRate * dt;
  }
}

Client:

typescript

// Listen for changes
ship.state.shield.onChange(() => {
  updateUI(ship.state.shield.strength);
});

Pattern 2: Client Commands, Server Validates

Client:

typescript

// User adjusts power slider
powerSlider.on('change', (value) => {
  room.send({type: '/Spaceship/ship-0/reactor/power', value});
});

Server:

typescript

// Receives command, validates, applies
this.onMessage((client, message) => {
  const value = clamp(0, 1, message.value);  // Validate
  applyJsonPointer(this.state, message.type, value);  // Apply
  // Auto-syncs to all clients
});

Client:

typescript

// UI updates automatically from synced state
ship.state.reactor.listen('power', (value) => {
  powerSlider.value = value;
});

Pattern 3: Multiplayer Testing

Use
ShipTestHarness
:

typescript

import { ShipTestHarness } from './ship-test-harness';

test('client receives server state updates', async () => {
  const harness = new ShipTestHarness();
  await harness.connect();

  // Server modifies
  harness.shipManager.state.shield.strength = 750;

  // Wait for sync
  await harness.waitForSync();

  // Client receives
  expect(harness.shipDriver.state.shield.strength).toBe(750);

  await harness.cleanup();
});

Use
MultiClientDriver
:

typescript

import { MultiClientDriver } from '@starwards/server/test/multi-client-driver';

test('multiple clients see same state', async () => {
  const driver = new MultiClientDriver();
  await driver.start();

  const [c1, c2] = await Promise.all([
    driver.joinShip('ship-1'),
    driver.joinShip('ship-1')
  ]);

  // Modify server state
  driver.getShipManager('ship-1').state.shield.strength = 800;
  await driver.waitForSync();

  // Both clients updated
  expect(c1.state.shield.strength).toBe(800);
  expect(c2.state.shield.strength).toBe(800);

  await driver.cleanup();
});

See

docs/testing/UTILITIES.md

for full API.

Common Colyseus Pitfalls

Pitfall 1: Modifying State Without @gameField

typescript

// WRONG - doesn't sync
class Shield {
  strength = 1000;  // No decorator
}

// CORRECT - syncs
class Shield extends Schema {
  @gameField('float32') strength = 1000;
}

Pitfall 2: Setting Objects Instead of Properties

typescript

// WRONG - breaks references
state.velocity = {x: 10, y: 0};

// CORRECT - update properties
state.velocity.setValue({x: 10, y: 0});
// Or:
state.velocity.x = 10;
state.velocity.y = 0;

Why: Colyseus tracks property changes, not object replacement.

Pitfall 3: Forgetting await harness.waitForSync()

typescript

// WRONG - client not updated yet
harness.shipManager.state.health = 50;
expect(harness.shipDriver.state.health).toBe(50);  // FAILS

// CORRECT - wait for replication
harness.shipManager.state.health = 50;
await harness.waitForSync();
expect(harness.shipDriver.state.health).toBe(50);  // PASSES

Pitfall 4: Using State in Client-Side Logic

typescript

// WRONG - client shouldn't have business logic
if (ship.state.health < 50) {
  ship.state.broken = true;  // Don't modify from client
}

// CORRECT - send command, server decides
if (ship.state.health < 50) {
  room.send({type: 'checkBroken'});  // Server validates & applies
}

Why: Server is authoritative. Client is display only.

Pitfall 5: Float32 Precision in Tests

typescript

// WRONG - exact match fails
expect(ship.speed).toBe(123.456789);

// CORRECT - close enough
expect(ship.speed).toBeCloseTo(123.46, 1);

Pitfall 6: Not Cleaning Up Test Harness

typescript

// WRONG - leaves connections open
test('something', async () => {
  const harness = new ShipTestHarness();
  await harness.connect();
  // Test code
});  // MISSING cleanup()!

// CORRECT
test('something', async () => {
  const harness = new ShipTestHarness();
  await harness.connect();
  // Test code
  await harness.cleanup();  // Clean up
});

Debugging Colyseus Issues

1. Colyseus Monitor

http://localhost:2567/colyseus-monitor
Login: admin / admin

See:

Active rooms
Connected clients
State tree (live values)

2. Chrome DevTools Network Tab

WebSocket messages:

Open DevTools (F12)
Network tab → WS filter
Click connection
See Messages: commands sent, patches received

3. State Logging

Server:

typescript

console.log('[SERVER] Shield strength:', this.state.shield.strength);

Client:

typescript

console.log('[CLIENT] Shield strength:', ship.state.shield.strength);

Compare values to find sync issues.

4. JSON Pointer Path Validation

Test paths:

typescript

const path = '/Spaceship/ship-1/shield/power';
const obj = resolveJsonPointer(state, path);
console.log('Resolved:', obj);  // Should not be undefined

Performance Considerations

Minimize Sync Frequency

typescript

// WRONG - syncs 60 times/sec
update(dt: number) {
  this.state.position.x += velocity.x * dt;
  this.state.position.y += velocity.y * dt;
}

// BETTER - sync only when significant change
update(dt: number) {
  const newX = this.state.position.x + velocity.x * dt;
  const newY = this.state.position.y + velocity.y * dt;

  if (Math.abs(newX - this.state.position.x) > 0.1) {
    this.state.position.x = newX;
  }
  if (Math.abs(newY - this.state.position.y) > 0.1) {
    this.state.position.y = newY;
  }
}

But: Starwards updates are already optimized. Don't prematurely optimize.

Use Appropriate Types

typescript

// WRONG - wastes bandwidth
@gameField('float64') health = 100;  // 8 bytes

// CORRECT - sufficient precision
@gameField('float32') health = 100;  // 4 bytes

Batch Commands

typescript

// WRONG - multiple round trips
room.send({type: '/Spaceship/ship-0/reactor/power', value: 0.8});
room.send({type: '/Spaceship/ship-0/thrusters/0/enabled', value: true});
room.send({type: '/Spaceship/ship-0/thrusters/1/enabled', value: true});

// BETTER - single batch command
room.send('batchUpdate', {
  '/reactor/power': 0.8,
  '/thrusters/0/enabled': true,
  '/thrusters/1/enabled': true
});

But: Only if actually a bottleneck. JSON Pointer is fine for normal use.

Integration with Other Skills

starwards-tdd - Test state sync with harnesses
starwards-debugging - Debug sync issues with tools
starwards-verification - Verify multiplayer scenarios

Quick Reference

Task	Pattern
Add synced property	`@gameField('type') prop = value`
Nested Schema	`@gameField(Class) obj = new Class()`
Array	`@gameField([Class]) arr = new ArraySchema()`
Map	`@gameField({map: Class}) map = new MapSchema()`
Send command (client)	`room.send({type: '/path', value})`
Listen to changes (client)	`state.onChange(() => {})`
Test sync	`await harness.waitForSync()`
Debug state	Colyseus Monitor (port 2567)

The Bottom Line

Remember:

@gameField must be last decorator
State is source of truth (server authoritative)
Commands go client → server, patches go server → client
Use harnesses for multiplayer tests
Float32 has precision loss (use toBeCloseTo)
Clean up test connections (await cleanup())
When in doubt, check Colyseus Monitor

starwards-colyseus

NPX Install

Tags

SKILL.md Content

Colyseus Multiplayer Patterns for Starwards

Overview

Architecture

The @gameField Decorator

Critical @gameField Rules

Rule 1: @gameField Must Be Last Decorator

Rule 2: Initialize Collections

Rule 3: Use Correct Types

Rule 4: Don't Sync Everything

Float32 Precision Gotcha

State vs Non-State

Commands: Client → Server

1. JSON Pointer (Dynamic)

2. Typed Commands (Optimized)

Room Architecture

AdminRoom

SpaceRoom

ShipRoom (per ship)

State Sync Patterns

Pattern 1: Server Modifies, Clients React

Pattern 2: Client Commands, Server Validates

Pattern 3: Multiplayer Testing

Common Colyseus Pitfalls

Pitfall 1: Modifying State Without @gameField

Pitfall 2: Setting Objects Instead of Properties

Pitfall 3: Forgetting await harness.waitForSync()

Pitfall 4: Using State in Client-Side Logic

Pitfall 5: Float32 Precision in Tests

Pitfall 6: Not Cleaning Up Test Harness

Debugging Colyseus Issues

1. Colyseus Monitor

2. Chrome DevTools Network Tab

3. State Logging

4. JSON Pointer Path Validation

Performance Considerations

Minimize Sync Frequency

Use Appropriate Types

Batch Commands

Integration with Other Skills

Quick Reference

The Bottom Line