Core API Reference - Multisynq Docs

This page provides a comprehensive reference for the Multisynq Core JavaScript API. Use the table of contents to navigate between major sections like Model, View, and Session.

Core Architecture

Multisynq provides a revolutionary client-side synchronized architecture for building real-time collaborative applications. Unlike traditional server-client architectures, Multisynq runs your application logic on every user’s device in perfect synchronization.

Client-Side Synchronization

Multisynq applications run entirely on the client side. All application logic executes on every user’s device in a deterministic virtual machine, ensuring perfect synchronization without custom server code.

Model-View Separation

Multisynq enforces a strict architectural pattern:

Model: Contains all application logic and state. Runs in a deterministic VM.
View: Handles user interface and input. Can read from the model but never writes directly.
Events: All communication happens through a publish-subscribe event system.

Reflector Network

Simple, stateless message-passing servers handle:

Event ordering from all clients into a canonical stream
Synchronized time (heartbeat ticks)
No application logic execution

Installation & Setup

Installation

Add Multisynq to your HTML page:

<script src="https://cdn.jsdelivr.net/npm/@multisynq/client@latest/bundled/multisynq-client.min.js"></script>

Or import as an ES module:

import * as Multisynq from "https://cdn.jsdelivr.net/npm/@multisynq/client@latest/bundled/multisynq-client.esm.js";

API Key

Get your free API key from multisynq.io/coder.

`Multisynq.Model`

The Model class provides the foundation for all synchronized objects in Multisynq applications. Models handle computation, maintain state, and ensure that all users see identical behavior through deterministic execution.

Key Concept: Models run identically on every user’s device, ensuring perfect synchronization. They communicate with Views only through publish/subscribe events.

Critical Rules

Implementation Requirements:

NEVER use new constructor - Always use Model.create()
NEVER override the constructor - Override init() method instead
Always call Model.register(classId) for all Model subclasses
Always call destroy() when a model instance is no longer needed

Properties

`id`

string

Unique identifier for the model within the session.

`sessionId`

sessionId

string

Global session identifier shared by all users.

`viewCount`

viewCount

number

Number of users currently in the session.

`activeSubscription`

activeSubscription

object

Information about the currently executing subscription handler (e.g., { scope, event, source }).

Instance Methods

`init(options, persistentData)`

Override this method to initialize your model. Called automatically by create().

options

object

Configuration options passed to create().

persistentData

object

Data restored from previous sessions (if using persistence).

`publish(scope, event, data)`

Send an event to a specific scope.

scope

string

required

Event scope (e.g., this.sessionId).

event

string

required

Event name.

data

any

Data to send with the event.

scope

string

required

Event scope to listen to.

event

string

required

Event name to handle.

handler

function

required

Method to call when event occurs.

`unsubscribe(scope, event, handler)`

Remove an event handler.

`future(milliseconds)`

Schedule a method call for future execution. Returns a proxy object that you call a method on. this.future(1000).myMethod(arg1, arg2);

milliseconds

number

default:"0"

Delay in milliseconds before execution.

`cancelFuture(method)`

Cancel a previously scheduled future message.

method

function

required

The method that was scheduled.

`now()`

Get the current model time in milliseconds.

`random()`

Generate a synchronized random number (0-1) identical across all users.

`destroy()`

Clean up a model instance when it’s no longer needed. This is critical for preventing memory leaks.

`getModel(id)`

Look up another model in the session by its ID.

string

required

Model ID to look up.

Static Methods

`Model.create(options)`

Create a new model instance. Always use this instead of new.

options

object

Configuration options passed to init().

`Model.register(classId)`

classId

string

required

Unique identifier for the model class.

Well-Known Models

`beWellKnownAs(name)`

Make a model instance globally accessible by a string name.

name

string

required

Global name for this model.

`wellKnownModel(name)`

Access a globally registered model from an instance method.

name

string

required

Name of the well-known model.

`Model.wellKnownModel(name)`

Access a globally registered model from a static method.

name

string

required

Name of the well-known model.

`Multisynq.View`

The View class represents the local, user-interface portion of Multisynq applications. Views are local to each device and handle user input, display output, and UI interactions.

Key Concept: Views are local and independent on each device. They subscribe to Model events to stay synchronized and publish events to communicate with Models.

Constructor

`new View(model, viewOptions)`

Creates a new View instance. Called automatically during Session.join().

model

Model

required

The model instance this view will display.

viewOptions

object

Optional configuration passed from Session.join().

Properties

`viewId`

viewId

string

Identifies the current user’s connection to the session.

`session`

session

object

Reference to the session object.

Instance Methods

`publish(scope, event, data)`

Send an event. For view-to-model communication, data must be serializable.

scope

string

required

Event scope.

event

string

required

Event name.

data

any

Event data.

scope

string

required

Event scope to listen to.

eventSpec

string | object

required

Event name or specification object for handling type.

handler

function

required

Function to call when event occurs.

Event Handling Types

"queued" (default): Called once per publish on the next frame.
"oncePerFrame": Called only once per frame with the latest data. Ideal for rendering updates.
"immediate": Called synchronously during the publish call.

// Example of 'oncePerFrame' for smooth rendering
this.subscribe(this.model.id, {
    event: "positionChanged",
    handling: "oncePerFrame"
}, this.updatePosition);

`unsubscribe(scope, event, handler)`

Remove an event handler.

`detach()`

Clean up the view when it is no longer needed. This is critical for preventing memory leaks.

`now()`

Get the current model time in milliseconds.

`externalNow()`

Get the latest timestamp from the reflector, which may be ahead of now() if the client is catching up.

`extrapolatedNow()`

Get an extrapolated time based on the last reflector timestamp and local time. Useful for predictive rendering.

`update(time)`

Called once per frame on the root view (if using "auto" stepping). Override this for frame-based logic like input polling or animation.

time

number

Frame timestamp from requestAnimationFrame.

`wellKnownModel(name)`

Access a globally registered model from a view instance.

name

string

required

Name given to Model.beWellKnownAs().

`Multisynq.Session`

The Session class is the main entry point for joining and managing Multisynq sessions.

`Session.join(parameters)`

The primary method for creating or joining a Multisynq session. It returns a Promise that resolves to a session object.

Key Parameters

apiKey

string

required

Your API key.

appId

string

required

Unique application identifier (e.g., “com.example.myapp”).

model

class

required

Your root Model class.

view

class

Your root View class.

name

string

Session name. Use Multisynq.App.autoSession() for URL-based names.

password

string

Session password. Use Multisynq.App.autoPassword() for URL-based passwords.

options

object

Options passed to your Model’s init() method.

tps

number

default:"20"

Ticks per second from the reflector (1-60).

debug

string | string[]

Debug options for console logging.

A full list of parameters can be found in the types.d.ts file.

Session Object

The object returned from Session.join() contains:

id: Unique session identifier.
view: Your root view instance.
leave(): A function to leave the session.
step(time): A function for manual stepping.

`Multisynq.App`

A collection of utilities for managing session URLs, QR codes, and debugging tools. (This section is a placeholder and will be expanded by the automation script.)

`Multisynq.Data`

The API for storing and retrieving large, immutable data blobs associated with a session. (This section is a placeholder and will be expanded by the automation script.)

System Events

Your models can subscribe to system-level events published on the sessionId scope.

`view-join`

Published when a new user enters the session.

data

string | object

The viewId of the joining user, or {viewId, viewData} if viewData was provided to Session.join().

`view-exit`

Published when a user leaves the session.

data

string | object

The viewId of the exiting user, or {viewId, viewDta}.

`synced`

A view-only event published when the local session has caught up to the reflector and the loading screen is hidden.

data

boolean

true if in sync, false if backlogged.

Core API

​Core Architecture

​Client-Side Synchronization

​Model-View Separation

​Reflector Network

​Installation & Setup

​Installation

​API Key

​Multisynq.Model

​Critical Rules

​Properties

​id

​sessionId

​viewCount

​activeSubscription

​Instance Methods

​init(options, persistentData)

​publish(scope, event, data)

​subscribe(scope, event, handler)

​unsubscribe(scope, event, handler)

​future(milliseconds)

​cancelFuture(method)

​now()

​random()

​destroy()

​getModel(id)

​Static Methods

​Model.create(options)

​Model.register(classId)

​Well-Known Models

​beWellKnownAs(name)

​wellKnownModel(name)

​Model.wellKnownModel(name)

​Multisynq.View

​Constructor

​new View(model, viewOptions)

​Properties

​viewId

​session

​Instance Methods

​publish(scope, event, data)

​subscribe(scope, eventSpec, handler)

Event Handling Types

​unsubscribe(scope, event, handler)

​detach()

​now()

​externalNow()

​extrapolatedNow()

​update(time)

​wellKnownModel(name)

​Multisynq.Session

​Session.join(parameters)

​Key Parameters

​Session Object

​Multisynq.App

​Multisynq.Data

​System Events

​view-join

​view-exit

​synced

Core Architecture

Client-Side Synchronization

Model-View Separation

Reflector Network

Installation & Setup

Installation

API Key

`Multisynq.Model`

Critical Rules

Properties

`id`

`sessionId`

`viewCount`

`activeSubscription`

Instance Methods

`init(options, persistentData)`

`publish(scope, event, data)`

`subscribe(scope, event, handler)`

`unsubscribe(scope, event, handler)`

`future(milliseconds)`

`cancelFuture(method)`

`now()`

`random()`

`destroy()`

`getModel(id)`

Static Methods

`Model.create(options)`

`Model.register(classId)`

Well-Known Models

`beWellKnownAs(name)`

`wellKnownModel(name)`

`Model.wellKnownModel(name)`

`Multisynq.View`

Constructor

`new View(model, viewOptions)`

Properties

`viewId`

`session`

Instance Methods

`publish(scope, event, data)`

`subscribe(scope, eventSpec, handler)`

`unsubscribe(scope, event, handler)`

`detach()`

`now()`

`externalNow()`

`extrapolatedNow()`

`update(time)`

`wellKnownModel(name)`

`Multisynq.Session`

`Session.join(parameters)`

Key Parameters

Session Object

`Multisynq.App`

`Multisynq.Data`

System Events

`view-join`

`view-exit`

`synced`