SDK-referentie

MiniEngine-client

MiniEngine houdt één websocketverbinding met een kamer open, ontvangt snapshots en stuurt opdrachten. Hij werkt in de browser en in Node.

import { MiniEngine, loadSession } from '/sdk/mini-engine.js';

const session = loadSession('HWKRTZ', 'player');
if (!session) throw new Error('Geen kamersleutel in deze sessie.');
const client = new MiniEngine(session);
client.on('snapshot', (room) => render(room));
client.connect();
await client.waitForSnapshot();

Opties #

new MiniEngine({ code, token, baseUrl?, reconnectDelay?, requestTimeout?, WebSocket? })

RoomCredentials uit createRoom, joinRoom of loadSession passen direct als opties.

Eigenschappen #

Verbinding #

connect() #

Opent de verbinding en geeft de client terug, dus new MiniEngine(…).connect() kan in één regel. De client stuurt { type: 'auth', token } als eerste bericht en is verbonden zodra de eerste snapshot binnenkomt.

resume() #

Verbindt een gesloten client opnieuw, bijvoorbeeld na session_replaced of bij pageshow. De laatste room blijft staan tot er een verse snapshot is.

close() #

Stopt de verbinding en alle automatische pogingen. Openstaande opdrachten en wachtende waitForSnapshot-beloftes worden afgewezen met code closed.

Snapshots #

waitForSnapshot(predicate?, options?) #

waitForSnapshot(
  predicate?: (room: Snapshot) => boolean,
  options?: { timeout?: number; signal?: AbortSignal },
): Promise<Snapshot>

Geeft de huidige snapshot als die al voldoet, of wacht op een volgende. De time-out is standaard requestTimeout; daarna volgt een fout met code snapshot_timeout.

await client.waitForSnapshot((room) => room.status === 'running');

Opdrachten #

Alle opdrachten geven een Promise<Ack>. Bij een mutatie komt de nieuwe snapshot binnen vóór de bevestiging.

action(name, data?, options?) #

action(name: string, data?: Json, options?: { actionId?: string }): Promise<Ack>

Stuurt een spelactie. Zonder actionId maakt de SDK een nieuwe unieke id. Zie acties en action-id's.

ready(ready?) #

ready(ready = true): Promise<Ack>

Zet je eigen klaarstatus in de lobby.

lifecycle(status) #

lifecycle(status: 'running' | 'finished' | 'lobby'): Promise<Ack>

Alleen de host. Volgt lobby → running → finished → lobby.

setSettings(settings) #

setSettings(settings: S): Promise<Ack>

Alleen de host. Vervangt het hele instellingenobject; de SDK stuurt de versie van client.room als expected_version mee.

configure(config) #

configure(config: { display_enabled?: boolean; allow_late_join?: boolean }): Promise<Ack>

Alleen de host, alleen in de lobby. De spelleidermodus kies je bij het maken van de kamer.

setState(state) #

setState(state: { expected_version: number; public_state: P; host_state?: Json; player_states?: Record<string, Json> }): Promise<Ack>

Alleen de host van een spel met runtime: "host". Vervangt de volledige spelstand. Een serverspel weigert dit.

request(type, payload?) #

request(type: string, payload?: Record<string, unknown>): Promise<Ack>

Een ruwe websocketopdracht met een eigen request_id. De andere methoden zijn hierop gebouwd. Niet verbonden: direct een fout met code not_connected.

Herverbinden #

Bij een tijdelijke sluiting (host_lagged, heartbeat_timeout, rate_limit, server_shutdown) of een weggevallen verbinding verbindt de client opnieuw, met een oplopende wachttijd tot maximaal vijftien seconden. Na rate_limit wacht hij minstens 1,2 seconde. Elke nieuwe verbinding authenticeert opnieuw.

Bij een definitieve sluiting (session_revoked, room_deleted, room_expired, session_replaced) stopt de client en krijg je het event closed.

Openstaande opdrachten worden bij uitval afgewezen met code disconnected, en na de time-out met request_timeout. De SDK speelt opdrachten nooit opnieuw af. Kijk na een onzeker resultaat eerst naar de nieuwste snapshot.

Generieke types #

const client = new MiniEngine<PublicState, Settings, PrivateState>(session);

Zo krijgen room.public_state, room.settings en room.private_state jouw eigen types. Zie types.