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:
- 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.
- 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.
- 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
|
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 theViewRoot
classstep(time)
is a function you need to call in each frame if you disabled automatic stepping. Thetime
argument is expected to be in milliseconds, monotonically increasing - for example, the time received by a function that you passed towindow.requestAnimationFrame
.leave()
is an async function that forces this session to disconnect.
- Type
- Promise