Pawn

Pawn

When an actor is instantiated, it automatically creates a corresponding pawn in the view. The pawn handles input and output, while the actor handles simulation. Actors are synchronized across all clients, but pawns are not.

Extends

Members

# (readonly) actor :Actor

Returns the pawn's actor. You can read the actor's current state directly using this pointer. You should never write to it.

Type:
Example:
const currentTranslation = this.actor.translation;

# (readonly) time :number

Returns the system time in milliseconds at the last frame update.

Type:
  • number
Overrides:

# (readonly) delta :number

Returns the time in milliseconds between the last frame update and the previous one.

Type:
  • number
Overrides:

Methods

# destroy()

Called automatically when the pawn's actor is destroyed. You should never call it directly. It cancels all of the pawn's subscriptions. You can overload it to do other teardown, like deallocating render objects or releasing resources.

Example
class MyPawn extends Pawn {
        destroy() {
            super.destroy();
            this.glBuffer.dispose();
        }
    }

# say(event, dataopt)

Publishes an event with its scope set to the actor.id. Both the actor and the pawn can listen for events coming from the pawn.

Note: Events published by the pawn and subscribed to by the actor will be sent via the reflector to every client.

Parameters:
Name Type Attributes Description
event string

The name of the event.

data Object <optional>

An optional data object.

Example
this.say("serialNumber", 1234);
this.say("newColor", [0.5, 0.5, 0.5]);
this.say("updatePrice", {dollars: 2, cents:95});

# listen(event, handler)

Subscribes to an event with its scope set to the actor.id. The data object from the say method will be passed as an argument to the handler.

Parameters:
Name Type Description
event string

The name of the event.

handler function

The event handler (must be a method of this).

Example
this.listen("priorityChanged", this.onNewPriority);

# listenImmediate(event, handler)

Subscribes to an event with its scope set to the actor.id. The event handler will be called immediately when the event is published. The data object from the say method will be passed as an argument to the handler.

Note: With a normal listen(), events coming from the actor are queued until all simulation has finished. However if a pawn needs to override this default behavior, use listenImmediate() instead. This doesn't make things run any faster, but may be necessary in rare cases where an event triggers listening to or ignoring other events.

Parameters:
Name Type Description
event string

The name of the event.

handler function

The event handler (must be a method of this).

# listenOnce(event, handler)

Subscribes to an event with its scope limited to this actor/pawn pair. The event handler will be called when the event is published. The data object from the say method will be passed as an argument to the handler. In the case where multiple copies of the same event are sent from the actor to the pawn during the same frame update, listenOnce() will only respond to the final one.

You should use listenOnce whenever a new event completely overrides a previous one. For example, when a snapshot loads, the model fast-forwards through a sequence of cached events to bring itself in synch with the other clients. However, there's no need for the view to process all these events; in most cases just acting on the final update is sufficient. Using listenOnce will greatly speed up the synch process.

Parameters:
Name Type Description
event string

The name of the event.

handler function

The event handler (must be a method of this).

# ignore(event)

Removes an existing listen() subscription.

Parameters:
Name Type Description
event string

The name of the event.

Example
this.ignore("priorityChanged");

# service(name) → {ViewService}

Returns a pointer to the named view service.

Parameters:
Name Type Description
name string

The public name of the view service.

Returns:
Type
ViewService

# modelService(name) → {ModelService}

Returns a pointer to the named model service.

Note: The view should only read from the model service. Do not write to it, or call methods that modify it.

Parameters:
Name Type Description
name string

The public name of the model service.

Returns:
Type
ModelService