@playerthree/sidecar#

@playerthree/sidecar: the PlayerThree host for non-JS game servers (SPEC §20.8 (a)). The engine speaks newline-delimited JSON over stdio or a local socket; this process serves MCP through a normal PlayerThreeHost.

Classes#

EngineLink#

Defined in: packages/sidecar/src/link.ts:38

Properties#

Accessors#

isClosed#

Get Signature#

get isClosed(): boolean;

Defined in: packages/sidecar/src/link.ts:120

Returns#

boolean

Methods#

call()#

call(
   session, 
   method, 
   args
): unknown;

Defined in: packages/sidecar/src/link.ts:128

One synchronous adapter call. Returns the engine's data; throws SidecarCallError for ok:false (its code), a timeout (timeout, and the connection is closed) or a closed connection (engine_closed).

Parameters#

Returns#

unknown

callPadded()#

callPadded(
   session, 
   method, 
   args, 
   lineBytes
): unknown;

Defined in: packages/sidecar/src/link.ts:136

Conformance probe: a call whose line is exactly lineBytes long (excluding "\n"), filled up by an ignored pad member. Engines must answer lines up to MAX_LINE_BYTES.

Parameters#

Returns#

unknown

close()#

close(code?, message?): void;

Defined in: packages/sidecar/src/link.ts:183

Closes the connection, after a fatal {"op":"error"} notice when code is given.

Parameters#

Returns#

void

send()#

send(msg): void;

Defined in: packages/sidecar/src/link.ts:175

Fire-and-forget host → engine message (replies to engine requests, pushes, ready).

Parameters#

Returns#

void

sendRawLine()#

sendRawLine(line): void;

Defined in: packages/sidecar/src/link.ts:145

Conformance probe: writes one line verbatim, without the size check (line excludes the "\n").

Parameters#

Returns#

void

open()#

static open(opts): Promise<EngineLink>;

Defined in: packages/sidecar/src/link.ts:101

Starts the link; for a socket, resolves once it listens (owner-only) and the engine may connect.

Parameters#

Returns#

Promise<EngineLink>

LineDecoder#

Defined in: packages/sidecar/src/protocol.ts:68

Splits a byte stream into lines. Holds at most one open line (≤ MAX_LINE_BYTES) and never scans a byte twice. push returns 'too_large' once a line, terminated or not, exceeds the limit and 'bad_utf8' for an undecodable line; the stream is unusable afterwards.

Constructors#

Constructor#

new LineDecoder(): LineDecoder;

Returns#

LineDecoder

Methods#

push()#

push(chunk, out): "too_large" | "ok" | "bad_utf8";

Defined in: packages/sidecar/src/protocol.ts:72

Parameters#

Returns#

"too_large" | "ok" | "bad_utf8"

SidecarCallError#

Defined in: packages/sidecar/src/link.ts:16

A failed call: the engine answered ok:false, or the connection timed out or closed.

Extends#

• Error

Constructors#

Constructor#

new SidecarCallError(code, message): SidecarCallError;

Defined in: packages/sidecar/src/link.ts:18

Parameters#

Returns#

SidecarCallError

Overrides#

Error.constructor

Properties#

Interfaces#

EngineLinkOptions#

Defined in: packages/sidecar/src/link.ts:25

Properties#

LinkClosed#

Defined in: packages/sidecar/src/link.ts:33

Properties#

ServedSidecar#

Defined in: packages/sidecar/src/serve.ts:17

Properties#

Methods#

close()#

close(): Promise<void>;

Defined in: packages/sidecar/src/serve.ts:23

Closes the engine connection and the HTTP server.

Returns#

Promise<void>

ServeSidecarOptions#

Defined in: packages/sidecar/src/serve.ts:8

Extends#

• Omit<SidecarOptions, "serve">

Properties#

Sidecar#

Defined in: packages/sidecar/src/sidecar.ts:33

Properties#

Methods#

close()#

close(): void;

Defined in: packages/sidecar/src/sidecar.ts:41

Returns#

void

match()#

match(session): 
  | PlayerThreeMatch<AnyManifest>
  | undefined;

Defined in: packages/sidecar/src/sidecar.ts:40

The match behind an engine-created session.

Parameters#

Returns#

| PlayerThreeMatch<AnyManifest> | undefined

SidecarOptions#

Defined in: packages/sidecar/src/sidecar.ts:17

Properties#

Type Aliases#

FatalCode#

type FatalCode = "too_large" | "bad_frame" | "timeout" | "invalid_manifest" | "protocol";

Defined in: packages/sidecar/src/protocol.ts:19

Fatal {"op":"error"} codes: the sender closes the connection right after.

Hook#

type Hook = typeof HOOKS[number];

Defined in: packages/sidecar/src/protocol.ts:16

@playerthree/sidecar: the PlayerThree host for non-JS game servers (SPEC §20.8 (a)). The engine speaks newline-delimited JSON over stdio or a local socket; this process serves MCP through a normal PlayerThreeHost.

Msg#

type Msg = Record<string, unknown>;

Defined in: packages/sidecar/src/protocol.ts:26

@playerthree/sidecar: the PlayerThree host for non-JS game servers (SPEC §20.8 (a)). The engine speaks newline-delimited JSON over stdio or a local socket; this process serves MCP through a normal PlayerThreeHost.

Transport#

type Transport = 
  | {
  kind: "stdio";
}
  | {
  kind: "socket";
  path: string;
};

Defined in: packages/sidecar/src/protocol.ts:28

@playerthree/sidecar: the PlayerThree host for non-JS game servers (SPEC §20.8 (a)). The engine speaks newline-delimited JSON over stdio or a local socket; this process serves MCP through a normal PlayerThreeHost.

Variables#

DEFAULT_CALL_TIMEOUT_MS#

const DEFAULT_CALL_TIMEOUT_MS: 5000 = 5_000;

Defined in: packages/sidecar/src/protocol.ts:9

@playerthree/sidecar: the PlayerThree host for non-JS game servers (SPEC §20.8 (a)). The engine speaks newline-delimited JSON over stdio or a local socket; this process serves MCP through a normal PlayerThreeHost.

DEFAULT_HELLO_TIMEOUT_MS#

const DEFAULT_HELLO_TIMEOUT_MS: 10000 = 10_000;

Defined in: packages/sidecar/src/protocol.ts:10

@playerthree/sidecar: the PlayerThree host for non-JS game servers (SPEC §20.8 (a)). The engine speaks newline-delimited JSON over stdio or a local socket; this process serves MCP through a normal PlayerThreeHost.

HOOKS#

const HOOKS: readonly ["matchData", "debugView", "observerView", "end", "forfeit", "rank", "clone", "signalLimits"];

Defined in: packages/sidecar/src/protocol.ts:15

Optional adapter calls an engine declares in hello.hooks; everything else in §10 is always forwarded.

MAX_ADVANCE#

const MAX_ADVANCE: 10000 = 10_000;

Defined in: packages/sidecar/src/sidecar.ts:13

Largest advance batch: bounds how long one engine request can hold the host.

MAX_LINE_BYTES#

const MAX_LINE_BYTES: 1048576 = 1_048_576;

Defined in: packages/sidecar/src/protocol.ts:8

Largest line in UTF-8 bytes, excluding the terminating "\n".

PROTOCOL#

const PROTOCOL: 1 = 1;

Defined in: packages/sidecar/src/protocol.ts:6

Sidecar wire protocol 1 (SPEC §20.8 (a)): newline-delimited UTF-8 JSON between a non-JS engine and this host. Shared by the host, the conformance runner, the mock engine's expectations and the tests.

SOCKET_ENV#

const SOCKET_ENV: "PLAYERTHREE_SIDECAR_SOCKET" = 'PLAYERTHREE_SIDECAR_SOCKET';

Defined in: packages/sidecar/src/protocol.ts:12

Environment variable a launcher uses to hand the socket path to the engine.

Functions#

encodeLine()#

function encodeLine(msg): string;

Defined in: packages/sidecar/src/protocol.ts:41

Serialises one message to a line (with its "\n"); throws when the JSON exceeds the line limit.

Parameters#

Returns#

string

main()#

function main(argv, err?): Promise<number>;

Defined in: packages/sidecar/src/cli.ts:31

Parameters#

Returns#

Promise<number>

member()#

function member(v, key): unknown;

Defined in: packages/sidecar/src/protocol.ts:36

One member of a JSON object; undefined when v is not an object or lacks it.

Parameters#

Returns#

unknown

parseLine()#

function parseLine(line): Msg | undefined;

Defined in: packages/sidecar/src/protocol.ts:51

Parses one line into a message object, or undefined for anything that is not a JSON object.

Parameters#

Returns#

Msg | undefined

serveSidecar()#

function serveSidecar(opts): Promise<ServedSidecar>;

Defined in: packages/sidecar/src/serve.ts:26

Parameters#

Returns#

Promise<ServedSidecar>

startSidecar()#

function startSidecar(opts): Promise<Sidecar>;

Defined in: packages/sidecar/src/sidecar.ts:167

Opens the engine link and runs the sidecar until the engine leaves.

Parameters#

Returns#

Promise<Sidecar>