alpha

Session

Session

The Session API is under construction.

New in 0.4: Session.join takes a single argument object instead of multiple unnamed arguments

New in 0.3: use Session.join instead of startSession(). The returned object has a new leave() method for leaving that session.

Methods

(async, static) join(parameters) → {Promise}

Join a Croquet session.

Joins a session by instantiating the root model (for a new session) or resuming from a snapshot, then constructs the view root instance.

The appId identifies each Croquet app. It must be a globally unique identifier following the Android convention, e.g. "com.example.myapp". Each dot-separated segment must start with a letter, and only letters, digits, and underscores are allowed.

The session name identifies individual sessions within an app. You can use it for example to create different sessions for different users. That is, a user in session "ABC" will not see a user in "DEF". One simple way to create unique sessions is via Croquet.App.autoSession() which will use or generate a random name in the query part (?...) of the current url. (If you use a constant, then all users will end up in the same session. This is what we do in some of our tutorials for simplicity, but actual apps should manage sessions.)

The session password is used for end-to-end encryption of all data leaving the client. If your app does not need to protect user data, you will still have to provide a constant dummy password. One simple way to have individual passwords is via Croquet.App.autoPassword() which will use or generate a random password in the hash part (#...) of the current url.

A session id is created from the given session name, and a hash of all the registered Model classes and Constants. This ensures that only users running the exact same source code end up in the same session, which is a prerequisite for perfectly replicated computation.

The session id is used to connect to a reflector. If there is no ongoing session, an instance of the model class is created (which in turn typically creates a number of submodels). Otherwise, the previously stored modelRoot is deserialized from the snapshot, along with all additional models.

That root model instance is passed to the constructor of your root view class. The root view should set up the input and output operations of your application, and create any additional views as to match the application state as found in the models.

Then the Croquet main loop is started (unless you pass in a step: "manual" parameter). This uses requestAnimationFrame() for continuous updating. Each step of the main loop executes in three phases:

  1. Simulation: the models execute the events received via the reflector, and the future messages up to the latest time stamp received from the reflector. The events generated in this phase are put in a queue for the views to consume.
  2. Event Processing: the queued events are processed by calling the view's event handlers. The views typically use these events to modify some view state, e.g. moving a DOM element or setting some attribute of a Three.js object.
  3. Updating/Rendering: The view root's update() method is called after all the queued events have been processed. In some applications, the update method will do nothing (e.g. DOM elements are rendered after returning control to the browser). When using other UI frameworks (e.g. Three.js), this is the place to perform the actual rendering. Also, polling input and other tasks that should happen in every frame should be placed here.

Parameters

parameter values Description
appId string unique application identifier as dot-separated words (e.g. "com.example.myapp")
name string a name for this session (e.g. "123abc")
password string a password for this session (used for end-to-end encryption of messages and snapshots)
model class the root Model class for your app
view class the root View class for your app
options JSON object passed into the root model's init() function (no default)
step "auto" automatic stepping via requestAnimationFrame() (default)
"manual" application-defined main loop is responsible for calling the session's step() function
tps 0...60 heartbeat ticks per second generated by reflector when no messages are sent by any user (default 20)
debug array or string pass array of strings to enable multiple debug logs
"session" logs session id and connections
"messages" received from reflector, after decryption, raw messages are in the WebSocket debugger
"sends" sent to reflector, before encryption, raw messages are in the WebSocket debugger
"snapshot" snapshot stats
"data" data API stats
"hashing" code hashing to derive sessionId / islandId
"subscribe" adding/removing subscriptions
"classes" registering classes
"ticks" each tick received
Examples

auto name, password, and main loop

Croquet.Session.join({
    appId: "com.example.myapp",             // namespace for session names
    name: Croquet.App.autoSession(),        // session via URL arg
    password: Croquet.App.autoPassword(),   // password via URL arg
    model: MyRootModel,
    view: MyRootView,
    debug: ["session"],
});

manual name, password, and main loop

Croquet.Session.join({ appId: "com.example.myapp", name: "abc", password: "password", model: MyRootModel, view: MyRootView, step: "manual"}).then(session => {
    function myFrame(time) {
        session.step(time);
        window.requestAnimationFrame(myFrame);
    }
    window.requestAnimationFrame(myFrame);
});
Parameters:
Name Type Description
parameters Object
Properties
Name Type Attributes Description
appId String

application identifier

name String

session name

password String

session password

model Model

root Model class

view View

root View class

options Object <nullable>

options passed to root Model's init

step String <nullable>

"auto" | "manual"

tps String <nullable>

ticks per second (0 to 60)

debug String <nullable>

enable debug logs

Returns:

Promise that resolves to an object describing the session:

{
    id,           // the session id
    view,         // the ViewRoot instance
    step(time),   // function for "manual" stepping
    leave(),      // force leaving the session
}

where

  • view is an instance of the ViewRoot class
  • step(time) is a function you need to call in each frame if you disabled automatic stepping. The time argument is expected to be in milliseconds, monotonically increasing - for example, the time received by a function that you passed to window.requestAnimationFrame.
  • leave() is an async function that forces this session to disconnect.
Type
Promise