playerthree/manifest#

The game definition contract (SPEC §3 Game description, §10 Adapter contract): the declarative GameManifest (checked by defineManifest), the GameAdapter a game implements, built-in bots, and the GameDefinition that bundles them; plus the fixed caps on agent-served text.

Interfaces#

BotCommander#

Defined in: packages/playerthree/src/manifest.ts:398

A built-in (developer-written, native) commander. Uses exactly the same intents as agents.

Type Parameters#

Methods#

init()?#

init?(matchData): void;

Defined in: packages/playerthree/src/manifest.ts:400

Runs once before think, with guarded seat-visible match data (null when no schema is declared).

Parameters#

Returns#

void

think()#

think(obs): IntentOf<M>[];

Defined in: packages/playerthree/src/manifest.ts:401

Parameters#

Returns#

IntentOf<M>[]

ChatMode#

Defined in: packages/playerthree/src/manifest.ts:109

Properties#

ControlModes#

Defined in: packages/playerthree/src/manifest.ts:86

manifest.control: the control modes a game offers its seats (absent optional modes are unavailable).

Properties#

GameAdapter#

Defined in: packages/playerthree/src/manifest.ts:405

One running match of a game.

Type Parameters#

Properties#

Methods#

apply()#

apply(
   seat, 
   intent, 
   context?
): ApplyResult<M>;

Defined in: packages/playerthree/src/manifest.ts:456

Intent is already schema-validated and role-checked. Omitted context means an explicit direct/owner call.

Parameters#

Returns#

ApplyResult<M>

clone()?#

clone?(): GameAdapter<M>;

Defined in: packages/playerthree/src/manifest.ts:440

Optional independent in-memory checkpoint. Copy all mutable state, RNG and caches; never share them.

Returns#

GameAdapter<M>

debugView()?#

debugView?(): unknown;

Defined in: packages/playerthree/src/manifest.ts:416

Optional bounded JSON snapshot of unfogged state. Developer-only; never sent to players or agents.

Returns#

unknown

end()?#

end?(outcomes, ranks): void;

Defined in: packages/playerthree/src/manifest.ts:424

Optional: the host ended the session early (PlayerThreeMatch.end, e.g. from the operator console) with these outcomes and placements for every match team. Adopt them so the game's own outcome, views and reports agree. Without it the host still reports the declared outcomes, but the game's views and reports keep whatever the game last decided.

Parameters#

Returns#

void

events()#

events(seat, sinceTick): Infer<M["event"]>[];

Defined in: packages/playerthree/src/manifest.ts:460

Events visible to a seat with tick > sinceTick, oldest first. Each must conform to manifest.event.

Parameters#

Returns#

Infer<M["event"]>[]

forfeit()?#

forfeit?(team): void;

Defined in: packages/playerthree/src/manifest.ts:431

Optional: the match team concedes now (PlayerThreeMatch.forfeit); take it out of play while the others play on, and report its final outcome from outcome(team) once the game decides it (now or at a later step). Called before step() of the current tick and recorded in replays, so it MUST be deterministic like apply. Called at most once per team, only while the team's outcome is not final. Without it PlayerThreeMatch.forfeit fails invalid.

Parameters#

Returns#

void

matchData()?#

matchData?(seat): MatchDataOf<M>;

Defined in: packages/playerthree/src/manifest.ts:454

Required when manifest.matchData is declared. Must enforce the seat's perspective.

Parameters#

Returns#

MatchDataOf<M>

observe()#

observe(
   seat, 
   sinceTick, 
   detail
): GameObservationOf<M>;

Defined in: packages/playerthree/src/manifest.ts:446

Must conform to manifest.observation, minus the host-owned signals member when signals are declared. Events after sinceTick; bootstrap is delivered separately. detail: the sections to render in full, in manifest order (empty without observationScope); summarise the others.

Parameters#

Returns#

GameObservationOf<M>

observerView()?#

observerView?(): unknown;

Defined in: packages/playerthree/src/manifest.ts:418

Required for omniscient observers when manifest.observer is declared; must conform to that schema.

Returns#

unknown

outcome()#

outcome(team): Outcome;

Defined in: packages/playerthree/src/manifest.ts:409

Parameters#

Returns#

Outcome

rank()?#

rank?(team): number;

Defined in: packages/playerthree/src/manifest.ts:438

Optional final placement of a match team, read once every match team's outcome is final: 1 is best, tied teams share a rank and the next rank skips (1, 2, 2, 4), allies share their alliance's rank, and ranks count alliances (or lone teams), never members. Without it, or when the ranks break these rules, the host ranks by outcome: win, then draw, then loss.

Parameters#

Returns#

number

report()#

report(team): Infer<M["report"]>;

Defined in: packages/playerthree/src/manifest.ts:458

Must conform to manifest.report.

Parameters#

Returns#

Infer<M["report"]>

setSeatInfo()#

setSeatInfo(seat, info): void;

Defined in: packages/playerthree/src/manifest.ts:462

Server informs the game so it can render controller badges and enforce mandate limits.

Parameters#

Returns#

void

signalLimits()?#

signalLimits?(): SignalLimits | null;

Defined in: packages/playerthree/src/manifest.ts:452

Optional, with manifest.signals: this match's signal limits, each at most the manifest's control.signals (a match may narrow, never widen them), or null when this match has signals off (every signal intent then fails disabled). Read once when the match (or a replay of it) is created. Without it the manifest's limits apply.

Returns#

SignalLimits | null

step()#

step(): void;

Defined in: packages/playerthree/src/manifest.ts:408

Returns#

void

view()#

view(team, opts?): GameViewOf<M>;

Defined in: packages/playerthree/src/manifest.ts:414

Must conform to manifest.view. snapshot is true when a client starts watching (its first view) and false for the periodic broadcast, so a game can send static, slow-changing parts (a map) only when they are needed.

Parameters#

Returns#

GameViewOf<M>

GameDefinition#

Defined in: packages/playerthree/src/manifest.ts:484

Factory for matches: used for live rooms and headless practice.

Type Parameters#

Properties#

Methods#

create()#

create(opts): GameAdapter<M>;

Defined in: packages/playerthree/src/manifest.ts:490

A new match of the given sides (teams ⊆ manifest teams, never empty; alliances only when the match declares them). A game that cannot play a side set throws; the host never invents phantom sides.

Parameters#

Returns#

GameAdapter<M>

createBot()#

createBot(
   seat, 
   opponent, 
   options?
): BotCommander<M>;

Defined in: packages/playerthree/src/manifest.ts:492

Built-in bot at a given strength for a seat.

Parameters#

Returns#

BotCommander<M>

metrics()?#

metrics?(game, options?): GameMetricRecorder;

Defined in: packages/playerthree/src/manifest.ts:496

Optional game-owned, observational benchmark recorder for this adapter instance.

Parameters#

Returns#

GameMetricRecorder

GameManifest#

Defined in: packages/playerthree/src/manifest.ts:202

Everything a game exposes to agents. All text here is static developer text (trusted). All data schemas are closed-vocabulary (see schema.ts). The manifest is plain JSON-able data, so non-JS engines can author it and speak the wire protocol directly.

Type Parameters#

Properties#

GameMetricRecorder#

Defined in: packages/playerthree/src/manifest.ts:472

A recorder must not mutate game state, consume RNG, or change observations.

Methods#

collect()#

collect(): void;

Defined in: packages/playerthree/src/manifest.ts:474

Called after each benchmark tick, including the terminal tick.

Returns#

void

finish()#

finish(): GameMetrics;

Defined in: packages/playerthree/src/manifest.ts:476

Called once; maps are snapshotted and bounded by the benchmark runner.

Returns#

GameMetrics

intent()?#

intent?(row): void;

Defined in: packages/playerthree/src/manifest.ts:480

Observational intent accounting, including rejected attempts.

Parameters#

Returns#

void

rows()?#

rows?(matchId): Partial<ResultRows>;

Defined in: packages/playerthree/src/manifest.ts:478

Sanitized normalized accounting rows for the generic result service.

Parameters#

Returns#

Partial<ResultRows>

GameMetrics#

Defined in: packages/playerthree/src/manifest.ts:466

Observational benchmark data: finite numbers only; side keys are declared physical teams.

Properties#

IntentContext#

Defined in: packages/playerthree/src/manifest.ts:391

Host-supplied provenance of one applied intent.

Properties#

IntentDef#

Defined in: packages/playerthree/src/manifest.ts:36

One intent kind of manifest.intents: the roles that may send it and its parameter schema.

Type Parameters#

Properties#

IntentMode#

Defined in: packages/playerthree/src/manifest.ts:50

Control modes. A game opts into each mode it supports; agents discover them from the briefing. The set is designed to grow as models get faster and cheaper: today an LLM is a commander that writes policies (seconds per decision); tomorrow it can drive the seat directly every tick (stream). New modes are added as new optional keys — never by changing an existing one.

Properties#

MatchSides#

Defined in: packages/playerthree/src/manifest.ts:379

The sides of one match: the manifest teams taking part (a subset, in manifest order) and optional named alliances (alliance id → member teams, manifest order; every match team belongs to exactly one). Without alliances every team is on its own: two teams are a duel, more a free-for-all.

Type Parameters#

Properties#

ObservationScope#

Defined in: packages/playerthree/src/manifest.ts:187

Observation sections (spec §3 Observation scope). Plain JSON like the rest of the manifest.

Properties#

PauseMode#

Defined in: packages/playerthree/src/manifest.ts:80

The game may stand still while an agent is away: owners can then choose whenAbsent: 'pause'. Declare it only when one absent seat may stop the whole session for everyone in it (solo play, turn-based seats that must move).

Properties#

PolicyLimits#

Defined in: packages/playerthree/src/manifest.ts:164

Policy = agent-written code that runs sandboxed at tick rate. This is the StarSkirmish lesson: LLMs are far stronger as bot authors (write → practice → read reports → revise) than as real-time players. Sandboxes have no I/O, no clock, no network; they only map observations to intents.

Properties#

PoolMode#

Defined in: packages/playerthree/src/manifest.ts:72

Async bot pool: published policies can be drafted into seats of other players' matches.

Properties#

PracticeLimits#

Defined in: packages/playerthree/src/manifest.ts:179

Properties#

Seat#

Defined in: packages/playerthree/src/manifest.ts:358

One seat: a manifest team and role.

Type Parameters#

Properties#

SequenceMode#

Defined in: packages/playerthree/src/manifest.ts:57

A bounded, tick-relative plan; no branching or executable code.

Properties#

SkillDef#

Defined in: packages/playerthree/src/manifest.ts:283

Properties#

StreamMode#

Defined in: packages/playerthree/src/manifest.ts:64

Tick-synchronous direct control: the server pushes observations every N ticks; intents apply on the next tick.

Properties#

TopicDef#

Defined in: packages/playerthree/src/manifest.ts:152

On-demand briefing topic. The index shows name — summary; the text is fetched with game_briefing { topic }.

Properties#

Type Aliases#

AnyManifest#

type AnyManifest = GameManifest<any, any, any, any, any, any, any, any, any, any>;

Defined in: packages/playerthree/src/manifest.ts:291

ApplyResult#

type ApplyResult<M> = 
  | {
  ok: true;
}
  | {
  code: GameErrorOf<M>;
  ok: false;
};

Defined in: packages/playerthree/src/manifest.ts:385

What GameAdapter.apply returns: accepted, or rejected with one of the game's declared error codes.

Type Parameters#

Controller#

type Controller = typeof CONTROLLERS[number];

Defined in: packages/playerthree/src/manifest.ts:26

DetailRequest#

type DetailRequest = readonly string[] | "all";

Defined in: packages/playerthree/src/manifest.ts:195

What a caller asks to see in full besides its role's defaults: section names, or every section.

DirectiveOf#

type DirectiveOf<M> = Infer<M["directive"]>;

Defined in: packages/playerthree/src/manifest.ts:302

Type Parameters#

EventOf#

type EventOf<M> = Infer<M["event"]>;

Defined in: packages/playerthree/src/manifest.ts:319

Type Parameters#

FinalOutcome#

type FinalOutcome = Exclude<Outcome, "running">;

Defined in: packages/playerthree/src/manifest.ts:372

A side's decided outcome.

GameErrorOf#

type GameErrorOf<M> = Infer<M["errors"]>;

Defined in: packages/playerthree/src/manifest.ts:316

Type Parameters#

GameObservationOf#

type GameObservationOf<M> = M["signals"] extends SignalVocabulary ? Omit<ObservationOf<M>, "signals"> : ObservationOf<M>;

Defined in: packages/playerthree/src/manifest.ts:298

What a game's observe returns: the observation without the host-owned signals member (when signals are declared).

Type Parameters#

GameViewOf#

type GameViewOf<M> = M["signals"] extends SignalVocabulary ? Omit<ViewOf<M>, "signals"> : ViewOf<M>;

Defined in: packages/playerthree/src/manifest.ts:300

What a game's view returns: the view without the host-owned signals member (when signals are declared).

Type Parameters#

IntentOf#

type IntentOf<M> = { [K in keyof M["intents"] & string]: { kind: K } & Infer<ObjS<M["intents"][K]["params"]>> }[keyof M["intents"] & string];

Defined in: packages/playerthree/src/manifest.ts:320

Type Parameters#

IntentSource#

type IntentSource = typeof INTENT_SOURCES[number];

Defined in: packages/playerthree/src/manifest.ts:389

LimitsOf#

type LimitsOf<M> = M["limits"] extends ObjS ? Infer<M["limits"]> : Record<string, unknown>;

Defined in: packages/playerthree/src/manifest.ts:303

Type Parameters#

MandateOf#

type MandateOf<M> = Omit<Mandate, "directive" | "limits" | "whenAbsent"> & object;

Defined in: packages/playerthree/src/manifest.ts:311

Type Parameters#

Type Declaration#

MatchDataOf#

type MatchDataOf<M> = M["matchData"] extends ObjS ? Infer<M["matchData"]> : Record<string, unknown>;

Defined in: packages/playerthree/src/manifest.ts:301

Type Parameters#

MatchOptionsOf#

type MatchOptionsOf<M> = M["matchOptions"] extends ObjS ? Infer<M["matchOptions"]> : Record<string, unknown>;

Defined in: packages/playerthree/src/manifest.ts:325

Validated match options of a game (the host rejects any options when the manifest declares none).

Type Parameters#

ObservationOf#

type ObservationOf<M> = Infer<M["observation"]>;

Defined in: packages/playerthree/src/manifest.ts:295

Type Parameters#

OpponentOf#

type OpponentOf<M> = Infer<M["opponents"]>;

Defined in: packages/playerthree/src/manifest.ts:317

Type Parameters#

Outcome#

type Outcome = "win" | "loss" | "draw" | "running";

Defined in: packages/playerthree/src/manifest.ts:370

PolicyRuntime#

type PolicyRuntime = typeof POLICY_RUNTIMES[number];

Defined in: packages/playerthree/src/manifest.ts:30

ReportOf#

type ReportOf<M> = Infer<M["report"]>;

Defined in: packages/playerthree/src/manifest.ts:318

Type Parameters#

RoleOf#

type RoleOf<M> = Infer<M["roles"]>;

Defined in: packages/playerthree/src/manifest.ts:294

Type Parameters#

SectionOf#

type SectionOf<M> = NonNullable<M["observationScope"]> extends object ? Infer<S> : never;

Defined in: packages/playerthree/src/manifest.ts:328

Observation section names of a game (never without observationScope).

Type Parameters#

TeamOf#

type TeamOf<M> = Infer<M["teams"]>;

Defined in: packages/playerthree/src/manifest.ts:293

Type Parameters#

ViewOf#

type ViewOf<M> = Infer<M["view"]>;

Defined in: packages/playerthree/src/manifest.ts:296

Type Parameters#

WhenAbsentOf#

type WhenAbsentOf<M> = 
  | Exclude<Mandate["whenAbsent"], "pause">
  | { [K in keyof M["control"] & "pausable"]: "pause" }[keyof M["control"] & "pausable"];

Defined in: packages/playerthree/src/manifest.ts:308

pause only for games whose control declares pausable (the host rejects it otherwise). A mapped type, not a conditional one, so PlayerThreeMatch<M> stays assignable to PlayerThreeMatch<AnyManifest>.

Type Parameters#

Variables#

CONTROL_PLANE_VERSION#

const CONTROL_PLANE_VERSION: 1 = 1;

Defined in: packages/playerthree/src/manifest.ts:122

CONTROLLERS#

const CONTROLLERS: readonly ["human", "agent", "policy", "bot", "none"];

Defined in: packages/playerthree/src/manifest.ts:25

Who drives a seat. Fixed by PlayerThree.

• human: the team owner's client
• agent: a live LLM harness (issues intents and may deploy a policy)
• policy: a published policy artifact, no live LLM (async bots: ladders, bot pools, "enemies are other players' bots")
• bot: the developer's built-in commander
• none: idle

DOC_MAX#

const DOC_MAX: 6000 = 6_000;

Defined in: packages/playerthree/src/manifest.ts:132

manifest.doc: the core rules every seat reads first.

GENERATED_TOPIC_ROOTS#

const GENERATED_TOPIC_ROOTS: readonly ["role", "intents", "intent", "observation", "match-data", "events", "report", "mandate", "modes", "schema", "signals"];

Defined in: packages/playerthree/src/manifest.ts:149

Generated topic roots: a game topic must not be one of these or start with <root>/. role/<role>, intent/<kind>, observation/<field>, match-data/fields and schema/<name> live under them.

INTENT_SOURCES#

const INTENT_SOURCES: readonly ["owner", "agent", "policy", "bot", "fallback"];

Defined in: packages/playerthree/src/manifest.ts:388

Trusted caller provenance, supplied by the host, never by an intent's untrusted payload.

MATCH_DATA_MAX_BYTES#

const MATCH_DATA_MAX_BYTES: number;

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

Independent UTF-8 JSON bound for match bootstrap, not part of an observation's byte budget.

MAX_POLICY_INCLUDES#

const MAX_POLICY_INCLUDES: 16 = 16;

Defined in: packages/playerthree/src/manifest.ts:144

Skill .js files one policy artifact may include.

MAX_SAY_CHARS#

const MAX_SAY_CHARS: 280 = 280;

Defined in: packages/playerthree/src/manifest.ts:120

MAX_TELL_CHARS#

const MAX_TELL_CHARS: 500 = 500;

Defined in: packages/playerthree/src/manifest.ts:119

Hard caps on chat lengths (manifests may only lower them).

POLICY_RUNTIMES#

const POLICY_RUNTIMES: readonly ["js", "wasm"];

Defined in: packages/playerthree/src/manifest.ts:29

Policy artifact formats. js: source run in QuickJS compiled to WASM. wasm: a core WebAssembly module (any language) using the PlayerThree policy ABI.

RESULT_TEXT_MAX#

const RESULT_TEXT_MAX: 24000 = 24_000;

Defined in: packages/playerthree/src/manifest.ts:130

Upper bound on any default tool result's MCP text content (core briefing, topic and skill pages, observe pages).

ROLE_DOC_MAX#

const ROLE_DOC_MAX: 3500 = 3_500;

Defined in: packages/playerthree/src/manifest.ts:134

Each manifest.roleDocs[role].

SKILL_PAGE_MAX#

const SKILL_PAGE_MAX: 20000 = 20_000;

Defined in: packages/playerthree/src/manifest.ts:142

One game_skill page, cut at a newline.

SKILL_PATH_PATTERN#

const SKILL_PATH_PATTERN: "^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*(/[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*)*$" = '^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*(/[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*)*$';

Defined in: packages/playerthree/src/manifest.ts:507

Skill file path grammar (also game_skill's path input pattern).

TOPIC_INDEX_MAX#

const TOPIC_INDEX_MAX: 5000 = 5_000;

Defined in: packages/playerthree/src/manifest.ts:140

All game-topic index lines (name — summary, newline-joined): keeps the core briefing and reference index small.

TOPIC_SUMMARY_MAX#

const TOPIC_SUMMARY_MAX: 160 = 160;

Defined in: packages/playerthree/src/manifest.ts:138

One-line topic summary shown in the index.

TOPIC_TEXT_MAX#

const TOPIC_TEXT_MAX: 8000 = 8_000;

Defined in: packages/playerthree/src/manifest.ts:136

Each topic page (game topic text; generated topics are split or paged to fit).

Functions#

defineManifest()#

function defineManifest<M>(m): M;

Defined in: packages/playerthree/src/manifest.ts:706

Typed identity helper: returns the manifest unchanged (with its inferred schema types) after validating it. Throws a descriptive error at startup for anything PlayerThree cannot serve safely: non-closed schemas, intents for unknown roles, an event schema without tick: int / kind: enum, invalid skills, insane limits.

Type Parameters#

Parameters#

Returns#

M

intentSchema()#

function intentSchema<M>(m): UnionS<"kind", Record<string, Fields>>;

Defined in: packages/playerthree/src/manifest.ts:364

Wire schema for any intent of this game: a union tagged by kind.

Type Parameters#

Parameters#

Returns#

UnionS<"kind", Record<string, Fields>>

observationSections()#

function observationSections(m): readonly string[];

Defined in: packages/playerthree/src/manifest.ts:331

Every declared observation section, in manifest order (empty without observationScope): the detail 'all'.

Parameters#

Returns#

readonly string[]

resolveDetail()#

function resolveDetail(
   m, 
   role, 
   request
): string[] | null;

Defined in: packages/playerthree/src/manifest.ts:340

The detail a seat of role observes with: its role's defaults united with request (a list of section names, or 'all' for every section; undefined = defaults only), in manifest order. Null when request is neither, names an undeclared section or repeats one — callers answer invalid.

Parameters#

Returns#

string[] | null