Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

13.0 KB
Raw Blame

API surface — esengine/session

Symbols: 0 public · 0 beta · 61 experimental · 0 deprecated

AcceptWebSocketOptions — interface @experimental

maxBufferedBytes: number | undefined

AcceptedConnection — interface @experimental

close: (code?: number, reason?: string) => void
onClose: (handler: () => void) => () => void
transport: NetTransport

ClientSession — class @experimental

attempts: number
close: () => void
lastClose: { code: number; } | null
on: <T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>) => () => void
onState: (handler: StateHandler) => () => void
request: <Res = unknown, Req = unknown>(type: string, payload: Req, options?: SessionRequestOptions) => Promise<Res>
retryNow: () => void
send: (type: string, payload: unknown, codec?: PayloadCodec<never>) => void
serverNow: () => number
start: () => Promise<SessionWelcome>
state: SessionState
welcome: SessionWelcome | null
static new (options: ClientSessionOptions): ClientSession
static prototype: ClientSession

ClientSessionOptions — interface @experimental

backoff: SessionBackoff | undefined
connect: () => PlatformSocket
credentials: () => unknown | Promise<unknown>
heartbeat: false | { intervalMs: number; timeoutMs: number; } | undefined
maxFrameBytes: number | undefined
random: (() => number) | undefined
readyTimeoutMs: number | undefined
requestTimeoutMs: number | undefined
retries: number | undefined
retryDelayMs: number | undefined
wire: WireFormat | undefined

Contract — interface @experimental

broadcast: <K extends keyof E & string, Ctx extends SessionContext>(host: SessionHost<Ctx>, type: K, payload: Infer<E[K]>, filter?: (ctx: Ctx) => boolean) => number
client: (session: ClientSession) => ContractClient<R>
fingerprint: string
on: <K extends keyof E & string>(session: ClientSession, type: K, handler: MessageHandler<Infer<E[K]>>) => () => void
push: <K extends keyof E & string>(host: SessionHost<never>, playerId: string, type: K, payload: Infer<E[K]>) => boolean
serve: <Ctx extends SessionContext>(host: SessionHost<Ctx>, impl: ContractImpl<R, Ctx>) => () => void

ContractClient — type @experimental

{
    [K in keyof R]: (payload: ReqOf<R[K]>, options?: SessionRequestOptions) => Promise<ResOf<R[K]>>;
}

ContractImpl — type @experimental

{
    [K in keyof R]: (payload: ReqOf<R[K]>, ctx: Ctx, session: ServerSession<Ctx>) => ResOf<R[K]> | Promise<ResOf<R[K]>>;
}

IdempotencyBegin — type @experimental

| { state: 'new' }
    /** Already answered: reply with this and do not run the handler. */
    | { state: 'done'; outcome: IdempotentOutcome }
    /** Another call with this key is running; resolves with its outcome. */
    | { state: 'busy'; outcome: Promise<IdempotentOutcome | null> }

IdempotencyStore — interface @experimental

abandon: (key: string) => void | Promise<void>
begin: (key: string) => IdempotencyBegin | Promise<IdempotencyBegin>
finish: (key: string, outcome: IdempotentOutcome) => void | Promise<void>

IdempotentOutcome — interface @experimental

d: unknown

Infer — type @experimental

S extends Schema<infer T> ? T : never

MemoryIdempotencyOptions — interface @experimental

maxEntries: number | undefined
now: (() => number) | undefined
ttlMs: number | undefined

MemoryIdempotencyStore — class @experimental

abandon: (key: string) => void
begin: (key: string) => IdempotencyBegin
finish: (key: string, outcome: IdempotentOutcome) => void
size: number
static new (options?: MemoryIdempotencyOptions): MemoryIdempotencyStore
static prototype: MemoryIdempotencyStore

MessageHandler — type @experimental

(payload: T) => void

NET_ATTEMPT_FAILED — const @experimental

"the first attempt failed, retry"

NET_RATE_LIMITED — const @experimental

"rate limited"

NetChannel — class @experimental

dispose: (reason?: string) => void
handle: <Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>, codec?: RequestCodec<Req, Res>) => () => void
on: <T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>) => () => void
onBinary: (channel: number, handler: BinaryHandler) => () => void
request: <Res = unknown, Req = unknown>(type: string, payload: Req, options?: number | RequestOptions) => Promise<Res>
send: <T = unknown>(type: string, payload: T, codec?: PayloadCodec<T>) => void
sendBinary: (channel: number, payload: Uint8Array) => void
setIdempotencyScope: (scope: string) => void
setWire: (format: WireFormat, options?: { acceptJson?: boolean; }) => void
wire: WireFormat
static new (transport: NetTransport, opts?: NetChannelOptions): NetChannel
static prototype: NetChannel

NetChannelOptions — interface @experimental

heartbeat: NetHeartbeatOptions | undefined
idempotency: IdempotencyStore | undefined
idempotencyScope: string | undefined
limits: NetLimitOptions | undefined
requestTimeoutMs: number | undefined

NetHeartbeatOptions — interface @experimental

intervalMs: number
onDead: () => void
timeoutMs: number

NetLimitOptions — interface @experimental

burst: number | undefined
maxFrameBytes: number | undefined
messagesPerSecond: number | undefined
onViolation: ((kind: NetViolation) => void) | undefined

NetRequestError — class @experimental

code: NetRequestErrorCode
retryable: boolean
static new (message: string, code: NetRequestErrorCode): NetRequestError
static prototype: NetRequestError

NetRequestErrorCode — type @experimental

'timeout' | 'closed' | 'rate-limited' | 'retry' | 'remote'

NetTransport — interface @experimental

on: (event: "message", handler: (data: string | ArrayBuffer) => void) => () => void
send: (data: string | ArrayBuffer) => void

NetViolation — type @experimental

'frame-size' | 'rate' | 'wire'

PayloadCodec — interface @experimental

decode: (bytes: Uint8Array) => T
encode: (value: T) => Uint8Array
fromJSON: (json: unknown) => T
toJSON: (value: T) => unknown

ProtoMessage — interface @experimental

decode: (bytes: Uint8Array) => T
encode: (value: T) => Uint8Array
fromJSON: (json: unknown) => T
shape: string
toJSON: (value: T) => unknown

ProtoSchema — interface @experimental

codec: PayloadCodec<T>
describe: () => string
parse: (value: unknown, path?: string) => T

ReliableOrderedTransport — interface @experimental

delivery: "reliable-ordered"
on: (event: "message", handler: (data: string | ArrayBuffer) => void) => () => void
send: (data: string | ArrayBuffer) => void

RequestCodec — interface @experimental

req: PayloadCodec<Req>
res: PayloadCodec<Res>

RequestDef — interface @experimental

req: Schema<Req>
res: Schema<Res>

RequestHandler — type @experimental

(payload: Req) => Res | Promise<Res>

RequestOptions — interface @experimental

codec: RequestCodec<any, any> | undefined
idempotencyKey: string | undefined
timeoutMs: number | undefined

Rng — interface @experimental

chance: (p: number) => boolean
float: () => number
fork: (label: string | number) => Rng
int: (min: number, max: number) => number
nextU32: () => number
pick: <T>(items: readonly T[]) => T
shuffle: <T>(items: readonly T[]) => T[]
weighted: <T>(items: readonly T[], weight: (item: T) => number) => T

RngSeed — type @experimental

number | string | readonly (number | string)[]

SESSION_HELLO — const @experimental

"session:hello"

SESSION_PROTOCOL_VERSION — const @experimental

1

Schema — interface @experimental

describe: () => string
parse: (value: unknown, path?: string) => T

SchemaError — class @experimental

path: string
static new (path: string, message: string): SchemaError
static prototype: SchemaError

ServerSession — interface @experimental

close: (code?: number, reason?: string) => void
ctx: Ctx
push: (type: string, payload: unknown, codec?: PayloadCodec<never>) => void

SessionBackoff — interface @experimental

factor: number | undefined
initialMs: number | undefined
jitter: number | undefined
maxMs: number | undefined

SessionCloseCode — const @experimental

{ readonly replaced: 4001; readonly helloTimeout: 4002; readonly unavailable: 4003; readonly abuse: 4004; }

SessionContext — interface @experimental

playerId: string

SessionHandler — type @experimental

(payload: Req, ctx: Ctx, session: ServerSession<Ctx>) => Res | Promise<Res>

SessionHelloRequest — interface @experimental

credentials: unknown
version: number
wire: "json" | "pb" | undefined

SessionHelloResponse — type @experimental

| {
        ok: true;
        playerId: string;
        /** The server's clock at the moment it answered, in epoch milliseconds. */
        serverTimeMs: number;
        /** The encoding both ends write from now on. Absent means JSON. */
        wire?: 'json' | 'pb';
        /** Anything the game wants the client to have at once (a renewed token). */
        data?: unknown;
    }
    | { ok: false; error: string; /** Retrying cannot help; the client stops. */ fatal: boolean }

SessionHost — class @experimental

accept: (connection: AcceptedConnection) => void
broadcast: (type: string, payload: unknown, filter?: (ctx: Ctx) => boolean, codec?: PayloadCodec<never>) => number
close: (code?: number, reason?: string) => void
connectionCount: number
handle: <Req = unknown, Res = unknown>(type: string, handler: SessionHandler<Ctx, Req, Res>, codec?: RequestCodec<Req, Res>) => () => void
playerCount: number
push: (playerId: string, type: string, payload: unknown, codec?: PayloadCodec<never>) => boolean
static new <Ctx extends SessionContext = SessionContext>(options: SessionHostOptions<Ctx>): SessionHost<Ctx>
static prototype: SessionHost<any>

SessionHostOptions — interface @experimental

authenticate: (credentials: unknown, connection: AcceptedConnection) => Ctx | Promise<Ctx>
heartbeat: false | { intervalMs: number; timeoutMs: number; } | undefined
helloTimeoutMs: number | undefined
idempotency: IdempotencyStore | undefined
limits: Pick<NetLimitOptions, "burst" | "maxFrameBytes" | "messagesPerSecond"> | undefined
maxSessions: number | undefined
maxViolationsPerMinute: number | undefined
requestTimeoutMs: number | undefined
wire: "json" | "pb" | "pb-only" | undefined

SessionRejected — class @experimental

fatal: boolean
static new (message: string, fatal?: boolean): SessionRejected
static prototype: SessionRejected

SessionRequestOptions — interface @experimental

codec: RequestCodec<any, any> | undefined
idempotencyKey: string | undefined
retries: number | undefined
timeoutMs: number | undefined

SessionState — type @experimental

'idle' | 'connecting' | 'ready' | 'reconnecting' | 'closed'

SessionWelcome — interface @experimental

data: unknown
playerId: string

WebSocketLike — interface @experimental

bufferedAmount: number | undefined
close: (code?: number, reason?: string) => void
on: { (event: "message", listener: (data: unknown, isBinary: boolean) => void): unknown; (event: "close", listener: () => void): unknown; (event: "error", listener: (err: unknown) => void): unknown; }
send: (data: string | ArrayBufferLike | ArrayBufferView) => void
terminate: (() => void) | undefined

WireFormat — type @experimental

'json' | 'pb'

acceptWebSocket — function @experimental

<Ctx extends SessionContext>(host: SessionHost<Ctx>, socket: WebSocketLike, options?: AcceptWebSocketOptions): void

createRng — function @experimental

(seed: RngSeed): Rng

defineContract — function @experimental

<R extends RequestDefs, E extends EventDefs = Record<never, never>>(def: { requests: R; events?: E; }): Contract<R, E>

hashSeed — function @experimental

(seed: RngSeed): number

jsonCodec — const @experimental

PayloadCodec<unknown>

proto — function @experimental

<T>(message: ProtoMessage<T>, check?: (value: T) => void): ProtoSchema<T>

protoAs — function @experimental

<T, W>(message: ProtoMessage<W>, view: { to(value: T): W; from(wire: W): T; }, check?: (value: T) => void): ProtoSchema<T>

s — const @experimental

{ string(opts?: { min?: number; max?: number; pattern?: RegExp; }): Schema<string>; int(opts?: { min?: number; max?: number; }): Schema<number>; number(opts?: { min?: number; max?: number; }): Schema<number>; boolean(): Schema<boolean>; literal<const T extends string | number | boolean | null>(value: T): Schema<T>; enum<const T extends readonly [string, ...string[]]>(values: T): Schema<T[number]>; array<T>(item: Schema<T>, opts?: { max?: number; }): Schema<T[]>; object<S extends Shape>(shape: S): Schema<ObjectOf<S>>; record<T>(value: Schema<T>, opts?: { maxKeys?: number; }): Schema<Record<string, T>>; optional<T>(inner: Schema<T>): Schema<T | undefined>; nullable<T>(inner: Schema<T>): Schema<T | null>; unknown(): Schema<unknown>; }