Actor

Actor

An actor is a type of model that automatically instantiates a pawn in the view when it’s created. This actor/pawn pair has a private communication channel that allows them to talk directly with each other. The actor handles the simulation, and the pawn handles input and output. When the actor is destroyed, the pawn is destroyed as well.

Extends

Members

# (readonly) pawn :Pawn

Returns the class type of the actor's corresponding pawn. Actors inheriting from this base class should overload this getter to specify their pawn type.

Type:
Example:
class MyActor extends Actor {
	    get pawn() { return MyPawn }
    }

# (readonly) doomed :Boolean

Set to true by the actor's destroy() method. Use it at the start of a recurring tick to make sure it doesn't continue as a zombie after the actor has been destroyed.

Type:
  • Boolean
Example:
tick() {
        if (this.doomed) return;
        future(50).tick();
    }

Methods

# (static) create(optionsopt)

Create an instance of an actor and automatically spawn its corresponding pawn. Create calls the user-defined init() method and passes in options to set the actor's initial properties.

Note: When your actor is no longer needed, you must destroy it. Otherwise it will be kept in the snapshot forever.

Warning: Never create an actor instance using new, or override its constructor.

Parameters:
Name Type Attributes Description
options Object <optional>

An object containing the initial properties of the actor. Passed to the actor's init().
Example 
const actor = MyActor.create({scale: 2})

# init(optionsopt)

This is called by create() to initialize the actor. In your actor subclass, this is the place to subscribe to or listen for events, or use a future message to start a recurring tick.

Super.init() calls set() to set the actor's initial properties from the options. It also automatically spawns the actor's pawn. The properties are set before the pawn is created.

Parameters:
Name Type Attributes Description
options Object <optional>

An object containing the initial properties of the actor.
Example 
class MyActor extends Actor {
    get scale() {return this._scale || 1};
}

# destroy()

Deletes the actor and its associated pawn.

Note: When your actor is no longer needed, you must destroy it. Otherwise it will be kept in the snapshot forever. You can check if an actor has been destroyed with the doomed flag.

Fires:
  • destroyActor

# set(optionsopt)

Sets one or more internal properties. The internal name of each property will be the name of the option prefaced by "_". You should define corresponding getters to access these internal properties.

    class MyActor extends Actor {
        get scale() {return this._scale || 1};
    }

    const actor = MyActor.create();
    actor.set({scale: 2, translation: [0,0,1]});
    const scale = actor.scale;

Actors inheriting from this base class can overload set() to trigger actions when a property changes:

    class MyActor extends Actor {

        set(options = {}) {
            super.set(options);
            if ('scale' in options ) this.say("scaleChanged", this.scale);
        }

    }

Note: The reason to use set() with getters is to reduce snapshot size. Worldcore actors can have dozens of properties. Multiplied by hundreds of actors, the total number of properties stored in the snapshot can grow large. Using set() with getters prevents defaults from being stored in the snapshot.

Parameters:
Name Type Attributes Description
options Object <optional>

An object containing the properties to be changed and their new values.

# 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 actor.

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 actor listens for an event sent by say(), the event will be routed through the reflector. 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);

# ignore(event)

Removes an existing listen() subscription.

Parameters:
Name Type Description
event string

The name of the event.
Example 
this.ignore("priorityChanged");

# service(name) → {ModelService}

Returns a pointer to the named model service.

Parameters:
Name Type Description
name string

The public name of the model service.
Inherited From:
Returns:
Type
ModelService