CardPawn

CardPawn

CardPawn is the view side implementation of the Card.

The corresponding actor for a CardPawn is accessible by this.actor. You can read a value in _cardData simply by this.actor._cardData.prop. But note that a pawn should never modify the state of the actor.

The most important property of CardPawn is shape, which is a Three.JS Group, and the Micorverse system treats it as the primary visual representation of the card. Customizing the visual appearance of a card means to create a new Three.JS Object3D and add it to shape.

When the Card's type is "2d", and it has some textureType, the texture object is stored in this.texture. If the textureType is "canvas", the DOM canvas is stored in this.canvas` so a pawn behavior can paint into the canvas.

Methods

# call(behaviorName, methodName, …values)

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 Attributes Description
behaviorName string

the name of the behavior that has the metho
methodName string

the name of the method
values any <repeatable>

arguments for the method
Returns:

any

# actorCall(behaviorName, methodName-, …values)

This method invokes a method on the corresponding actor. It is expected that the method to be invoked does not alter the state of the actor, but only reads a property or synthesizes a value from properties. The behaviorName has to be a name of an actor behavior in the same module. actorCall() is used as you cannot invoke an intended method by a simple invocation syntax:

let foo = aPawn.actor.getFoo();

because the behavior that has getFoo() is not specified. If getFoo() is defined by an actor behavior with the name FooActor, you can call it by

let foo = aPawn.actorCall("FooActor", "getFoo");

Make sure that the actor's method called from the pawn does not modify the state of the model in any way.

Parameters:
Name Type Attributes Description
behaviorName string

the name of the behavior that has the method
methodName- string

the name of the method
values any <repeatable>

arguments for the method

# future(time)

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

this.future(20).mth();

mthof the same behavior will be invoked. If you would like to call a method of another module or behavior, you can usecall()`:

Parameters:
Name Type Description
time number

the wall clock time to delay the method invocatino.
Returns:

a proxy to call a method on

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

# addEventListener(eventName, listener)

This method adds a "listener" to be invoked when an event occurs on the pawn of a card. When listener is a string, it has to have the name of an existing method of CardPawn or the behavior itself. (Internally the function object is stored in the event listener data structure.)

Calling this with the same arguments (thus the string form) removes the previous listener and then add the new one. This semantics ensures that dynamically-modified method will be used.

Parameters:
Name Type Description
eventName EventName

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

# removeEventListener(eventName, listener)

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

Parameters:
Name Type Description
eventName EventName

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

# subscribe(scope, eventName, listener)

This method adds 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 a new one; so that it is safe to call this from the setup() of a behavior. The listener can be either a function or a string in the form of:

  • "ModuleName$BehaviorName.methodName"
  • "BehaviorName.methodName"
  • "methodName"
Parameters:
Name Type Description
scope string

the scope name 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 eventName of Croquet event
data anyf

serializable data to be published

# listen(eventName, listener)

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

Parameters:
Name Type Description
eventName string

the eventName 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.actor.id as its scope.

Parameters:
Name Type Description
eventName string

the eventName of Croquet event
data any

serializable data to be published

# getMyAvatar() → {AvatarPawn}

This method returns the AvatarPawn of the local client. Recall that the notion of "my" avatar only exists on the view side. The model side treats all avatars equally, even the one that is associated with the local computer. This is why this method is on the pawn side, and returns the AvatarPawn.

Returns:

The local AvatarPawn

Type
AvatarPawn

# addUpdateRequest(array)

A pawn behavior may request a method callback when CardPawn's update() method is invoked. behaviorName and methodName will be "registered in the pawn, and for each update() call, the behavior method is invoked. the argument is an array of the behavior name and the method to be called: type BehaviorMethod = Array<behaviorName, methodName>.

Parameters:
Name Type Description
array BehaviorMethod

a two element array with behavior name and method name

# roundedCornerGeometry(width, height, depth, cornerRadius) → {Geometry}

This method creates a flat card like Three.JS geometry in specified in width, height, depth, and cornerRadius.

Parameters:
Name Type Description
width number

width of the geometry (in meters)
height number

height of the geometry (in meters)
depth number

depth of the geometry (in meters)
cornerRadius number

radius of the corners of the geometry (in meters)
Returns:

THREE.Geometry created

Type
Geometry

# makePlaneMaterial(depth, color, frameColor, fullBright) → {PlaneMaterial}

type PlaneMaterial = Material|Array<Material>

This method creates a Three.JS material that can be used with the geometry created by roundedCornerGeometry(). When the depth is non-zero, thus it is expected that the geometry from roundedCornerGeometry() has "sides", this method returns an array of materials with color and frameColor. Otherwise, it return a material with color.

Parameters:
Name Type Description
depth number

depth of the geometry (in meters)
color number

the surface color for the material
frameColor number

the frame color for the material if depth is non-zero
fullBright boolean

if the material should ignore shaadows.
Returns:
Type
PlaneMaterial

# translateTo(v)

This method publishes an event to set the corresponding actor's translation.

Parameters:
Name Type Description
v Vector3

the translation to be used by corresponding actor

# rotateTo(q)

This method publishes an event to set the corresponding actors's rotation.

Parameters:
Name Type Description
q Quaternion

the rotation to be ued by corresponding actor

# scaleTo(s)

This method publishes an event to set the corresponding actors's rotation.

Parameters:
Name Type Description
s Vector3

the scale to be used by the corresponding actor

# positionTo(v, q)

This method publishes an event to set the corresponding actors's translation and rotation. It guarantees that two values are sent in one message, thus causes both to be updated at the same time.

Parameters:
Name Type Description
v Vector3

the translation to be used by corresponding actor
q Quaternion

the rotation to be ued by corresponding actor

# constructCollider(obj)

In order for the avatar to walk on a three-dimensional model, the 3D model needs to have the bounded volume hierarchy structure attached. This method has to be called to make a 3D object that is created in the pawn-side behavior.

Parameters:
Name Type Description
obj Object3D

# cleanupColliderObject()

If the card has an associated collider object, it will be removed. If there is no collider object, this method does not take any effects. A typical use case of constructCollider() and cleanupColliderObject() in a pawn-side behavior is as follows in its setup() method:

Example 
this.cleanupColliderObject()
if (this.actor.layers && this.actor.layers.includes("walk")) {
    this.constructCollider(this.floor);
    // where this.floor is a Three.js Mesh with geometry.
 }

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