Easy Multiplayer v0.4 Consumer API

This is the game developer's reference for the public v0.4 authoring surface. Internal engine, ledger, bus, and worker classes are not compatibility APIs.

Start with the quickstart.

Import

import { EasyMultiplayer } from
  'https://libs.letsinspire.com/easy_multiplayer/releases/0.4/EasyMultiplayer.js';

Primary namespace:

EasyMultiplayer.performanceMode

defineGame(definition)

Creates and freezes a game definition.

const game = EasyMultiplayer.performanceMode.defineGame({
  initialState: () => ({}),
  queries: {},
  step(ctx) {},
});

Fields:

Game delivery forms:

game: inlineDefinition

Inline games are time-sliced only.

game: {
  module: new URL('./game.js', import.meta.url),
  export: 'createGame',
  options: {},
}

Module games work in worker and time-sliced modes. The factory options must be structured-cloneable and identical on every peer.

createSession(options)

const session = EasyMultiplayer.performanceMode.createSession({
  room: { id: 'room-123', appId: 'my-game' },
  game: { module: gameUrl, export: 'createGame' },
  getLocalInputs,
  tickMs: 50,
  maxParticipants: 4,
  dev: true,
});

Stable options

Input envelope

getLocalInputs: () => ({
  discoverable: true,
  stopParticipating: false,
  input: {
    left: held.left,
    jumpPress: counters.jump,
  },
})

• input is the game payload seen by query predicates.
• discoverable allows discovery predicates to inspect the candidate.
• stopParticipating ends the current participation attempt.
• Non-discoverable input from a spectator with no active discoverable attempt may be silenced before transmission.

Session methods

Runtime status includes runtimeMode, runtimeFallback, tick, connected, isLive, localId, participant counts/peer IDs, and rollback count.

Step context

step(ctx) receives:

Query predicates

Gameplay query:

const moveAxis = (inputs, context) =>
  Number(inputs[0]?.right) - Number(inputs[0]?.left);

inputs[i] corresponds to participantIds[i]. Access builds the dependency read-set. context is frozen/canonicalized for later rechecks. Return a specific serializable decision, never the inputs accessor itself.

Discovery predicate:

const claimSlot = (input, context) => input?.claimSlot === context.slot;

Discovery receives one candidate input as its first argument, not the gameplay inputs array. The second argument is the frozen context supplied to discoverParticipants.

rawInputs()

Requires:

simpleMode: true

Usage:

const inputs = ctx.rawInputs();
if (inputs[playerId].left) moveLeft();

Each property access is one standard query. It remains branch-sensitive and rollback-correct, but separate fields produce separate decision results. Under dev, first use warns that named queries are preferred.

World facade

Both schema and proxied worlds route engine services:

const world = ctx.world();
world.query(...);
world.participants();
world.isParticipant(id);
world.discoverParticipants(...);
world.rawInputs();
world.emit(...);

Schema mode additionally provides class-bound table helpers:

world.get(Type, id);
world.all(Type);
world.spawn(Type, id, record);
world.owned(Type, ownerId, factory);
world.destroy(entityOrType, id);
world.table(name);
world.id(prefix, ...parts);

Canonical state rules

Default proxied state supports plain objects, arrays, and JSON scalars. It rejects functions, class instances, Map, Set, Date, undefined, and object aliases.

Standard array reads work normally. Mutating arrays support push, pop, shift, unshift, splice, sort, reverse, copyWithin, and fill, provided the final state contains no persistent object aliases.

Writes are legal only inside step. Canonical relationships should use stable IDs:

state.heldItemId = item.id;

Do not store the same mutable item object in two locations.

Mirror contract

Proxied mode:

const mirror = session.getMirror();
const state = mirror.state; // deeply frozen

Schema mode:

const players = mirror.tryTable('players');
for (const id of players.ids()) {
  const row = players.get(id);
}

Treat mirrors as replaceable, read-only projections. Never use mirror values to drive canonical simulation.

Presentation

Simulation code must not access DOM, canvas, audio, timers, or sockets.

Use trails for interpolation:

ctx.trail(player.id, { x: player.x, y: player.y });

Use deterministic events for one-shot presentation:

ctx.emit('sound', { key: `jump:${player.id}:${ctx.tick}`, name: 'jump' });

Only finalized events should reach irreversible browser effects.

Advanced configuration

Common expert settings:

advanced: {
  engine: {
    inputDelay: 1,
    autoRelease: { demote: 'consume' },
  },
  backend: {
    snapshotInterval: 10,
    patchesInterval: 3,
  },
  workerPoolSize: 3,
}

Advanced keys are validated but intentionally outside the stable compatibility contract. Measure before tuning.

Custom transport

Provide one of room or transport. A custom transport supplies stable local identity, message delivery, peer events, current peers, disconnect, and the clock-sync channel. See contracts/transport.md for the exact interface.

Determinism checklist

• Same initial state and queried results produce the same next state.
• No wall clock, ambient randomness, asynchronous work, DOM, audio, or network calls in step.
• Every mutable gameplay fact is canonical.
• Every input read goes through query, discovery, or explicitly enabled rawInputs.
• Queries are pure and registered.
• Participant input is guarded by membership.
• IDs remain stable across deletion and reordering.
• Presentation effects wait for confirmation.