CardActor

CardActor

A card in Croquet Microverse is represented with a class called CardActor on the Croquet's Model side, and CardPawn on the Croquet's View side.

An instance of CardActor and CardPawn can have a list of behaviors. Each of such behavior can use the features provided by the CardActor or CardPawn to which it is attached. For example, A CardActor implements a method called createCard(), which takes a card spec and creates a new card and place it in the world. A behavior can simply call:

  this.createCard({...});

to invoke the feature of the CardActor.

This document shows all public methods on CardActor and CardPawn that can be used from your behaviors.

Also, properties of CardActor or CardPawn can be read and written in a simple form:

let a = this.foo;

or

this.foo = 42;

Note that multiple behaviors installed to the same CardActor (or CardPawn) share the same property.

Microverse uses the vector types defined in the Worldcore library. Those vectors are actually simple JavaScript Array. In the description below, the representation of Vector3 and Quatanion are:

type Vector3 = [<number>, <number, <number>]

type Quaternion = [<number>, <number, <number>, <number>]

Some rotation related methods take an array with 3 elements as an Euler angle. Internally it converts the Euler angle to a Quaternion. Thus they may take a union of Quaternion or Vector3 as a generic rotation argument.

type Rotation = Quaternion|Vector3

Also, the Card can handle certain kinds of pointer events. The EventName type is defined as:

type EventName = "pointerDown"|"pointerUp"|pointerMove"|"pointerTap"|"pointerLeave"|"pointerEnter"|"wheel"|"doubleDown"|"click"|"keyUp"|"keyDown"

The pointerTap event, only one synthesized event type, is generated when a pointerUp event occurs close in time (< 300ms) and space (< 10 pixels) to the corresponding pointerDown event. Then first the pointerTap event is sent before the pointerUp.

Members

# _translation :Vector3

The [x, y, z] translation of the card.

Type:
  • Vector3

# _rotation :Quaternion

The rotation of the card in quaternion.

Type:
  • Quaternion

# _scale :Vector3

The scale of the card in three axes.

Type:
  • Vector3

# _layers :Array

The layers property specifies how the card is treated when a special action is taken. Typical value are as follows:

  • "walk": The avatar stays on the geometry of the card.
  • "pointer": The pointer action is enabled.
  • "portal": the avatar tests if the card it is going through needs to take the avatar to a connected world.
Type:
  • Array

# _parent :CardActor

The cards in the world are organized in a hierarchical parent-children structure. The _parent specifies its parent. Note that this is a "logical" structure. All cards are held as a direct child of the Three.JS scene, with automatic matrix composition for nested cards.

Type:

# _behaviorModules :Array

The list of behavior modules installed to the card.

Type:
  • Array

# _name :string

An informative string for the card.

Type:
  • string

# _hidden :boolean

The visibility of the card, and whether it responds to pointer events or not.

Type:
  • boolean

# _cardData :Object

Any other values that the CardActor holds are stored in an object stored in the _cardData property. This is needed to mark the values to be stored in the persistent data.

Type:
  • Object

Methods

# createCard(data) → {CardActor}

This method creates a new card (a CardActor on the model side and a CardPawn on the view side), based on the cardSpec.

Parameters:
Name Type Description
data object

the spec for a card to be created.
Returns:

the CardActor created.

Type
CardActor

# destroy()

This method removes the card from the world. All teardown() method of installed pawn behaviors and actor behaviors are called before the CardActor is removed from the system.

# call(behaviorName, methodName) → {any}

This method invokes a method of another behavior. The behaviorName has to be in one of the form of:

  • "ModuleName$BehaviorName"
  • "BehaviorName"

When the first form is used, it specifies the globally known module name and the behavior with the name on the actor side of the module. When the second form is used, it specified the behavior in the same module as the calling behavior. The methodName is the name of the method, and values are variable-length arguments for the method.

Parameters:
Name Type Description
behaviorName string

name of the behavior
methodName string

name of the method
...arguments any

arguments for the method
Returns:

the return value from the method

Type
any

# future(time)

This method schedules a future call in the specified logical time in milliseconds. If it is used in this form:

this.future(20).mth();

mth of the same behavior will be invoked 20 milliseconds from logical now. If you would like to call a method of another module or behavior, you can use call():

this.future(20).call("Module$Behavior", "mth");

Parameters:
Name Type Description
time number

the delay in logical millisecond
Returns:

A proxy to invoke a method on

# setCardData(options)

This method updates some elements in the _cardData object. The current value and the new values are merged to create the new _cardData object. As a side effect, it publishes cardDataSet Croquet event that can be handled by the pawn or any other subscribers.

Parameters:
Name Type Description
options object

keys and values to specify new values

# addEventListener(eventType, listener)

This method adds a "listener" to be invoked when an event occurs on the card. When listener is a function, it has to have a form of this.mthName where mthName is an existing method name of CardActor or the behavior itself. When listener is a string, it has to be the name of a method at CardActor or the behavior itself. The listener added by this Actor-side addEventListener() is invoked when any user in the world causes the corresponding user pointer or key event.

Calling this method with the same arguments removes the previous listener before adding the new one. This semantics ensures that dynamically-modified method will be used.

Parameters:
Name Type Description
eventType EventName

the event type
listener string | function

the name of the handler in the calling behavior, or a function specified in the form of this.mth

# removeEventListener(eventName, listener)

This method removes the event listener that was added. You can call it when there is no matching event listener.

Parameters:
Name Type Description
eventName EventType

the event type
listener string | function

# subscribe(scope, eventName, listener)

This method adds a Croquet event subscription. Unlike the version in the Croquet Library, this version removes the subscription with the same scope and eventName if it exists before adding the new one. This semantics ensures that it is safe to call this from the setup() of a behavior.

Parameters:
Name Type Description
scope string

the scope of Croquet event
eventName string

the event name of Croquet event
listener string | function

the name of the handler in the calling behavior, or a function specified in the form of this.mth

# publish(scope, eventName, data)

This method publishes a Croquet event.

Parameters:
Name Type Description
scope string

the scope of Croquet event
eventName string

the event name of Croquet event
data any

serializable data to be published

# listen(eventName, listener)

This method adds a Croquet event subscription by calling the subscribe() method with this.id as the scope.

Parameters:
Name Type Description
eventName string

the event name of Croquet event
listener string | function

the name of the handler in the calling behavior, or a function specified in the form of this.mth

# say(eventName, data)

This method publishes a Croquet event with this.id as the scope. It is usually used to publish an event whose expect recipient is the corresponding CardPawn.

Parameters:
Name Type Description
eventName string

the event name of Croquet event
data any

serializable data to be published

# addLayer(newLayerName)

This method adds a new element to the layers array. If newLayerName is already in the layers array, the call does not have any effects.

Parameters:
Name Type Description
newLayerName string

the name of a later to be added

# removeLayer(layerName)

This method removes an element from the layers array. If layerName is not in the layers array, the call does not have any effects.

Parameters:
Name Type Description
layerName string

the name of a later to be removed

# translateTo(v)

This method moves the translation of the card to the specified [x, y, z] coordinates.

Parameters:
Name Type Description
v Vector3

the translation for the card

# rotateTo(rot)

When rot is a 4 element array, it is interpreted as a quaternion. When rot is a 3 element array, it is interpreted as an Euler angle. When rot is a number, it is interpreted as [0, rot, 0].

This method sets the rotation of the card to the specified by the argument.

Parameters:
Name Type Description
rot Rotation | number

the rotation for the card

# scaleTo(s)

When s is a number, it is interpreted as [s, s, s]. This method sets the scale of the card to the specified by scale factors in [x, y, z] axis.

Parameters:
Name Type Description
s Vector3 | number

the scale for the card

# positionTo(v, q)

This method sets the translation and rotation of the card, making sure that those two values are used in the same logical time and used for the rendering.

Parameters:
Name Type Description
v Vector3

the translation for the card
q Quaternion

the rotation for the card

# translateBy(v)

This method moves the translation of the card by the specified [x, y, z] vector.

Parameters:
Name Type Description
v Vector3

the translation offset

# rotateBy(rot)

When rot is a 4 element array, it is interpreted as a quaternion. When rot is a 3 element array, it is interpreted as an Euler angle. When rot is a number, it is interpreted as [0, rot, 0].

This method combines the rotation of the card by the specified rotation.

Parameters:
Name Type Description
rot Rotation | number

the additional rotation for the card

# scaleBy(s)

When s is a number, it is interpreted as [s, s, s]. This method multiplies the scale of the card by the specified by scale factors in [x, y, z] axis.

Parameters:
Name Type Description
s Vector3

the scale offset

# forwardBy(v)

When v is a number, it is interpreted as [0, 0, v].

This method translates the object by `the specified offset, in the reference frame of the object.

Parameters:
Name Type Description
v Vector3 | number

the offset

# setAnimationClipIndex(animationClipIndex)

A Three.js keyframe based animation is supported. The animation clip can contain multiple tracks. The index specified here dictates which track to play. A cardData called animationStartTime specifiy the base for time offset.

Parameters:
Name Type Description
animationClipIndex number

the index into animation tracks array

# nop()

This method is empty. It is used to have a way to get the tap to focus keyboard events but you don't need to take any particular action on tap.