playerthree#

playerthree: the game-agnostic contract — schema DSL, manifest and definition types, control plane, protocol messages, team signals, the outbound guard, briefing/surface hash, skills and topics. Runtime pieces live under subpaths (playerthree/host, /mcp, /policy, /devtools, /postgres, …).

Classes#

PlayerThreeError#

Defined in: packages/playerthree/src/host/util.ts:9

The only error the control plane throws on purpose. Carries a closed code and no text, so bindings can forward it verbatim; anything else is an internal failure and must be reported as internal.

Extends#

• Error

Constructors#

Constructor#

new PlayerThreeError(code): PlayerThreeError;

Defined in: packages/playerthree/src/host/util.ts:11

Parameters#

Returns#

PlayerThreeError

Overrides#

Error.constructor

Properties#

Interfaces#

AuthorizationLease#

Defined in: packages/playerthree/src/host/types.ts:184

One transport connection's claim on a credential (claimToken); re-checked with authorizeLease on every request.

Properties#

BriefingTopic#

Defined in: packages/playerthree/src/topics.ts:22

Properties#

ChatEntry#

Defined in: packages/playerthree/src/host/types.ts:921

Properties#

CommanderAgent#

Defined in: packages/playerthree/src/host/types.ts:944

Agent-rights access to one commander that is not bound to its commander token (e.g. an OAuth connection).

Properties#

Methods#

active()#

active(): boolean;

Defined in: packages/playerthree/src/host/types.ts:950

Recent calls, in-flight work, or a running sequence keep this commander active.

Returns#

boolean

drain()#

drain(): OwnerMessage[];

Defined in: packages/playerthree/src/host/types.ts:952

Read (and clear) unread owner messages (chat mode), in the lobby or the live seat.

Returns#

OwnerMessage[]

reportUsage()#

reportUsage(report): void;

Defined in: packages/playerthree/src/host/types.ts:947

Parameters#

Returns#

void

seat()#

seat(): 
  | {
  match: string;
  role: string;
  team: string;
}
  | null;

Defined in: packages/playerthree/src/host/types.ts:954

The live match seating the commander, or null (lobby).

Returns#

| { match: string; role: string; team: string; } | null

status()#

status(): SeatStatus;

Defined in: packages/playerthree/src/host/types.ts:948

Returns#

SeatStatus

CommanderIdentity#

Defined in: packages/playerthree/src/host/types.ts:787

Extended by#

• CommanderStatus
• StoredCommander

Properties#

CommanderLogContext#

Defined in: packages/playerthree/src/host/types.ts:117

What the game stamps into each new entry before it is digested and signed.

Properties#

CommanderLogEntry#

Defined in: packages/playerthree/src/commander-log.ts:63

The signed entry: what verifiers and public projections see.

Properties#

CommanderLogHead#

Defined in: packages/playerthree/src/commander-log.ts:161

Chain head and casual tally (non-practice decided entries) of one commander.

Properties#

CommanderLogOptions#

Defined in: packages/playerthree/src/host/types.ts:128

Commander match log settings (PlayerThreeHostOptions.commanderLog).

Properties#

Methods#

verdict()?#

verdict?(context): 
  | CommanderLogVerdict
| Promise<CommanderLogVerdict>;

Defined in: packages/playerthree/src/host/types.ts:138

The game's rating decision for one entry (default: unrated). A failure stamps the default and is reported.

Parameters#

Returns#

| CommanderLogVerdict | Promise<CommanderLogVerdict>

CommanderLogReader#

Defined in: packages/playerthree/src/host/types.ts:153

Read side of the commander log (operators and the game; owner views go through CommanderRegistry.log).

Properties#

Methods#

all()#

all(): Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/host/types.ts:159

Returns#

Promise<StoredCommanderLogEntry[]>

amend()#

amend(
   entryId, 
   verdict, 
   reason
): Promise<CommanderLogVerdictRow>;

Defined in: packages/playerthree/src/host/types.ts:162

Append a signed verdict change (a review void) for an entry; never rewrites the entry.

Parameters#

Returns#

Promise<CommanderLogVerdictRow>

entries()#

entries(commanderId, afterSeq?): Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/host/types.ts:157

Parameters#

Returns#

Promise<StoredCommanderLogEntry[]>

flush()#

flush(): Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:166

Resolves once queued log writes finished.

Returns#

Promise<void>

match()#

match(matchId): Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/host/types.ts:158

Parameters#

Returns#

Promise<StoredCommanderLogEntry[]>

onAppend()#

onAppend(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:164

After each durable append. Returns unsubscribe.

Parameters#

Returns#

() => void

verdicts()#

verdicts(): Promise<CommanderLogVerdictRow[]>;

Defined in: packages/playerthree/src/host/types.ts:160

Returns#

Promise<CommanderLogVerdictRow[]>

CommanderLogSealed#

Defined in: packages/playerthree/src/commander-log.ts:135

Private facts, owner-only; scrubbed (set to null) by a deletion tombstone.

Properties#

CommanderLogSeatRef#

Defined in: packages/playerthree/src/commander-log.ts:39

A seat of the match as observed at the end: who held it and of what kind.

Properties#

CommanderLogStore#

Defined in: packages/playerthree/src/commander-log.ts:174

Storage behind the commander log. Every method may be sync or async; the host issues writes in order. Insert only: redact (privacy tombstone) is the one rewrite, and it touches only the sealed part.

Methods#

all()#

all(): 
  | StoredCommanderLogEntry[]
| Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/commander-log.ts:182

Every entry in (endedAt, matchId, commander) order: deterministic recomputes.

Returns#

| StoredCommanderLogEntry[] | Promise<StoredCommanderLogEntry[]>

append()#

append(row): void | Promise<void>;

Defined in: packages/playerthree/src/commander-log.ts:176

Parameters#

Returns#

void | Promise<void>

appendVerdict()#

appendVerdict(row): void | Promise<void>;

Defined in: packages/playerthree/src/commander-log.ts:183

Parameters#

Returns#

void | Promise<void>

entries()#

entries(commanderId, afterSeq?): 
  | StoredCommanderLogEntry[]
| Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/commander-log.ts:178

One commander's entries in seq order, after afterSeq (exclusive); limit newest-first trimming is the caller's.

Parameters#

Returns#

| StoredCommanderLogEntry[] | Promise<StoredCommanderLogEntry[]>

heads()#

heads(): 
  | CommanderLogHead[]
| Promise<CommanderLogHead[]>;

Defined in: packages/playerthree/src/commander-log.ts:175

Returns#

| CommanderLogHead[] | Promise<CommanderLogHead[]>

match()#

match(matchId): 
  | StoredCommanderLogEntry[]
| Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/commander-log.ts:180

Every commander's entry for one match.

Parameters#

Returns#

| StoredCommanderLogEntry[] | Promise<StoredCommanderLogEntry[]>

redact()#

redact(commanderId): void | Promise<void>;

Defined in: packages/playerthree/src/commander-log.ts:185

Parameters#

Returns#

void | Promise<void>

verdicts()#

verdicts(): 
  | CommanderLogVerdictRow[]
| Promise<CommanderLogVerdictRow[]>;

Defined in: packages/playerthree/src/commander-log.ts:184

Returns#

| CommanderLogVerdictRow[] | Promise<CommanderLogVerdictRow[]>

CommanderLogUsage#

Defined in: packages/playerthree/src/commander-log.ts:52

Properties#

CommanderLogVerdict#

Defined in: packages/playerthree/src/commander-log.ts:25

The game's rating decision, stamped into the entry before it is digested and signed (commanderLog.verdict).

Properties#

CommanderLogVerdictRow#

Defined in: packages/playerthree/src/commander-log.ts:151

A later verdict change (a review void): appended, never rewriting the entry.

Properties#

CommanderPolicyVersion#

Defined in: packages/playerthree/src/host/types.ts:812

Properties#

CommanderPractice#

Defined in: packages/playerthree/src/host/types.ts:827

Closed-vocabulary summary of the last practice run (UI or agent).

Properties#

CommanderRegistry#

Defined in: packages/playerthree/src/host/types.ts:862

Persistent commander rosters. All methods take an owner id the game has already authenticated. Unknown owners/commander IDs and invalid settings throw PlayerThreeError('invalid').

Type Parameters#

Properties#

Methods#

agent()#

agent(
   owner, 
   id, 
   valid, 
   role?
): CommanderAgent | undefined;

Defined in: packages/playerthree/src/host/types.ts:906

Agent-rights access to an owner's commander for a credential the registry does not issue (the MCP binding's OAuth connections): it stays usable while valid() holds. Undefined for unknown owners/roles.

Parameters#

Returns#

CommanderAgent | undefined

chat()#

chat(owner): ChatEntry[];

Defined in: packages/playerthree/src/host/types.ts:894

Recent owner ↔ commander chat of an owner (memory only), oldest first. Agent text: render as plain text.

Parameters#

Returns#

ChatEntry[]

create()#

create(owner, input): CommanderStatus;

Defined in: packages/playerthree/src/host/types.ts:869

Parameters#

Returns#

CommanderStatus

delete()#

delete(owner, id): Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:871

Parameters#

Returns#

Promise<void>

ensure()#

ensure(owner): CommanderStatus[];

Defined in: packages/playerthree/src/host/types.ts:868

Create an empty owner registry if missing.

Parameters#

Returns#

CommanderStatus[]

flush()#

flush(): Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:866

Finish queued artifact, role-library and terminal-receipt writes before closing persistent storage.

Returns#

Promise<void>

has()#

has(owner): boolean;

Defined in: packages/playerthree/src/host/types.ts:872

Parameters#

Returns#

boolean

log()#

log(owner, id): Promise<StoredCommanderLogEntry[]>;

Defined in: packages/playerthree/src/host/types.ts:885

The owner's full log of one commander (entries and their sealed parts), oldest first.

Parameters#

Returns#

Promise<StoredCommanderLogEntry[]>

onSaid()#

onSaid(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:896

Agent replies of any owner's commanders (lobby and matches). Returns unsubscribe.

Parameters#

Returns#

() => void

onStatus()#

onStatus(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:901

Commander lifecycle or credential changes. role is the one execution lane that changed, or null when the whole commander did. Returns unsubscribe; no text or credentials.

Parameters#

Returns#

() => void

owners()#

owners(): string[];

Defined in: packages/playerthree/src/host/types.ts:874

Every owner with a roster, sorted. For operator tooling; players only ever see their own roster.

Returns#

string[]

practice()#

practice(
   owner, 
   id, 
   req
): Promise<PracticeResult>;

Defined in: packages/playerthree/src/host/types.ts:879

Parameters#

Returns#

Promise<PracticeResult>

publicId()#

publicId(owner, id): string;

Defined in: packages/playerthree/src/host/types.ts:887

The commander's public id (commanderPublicId).

Parameters#

Returns#

string

remove()#

remove(owner): Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:883

Delete an owner's roster, tokens and library.

Parameters#

Returns#

Promise<void>

rename()#

rename(
   owner, 
   id, 
   input
): CommanderStatus;

Defined in: packages/playerthree/src/host/types.ts:870

Parameters#

Returns#

CommanderStatus

reserve()#

reserve(
   owner, 
   id, 
   role, 
   reservation
): void;

Defined in: packages/playerthree/src/host/types.ts:914

A game lobby reserves one role lane of this commander for a seat of the next match (null clears it): until a match seats it, its agent's lobby state shows the seat, the game's pre-match summary (match, manifest.lobby) and when the match starts (start.at: wall clock, ms since epoch), and the agent can mark itself ready (carried into the match that seats it there). A different seat, or clearing, resets ready and wakes the lane's lobby waits. The reservation ends when the lane's match ends; it never seats anything by itself.

Parameters#

Returns#

void

resolveApproval()#

resolveApproval(
   owner, 
   id, 
   approvalId, 
   approve
): Promise<
  | void
  | DeployResult
| PublishResult>;

Defined in: packages/playerthree/src/host/types.ts:881

Parameters#

Returns#

Promise< | void | DeployResult | PublishResult>

rollback()#

rollback(
   owner, 
   id, 
   role, 
   version
): Promise<DeployResult>;

Defined in: packages/playerthree/src/host/types.ts:880

Parameters#

Returns#

Promise<DeployResult>

roster()#

roster(owner): CommanderStatus[];

Defined in: packages/playerthree/src/host/types.ts:875

Parameters#

Returns#

CommanderStatus[]

rotate()#

rotate(owner, id): string;

Defined in: packages/playerthree/src/host/types.ts:878

Parameters#

Returns#

string

tell()#

tell(
   owner, 
   commanderIds, 
   text, 
   ping?
): void;

Defined in: packages/playerthree/src/host/types.ts:892

Chat mode: message the owner's own commanders (in the lobby or in their live match). Text ≤ maxTellChars, rate-limited per owner; ping must match manifest.control.chat.ping.

Parameters#

Returns#

void

token()#

token(owner, id): string;

Defined in: packages/playerthree/src/host/types.ts:877

Parameters#

Returns#

string

update()#

update(
   owner, 
   id, 
   patch
): CommanderStatus;

Defined in: packages/playerthree/src/host/types.ts:876

Parameters#

Returns#

CommanderStatus

CommanderSaid#

Defined in: packages/playerthree/src/host/types.ts:916

An agent's reply to its owner (say), as delivered to the owner's clients only.

Extends#

• Said

Properties#

CommanderSettings#

Defined in: packages/playerthree/src/host/types.ts:799

Extended by#

• CommanderStatus
• StoredCommander

Properties#

CommanderSettingsPatch#

Defined in: packages/playerthree/src/host/types.ts:806

Properties#

CommanderStatus#

Defined in: packages/playerthree/src/host/types.ts:840

Extends#

• CommanderSettings
• CommanderIdentity

Properties#

CommanderStore#

Defined in: packages/playerthree/src/host/types.ts:1020

Storage behind the commander registry. Every method may be sync or async; writes are issued in order and failures are reported to the host's console (the in-memory state stays authoritative for the process).

Methods#

deleteArtifact()#

deleteArtifact(
   owner, 
   commanderId, 
   version
): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1028

Parameters#

Returns#

void | Promise<void>

deleteOwner()#

deleteOwner(owner): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1025

Parameters#

Returns#

void | Promise<void>

load()#

load(): 
  | CommanderStoreData
| Promise<CommanderStoreData>;

Defined in: packages/playerthree/src/host/types.ts:1021

Returns#

| CommanderStoreData | Promise<CommanderStoreData>

loadArtifact()#

loadArtifact(
   owner, 
   commanderId, 
   version
): 
  | StoredPolicyArtifact
  | Promise<StoredPolicyArtifact | undefined>
  | undefined;

Defined in: packages/playerthree/src/host/types.ts:1027

Parameters#

Returns#

| StoredPolicyArtifact | Promise<StoredPolicyArtifact | undefined> | undefined

saveArtifact()#

saveArtifact(
   owner, 
   commanderId, 
   version, 
   artifact
): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1026

Parameters#

Returns#

void | Promise<void>

saveKey()#

saveKey(key): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1022

Parameters#

Returns#

void | Promise<void>

saveOwner()#

saveOwner(record): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1024

Upsert one owner's full record.

Parameters#

Returns#

void | Promise<void>

CommanderStoreData#

Defined in: packages/playerthree/src/host/types.ts:1007

Properties#

CommentaryEvent#

Defined in: packages/playerthree/src/host/types.ts:205

Properties#

CreateMatchOptions#

Defined in: packages/playerthree/src/host/types.ts:223

Options of PlayerThreeHost.createMatch.

Type Parameters#

Properties#

DecisionUsage#

Defined in: packages/playerthree/src/host/types.ts:53

Optional harness accounting. Provider identity and billing are declared, never host-verified.

Properties#

GuardDrop#

Defined in: packages/playerthree/src/guard.ts:21

Properties#

GuardOptions#

Defined in: packages/playerthree/src/guard.ts:42

Properties#

GuardStats#

Defined in: packages/playerthree/src/guard.ts:27

Properties#

HistoryStore#

Defined in: packages/playerthree/src/host/types.ts:1066

Storage behind the session history. Every method may be sync or async; writes are issued in order and failures are reported to the host's console. Records of other games in load() are ignored; the host prunes the loaded records with its bounds (deleting from the store).

Methods#

delete()#

delete(id): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1071

Parameters#

Returns#

void | Promise<void>

load()#

load(): 
  | SessionRecord[]
| Promise<SessionRecord[]>;

Defined in: packages/playerthree/src/host/types.ts:1068

Every kept record. record.replay is true only when the replay is actually stored.

Returns#

| SessionRecord[] | Promise<SessionRecord[]>

loadReplay()#

loadReplay(id): 
  | Replay
  | Promise<Replay | undefined>
  | undefined;

Defined in: packages/playerthree/src/host/types.ts:1072

Parameters#

Returns#

| Replay | Promise<Replay | undefined> | undefined

save()#

save(record, replay): void | Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:1070

Upsert a released session: its record and its replay as serialized JSON (Replay), or null when not kept.

Parameters#

Returns#

void | Promise<void>

LoadOptions#

Defined in: packages/playerthree/src/policy/types.ts:59

Per-instance load options.

Properties#

LobbyReservation#

Defined in: packages/playerthree/src/host/types.ts:934

A game lobby's reservation of one commander role lane (CommanderRegistry.reserve).

Properties#

MatchLogFacts#

Defined in: packages/playerthree/src/host/types.ts:142

Game-supplied match facts for the commander log (game vocabularies; bounded identifiers).

Properties#

MatchTokens#

Defined in: packages/playerthree/src/host/types.ts:278

The match's owner tokens, minted at creation: hand each team's token only to that team's owner.

Properties#

ObserverPolicy#

Defined in: packages/playerthree/src/host/types.ts:213

Properties#

OutboundGuard#

Defined in: packages/playerthree/src/guard.ts:33

Methods#

pass()#

pass(
   channel, 
   schema, 
   data
): GuardResult<unknown>;

Defined in: packages/playerthree/src/guard.ts:38

Snapshot data (JSON round trip, so getters/toJSON/prototype tricks cannot change it after the check), validate the snapshot, and return it. The snapshot is what must be sent.

Parameters#

Returns#

GuardResult<unknown>

stats()#

stats(): GuardStats;

Defined in: packages/playerthree/src/guard.ts:39

Returns#

GuardStats

PlayerThreeHost#

Defined in: packages/playerthree/src/host/types.ts:549

The in-process host of one game (createPlayerThreeHost): creates matches, resolves tokens and serves the bindings.

Type Parameters#

Properties#

Methods#

agentSession()#

agentSession(token, role?): AgentSession | undefined;

Defined in: packages/playerthree/src/host/types.ts:573

Seat token or commander token → agent session (agent rights). Used by the MCP binding.

Parameters#

Returns#

AgentSession | undefined

authenticate()#

authenticate(token): 
  | {
  match: PlayerThreeMatch<M>;
  principal: Principal;
}
  | undefined;

Defined in: packages/playerthree/src/host/types.ts:564

Resolve any token to its match + principal. Constant-time compare; undefined if unknown/expired.

Parameters#

Returns#

| { match: PlayerThreeMatch<M>; principal: Principal; } | undefined

authorizeLease()#

authorizeLease(lease): Principal | undefined;

Defined in: packages/playerthree/src/host/types.ts:567

Parameters#

Returns#

Principal | undefined

claimToken()#

claimToken(token, connectionId): AuthorizationLease | undefined;

Defined in: packages/playerthree/src/host/types.ts:566

Atomically consumes a match credential for exactly one transport session.

Parameters#

Returns#

AuthorizationLease | undefined

createMatch()#

createMatch(opts?): PlayerThreeMatch<M>;

Defined in: packages/playerthree/src/host/types.ts:561

Parameters#

Returns#

PlayerThreeMatch<M>

disconnectLease()#

disconnectLease(lease): void;

Defined in: packages/playerthree/src/host/types.ts:568

Parameters#

Returns#

void

dispose()#

dispose(): void;

Defined in: packages/playerthree/src/host/types.ts:577

Returns#

void

getMatch()#

getMatch(id): PlayerThreeMatch<M> | undefined;

Defined in: packages/playerthree/src/host/types.ts:562

Parameters#

Returns#

PlayerThreeMatch<M> | undefined

matches()#

matches(): PlayerThreeMatch<M>[];

Defined in: packages/playerthree/src/host/types.ts:579

Live (not disposed) matches.

Returns#

PlayerThreeMatch<M>[]

onLeaseRevoked()#

onLeaseRevoked(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:569

Parameters#

Returns#

() => void

onTrace()#

onTrace(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:581

Developer-facing trace stream (DevTools). Returns unsubscribe. Listener errors are swallowed.

Parameters#

Returns#

() => void

onUsage()#

onUsage(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:582

Parameters#

Returns#

() => void

seatControl()#

seatControl(token): SeatControl | undefined;

Defined in: packages/playerthree/src/host/types.ts:571

Seat token → control plane bound to that seat (agent rights). Used by the MCP binding.

Parameters#

Returns#

SeatControl | undefined

PlayerThreeHostOptions#

Defined in: packages/playerthree/src/host/types.ts:77

Options of createPlayerThreeHost: the game definition, storage (directories or custom stores) and host defaults.

Type Parameters#

Properties#

PlayerThreeMatch#

Defined in: packages/playerthree/src/host/types.ts:313

One live match (session) on a host: seats and controllers, the clock, streams, replays and the protocol entry point.

Type Parameters#

Properties#

Methods#

assign()#

assign(assignment): void;

Defined in: packages/playerthree/src/host/types.ts:369

Trusted (game-authenticated owner) re-assignment of one seat, before the start or mid-match, at the current tick boundary. The previous occupant is detached first: its commander lane returns to the lobby (its waits return unseated), its exact-seat and human credentials (unless the same human keeps it) stop authenticating, and its plan, pending approval, inbox and seat policies end. The new occupant takes the seat now — a named commander (commander, with the createMatch rules: compatible role and kind, one owner's agents on different teams need independent sessions, a commander seated elsewhere fails busy) gets the seat's lease, and its agent's next wait returns the match entry with its first observation. Recorded as a seat change. Same occupant: no-op. invalid once the seat's team is out, the match is over or its bindings were released.

Parameters#

Returns#

void

cards()#

cards(): PublicSeatCard[];

Defined in: packages/playerthree/src/host/types.ts:398

Returns#

PublicSeatCard[]

checkpoint()#

checkpoint(tick?): ReplayPosition<M> | undefined;

Defined in: packages/playerthree/src/host/types.ts:442

Persistent sessions: an isolated copy (adapter clone()) of the newest kept checkpoint at or before tick (default: the oldest kept one), positioned to re-simulate this session's replay() window with replaySimulation(definition, replay, target, position). Undefined when no kept checkpoint is that old (or the session is not persistent; then replay from the seed).

Parameters#

Returns#

ReplayPosition<M> | undefined

coachingAllowed()#

coachingAllowed(owner): boolean;

Defined in: packages/playerthree/src/host/types.ts:389

Parameters#

Returns#

boolean

debugView()#

debugView(): unknown;

Defined in: packages/playerthree/src/host/types.ts:413

Unfogged developer-only JSON snapshot, or null if unsupported. Never exposed by the player protocol.

Returns#

unknown

dispose()#

dispose(): void;

Defined in: packages/playerthree/src/host/types.ts:498

Returns#

void

end()#

end(outcomes): Record<string, Outcome>;

Defined in: packages/playerthree/src/host/types.ts:483

End the session now, as if the game had decided it: the clock stops, onEnd listeners and the match_ended trace fire, outcome()/rank()/replay() report it, and blocked wait calls return. 'draw': every team draws. Otherwise keys are match teams and/or alliance ids (an alliance key covers its members) and values are either all outcomes (win/loss/draw, ranked win, draw, loss) or all placements (1 = first; the single side placed first wins, sides sharing first place draw, the rest lose; a standard competition ranking counting alliances, not members). Every match team must be covered, allies must agree. Already over: no-op. Returns the final outcomes. Throws invalid for any other shape and for a persistent session (it has no outcome; dispose() closes it).

Parameters#

Returns#

Record<string, Outcome>

forfeit()#

forfeit(team, opts?): void;

Defined in: packages/playerthree/src/host/types.ts:491

One match team concedes while the others play on: records the forfeit at the current tick (replay entry and forfeit trace) and calls the game's forfeit hook, which takes the team out of play. The team's outcome turns final when the game reports it (the per-team terminal rule); the host then retires it as any team that is out. No-op once the team forfeited, its outcome is final or the session is over. Throws invalid for a team outside the match, a game without the hook, or a persistent session (it has no outcome).

Parameters#

Returns#

void

halt()#

halt(): Promise<void>;

Defined in: packages/playerthree/src/host/types.ts:393

Stop at a serialized tick boundary without assigning an outcome; cannot be resumed.

Returns#

Promise<void>

handleMessage()#

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

Defined in: packages/playerthree/src/host/types.ts:454

Transport-agnostic message handling for protocol.ts messages from an authenticated principal. push is the transport's channel to that client; required for op: 'stream' (subscriptions are keyed by (push, role); everyTicks: 0 stops). Call release(push) when the client leaves.

Parameters#

Returns#

Promise<ServerMsg | undefined>

holdStart()#

holdStart(): void;

Defined in: packages/playerthree/src/host/types.ts:461

Trusted tick-0 manual preparation/countdown gate. Only start()/skipReadyCheck() releases it.

Returns#

void

humanJoined()#

humanJoined(
   team, 
   role, 
   joined
): void;

Defined in: packages/playerthree/src/host/types.ts:397

Parameters#

Returns#

void

metricRows()#

metricRows(): Partial<ResultRows>;

Defined in: packages/playerthree/src/host/types.ts:329

Returns#

Partial<ResultRows>

metrics()#

metrics(): GameMetrics;

Defined in: packages/playerthree/src/host/types.ts:328

Returns#

GameMetrics

mintHumanToken()#

mintHumanToken(
   team, 
   role, 
   opts?
): SeatTicket;

Defined in: packages/playerthree/src/host/types.ts:378

Parameters#

Returns#

SeatTicket

mintObserverToken()#

mintObserverToken(grant, opts): SeatTicket;

Defined in: packages/playerthree/src/host/types.ts:385

Parameters#

Returns#

SeatTicket

mintSeatToken()#

mintSeatToken(team, role): string;

Defined in: packages/playerthree/src/host/types.ts:377

Mint a seat token for an agent (one seat, this match).

Parameters#

Returns#

string

mintSpectatorToken()#

mintSpectatorToken(team, opts?): SeatTicket;

Defined in: packages/playerthree/src/host/types.ts:384

Parameters#

Returns#

SeatTicket

observerFrames()#

observerFrames(grant, after?): AsyncIterable<ObserverFrame>;

Defined in: packages/playerthree/src/host/types.ts:388

Parameters#

Returns#

AsyncIterable<ObserverFrame>

observerMessages()#

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

Defined in: packages/playerthree/src/host/types.ts:387

Released observer messages after cursor after: deltas in order, or one keyframe (join, resync). Shared and frozen.

Parameters#

Returns#

ObserverMessage[]

onCommentary()#

onCommentary(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:331

Parameters#

Returns#

() => void

onEnd()#

onEnd(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:428

Fires once when the match is over, with every match team's outcome and rank.

Parameters#

Returns#

() => void

onReadiness()#

onReadiness(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:351

Readiness/card changes: every status change plus agent arrivals (presence is not part of SeatStatus).

Parameters#

Returns#

() => void

onSaid()#

onSaid(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:408

Agent replies (say) per team — deliver them to that team's owners only. Returns unsubscribe.

Parameters#

Returns#

() => void

onStatus()#

onStatus(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:349

Seat lifecycle changes, not tick-rate observations. Returns unsubscribe.

Parameters#

Returns#

() => void

onTick()#

onTick(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:327

Parameters#

Returns#

() => void

onUsage()#

onUsage(listener): () => void;

Defined in: packages/playerthree/src/host/types.ts:330

Parameters#

Returns#

() => void

onView()#

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

Defined in: packages/playerthree/src/host/types.ts:419

Subscribe to a team's view stream (SPEC §4, view streams). The host computes a team's views only while its stream has subscribers: a first subscriber restarts it from a fresh view, then every view tick (viewHz) that changed the view adds a version and calls listener with it. Returns unsubscribe.

Parameters#

Returns#

() => void

outcome()#

outcome(team): Outcome;

Defined in: packages/playerthree/src/host/types.ts:339

A match team's outcome. The first final outcome the game reports for a team is kept: from then on the team is out (its seats' intents fail game_over, its bots and policies stop, its waits return, its commanders and pool policies record the outcome) while the others play on. The match is over once every team is final.

Parameters#

Returns#

Outcome

paused()#

paused(): PauseInfo | undefined;

Defined in: packages/playerthree/src/host/types.ts:447

The session stands still because a seat with whenAbsent: 'pause' has no present agent (pausable games), or undefined while it runs.

Returns#

PauseInfo | undefined

rank()#

rank(team): number | null;

Defined in: packages/playerthree/src/host/types.ts:344

A match team's final placement once the match is over (1 is best, ties share, allies share their alliance's), else null: the game's rank(), or ranked by outcome. invalid for a team not in the match.

Parameters#

Returns#

number | null

readiness()#

readiness(): ReadinessSnapshot;

Defined in: packages/playerthree/src/host/types.ts:399

Returns#

ReadinessSnapshot

readyCheck()#

readyCheck(): ReadyCheck | undefined;

Defined in: packages/playerthree/src/host/types.ts:463

Ready check state, or undefined if the match was created without one.

Returns#

ReadyCheck | undefined

release()#

release(push): void;

Defined in: packages/playerthree/src/host/types.ts:456

Drop every stream subscription made through handleMessage with this push.

Parameters#

Returns#

void

releaseBindings()#

releaseBindings(): Promise<void>;