@playerthree/colyseus#

@playerthree/colyseus — bind a Colyseus Room to a PlayerThree PlayerThreeMatch.

What the binding does (and nothing game-specific):

• onAuth: atomically claims a host authorization lease for this connection and match. Every inbound request and private delivery reauthorizes that lease; revocation closes the connection.
• routes MSG.call | stream | mandate | scopes | resolveApproval | controller | mint | tell to match.handleMessage with a size cap and an in-flight cap per client; replies on MSG.result, stream pushes on MSG.obs.
• fan-out of each team's view stream (match.onView / match.viewMessages): a keyframe on join or watch, then the structural deltas, each message encoded once and shared by every reader of that team. Each team's guarded view goes only to that team's owner clients and to spectators that chose to watch it (MSG.watch, rate limited per spectator token). Seat principals (agents) never receive views — only their own stream. A team's stream is subscribed (computed) only while some client watches it.
• view flow control, for every client: a client gets views about once per viewIntervalMs at most, and each batch is followed by a WebSocket ping: no further views until its pong shows the client has read up to there. A slow client then catches up with the deltas it missed in one batch, or with one keyframe when it fell more than a bounded batch behind, instead of backing up its socket until the transport's heartbeat drops it as unresponsive. Nothing else (join/watch keyframes, seats, results, stream pushes, reports, chat) is held back.
• pushes MSG.seats and MSG.cards (on join, on change) and MSG.report (once a team's outcome is decided).
• observer principals choose a granted perspective with MSG.observer and receive only its released observer frames; they get no views, seats or RPC.
• chat mode: routes owner messages and agent replies only to the exact owning human seat (or a trusted private team-root client), never to spectators, agents, opponents or another human role on the same team.
• cleans up subscriptions on leave and on dispose.

Wire it into your room's lifecycle hooks:

class MyRoom extends Room {
  playerThree!: PlayerThreeRoomBinding;
  onCreate(options) { this.playerThree = bindPlayerThreeRoom(this, { host, match: host.getMatch(options.matchId)! }); }
  onAuth(client, options) { return this.playerThree.onAuth(client, options); }
  onJoin(client, options) { this.playerThree.onJoin(client, options); }
  onLeave(client) { this.playerThree.onLeave(client); }
  onDispose() { this.playerThree.dispose(); }
}

Interfaces#

PlayerThreeHostPort#

Defined in: packages/colyseus/src/index.ts:86

The parts of a PlayerThreeHost the binding uses (every PlayerThreeHost<M> is assignable).

Methods#

authenticate()#

authenticate(token): 
  | {
  match: {
     id: string;
  };
  principal: Principal;
}
  | undefined;

Defined in: packages/colyseus/src/index.ts:87

Parameters#

Returns#

| { match: { id: string; }; principal: Principal; } | undefined

authorizeLease()#

authorizeLease(lease): Principal | undefined;

Defined in: packages/colyseus/src/index.ts:89

Parameters#

Returns#

Principal | undefined

claimToken()#

claimToken(token, connectionId): 
  | AuthorizationLease
  | undefined;

Defined in: packages/colyseus/src/index.ts:88

Parameters#

Returns#

| AuthorizationLease | undefined

disconnectLease()#

disconnectLease(lease): void;

Defined in: packages/colyseus/src/index.ts:90

Parameters#

Returns#

void

onLeaseRevoked()#

onLeaseRevoked(listener): () => void;

Defined in: packages/colyseus/src/index.ts:91

Parameters#

Returns#

() => void

PlayerThreeMatchPort#

Defined in: packages/colyseus/src/index.ts:61

The parts of a PlayerThreeMatch the binding uses, with teams as plain strings so any game's match fits (every PlayerThreeMatch<M> is assignable).

Properties#

Methods#

cards()#

cards(): PublicSeatCard[];

Defined in: packages/colyseus/src/index.ts:66

Returns#

PublicSeatCard[]

dispose()#

dispose(): void;

Defined in: packages/colyseus/src/index.ts:82

Returns#

void

handleMessage()#

handleMessage(
   principal, 
   msg, 
   push?
): Promise<ServerMsg | undefined>;

Defined in: packages/colyseus/src/index.ts:80

Parameters#

Returns#

Promise<ServerMsg | undefined>

humanJoined()#

humanJoined(
   team, 
   role, 
   joined
): void;

Defined in: packages/colyseus/src/index.ts:67

Parameters#

Returns#

void

observerMessages()#

observerMessages(
   principal, 
   perspective, 
   after?
): ObserverMessage[];

Defined in: packages/colyseus/src/index.ts:72

Parameters#

Returns#

ObserverMessage[]

onEnd()#

onEnd(listener): () => void;

Defined in: packages/colyseus/src/index.ts:77

Parameters#

Returns#

() => void

onSaid()?#

onSaid?(listener): () => void;

Defined in: packages/colyseus/src/index.ts:79

Agent replies per team (chat mode). Optional so older match implementations still fit.

Parameters#

Returns#

() => void

onView()#

onView(team, listener): () => void;

Defined in: packages/colyseus/src/index.ts:74

Subscribe to a team's view stream (computed only while subscribed); notified with each new version.

Parameters#

Returns#

() => void

outcome()#

outcome(team): Outcome;

Defined in: packages/colyseus/src/index.ts:70

Parameters#

Returns#

Outcome

readiness()#

readiness(): ReadinessSnapshot;

Defined in: packages/colyseus/src/index.ts:68

Returns#

ReadinessSnapshot

release()#

release(push): void;

Defined in: packages/colyseus/src/index.ts:81

Parameters#

Returns#

void

report()#

report(team): unknown;

Defined in: packages/colyseus/src/index.ts:71

Parameters#

Returns#

unknown

seats()#

seats(): SeatInfo[];

Defined in: packages/colyseus/src/index.ts:65

Returns#

SeatInfo[]

setHumanReady()#

setHumanReady(
   team, 
   role, 
   ready
): void;

Defined in: packages/colyseus/src/index.ts:69

Parameters#

Returns#

void

viewMessages()#

viewMessages(team, after?): ViewMessage[];

Defined in: packages/colyseus/src/index.ts:76

Messages bringing a reader at version after (undefined: fresh) up to date: missed deltas or one keyframe.

Parameters#

Returns#

ViewMessage[]

PlayerThreeRoomBinding#

Defined in: packages/colyseus/src/index.ts:131

The room-side handle: call these from the room's lifecycle hooks.

Methods#

dispose()#

dispose(): void;

Defined in: packages/colyseus/src/index.ts:141

Call from Room#onDispose. Idempotent.

Returns#

void

onAuth()#

onAuth(client, options): false | Principal;

Defined in: packages/colyseus/src/index.ts:133

Call from Room#onAuth. Returns the principal (becomes client.auth) or false to reject the join.

Parameters#

Returns#

false | Principal

onJoin()#

onJoin(client, options?): void;

Defined in: packages/colyseus/src/index.ts:135

Call from Room#onJoin. Human view: false suppresses views/reports; spectators cannot expand their scope.

Parameters#

Returns#

void

onLeave()#

onLeave(client): void;

Defined in: packages/colyseus/src/index.ts:137

Call from Room#onLeave (and onDrop if you do not allow reconnection).

Parameters#

Returns#

void

principal()#

principal(client): Principal | undefined;

Defined in: packages/colyseus/src/index.ts:139

Principal of a joined client.

Parameters#

Returns#

Principal | undefined

PlayerThreeRoomLike#

Defined in: packages/colyseus/src/index.ts:125

The parts of a Colyseus Room the binding uses. Structural, so rooms from another copy of @colyseus/core (e.g. a linked workspace) are accepted.

Properties#

Methods#

onMessage()#

onMessage(type, callback): unknown;

Defined in: packages/colyseus/src/index.ts:126

Parameters#

Returns#

unknown

PlayerThreeRoomOptions#

Defined in: packages/colyseus/src/index.ts:95

Options of bindPlayerThreeRoom.

Properties#

Functions#

bindPlayerThreeRoom()#

function bindPlayerThreeRoom(room, opts): PlayerThreeRoomBinding;

Defined in: packages/colyseus/src/index.ts:227

Binds room to opts.match: registers the PlayerThree message handlers and returns the lifecycle hooks to call (see the module example).

Parameters#

Returns#

PlayerThreeRoomBinding