Session

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

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"],
});

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);
});

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