API Documentation for: 0.11.8
Show:

platypus.components.Orientation Class

This component handles the orientation of an entity. It maintains an orientationMatrix property on the owner to describe the entity's orientation using an affine transformation matrix.

Several methods on this component accept either a 3x3 2D Array or a string to describe orientation changes. Accepted strings include:

  • "horizontal" - This flips the entity around the y-axis.
  • "vertical" - This flips the entity around the x-axis.
  • "diagonal" - This flips the entity around the x=y axis.
  • "diagonal-inverse" - This flips the entity around the x=-y axis.
  • "rotate-90" - This rotates the entity 90 degrees clockwise.
  • "rotate-180" - This rotates the entity 180 degrees clockwise (noticeable when tweening).
  • "rotate-270" - This rotates the entity 90 degrees counter-clockwise.

NOTE: This component absorbs specific properties already on the entity into orientation:

  • orientationMatrix: 3x3 2D array describing an affine transformation.
  • If the above is not provided, these properties are used to set initial orientation. This is useful when importing Tiled maps.
    • scaleX: absorb -1 if described
    • scaleY: absorb -1 if described
    • rotation: absorb 90 degree rotations

Methods

'append-transform'

(
  • transform
)

This message performs an immediate transform of the entity by performing the transformation via an appended matrix multiplication.

Parameters:

  • transform Array | String

    A 3x3 @D Array or a string describing a transformation.

'complete-tweens'

()

Defined in 'complete-tweens':314

Available since 0.7.1

On receiving this message, any currently running orientation tweens are immediately completed to give the entity a new stable position.

'drop-tweens'

()

Defined in 'drop-tweens':328

On receiving this message, any currently running orientation tweens are discarded, returning the entity to its last stable position.

'handle-logic'

(
  • tick.delta
)

Defined in 'handle-logic':261

On the 'handle-logic' event, this component updates any transformational tweening of the entity.

Parameters:

  • tick.delta Number

    Time passed since the last logic step.

'load'

()

Defined in 'load':228

This component listens for this event prior to loading initial transformations.

'orient-vector'

(
  • vector
)

Defined in 'orient-vector':350

On receiving a vector via this event, the component will transform the vector using the current orientation matrix and then store the vector and continue manipulating it as the orientation matrix changes.

Parameters:

'prepend-transform'

(
  • transform
)

This message performs an immediate transform of the entity by performing the transformation via a prepended matrix multiplication.

Parameters:

  • transform Array | String

    A 3x3 @D Array or a string describing a transformation.

'remove-vector'

(
  • vector
)

Defined in 'remove-vector':372

On receiving this message, the maintained vector is immediately dropped from the list of maintained vectors.

Parameters:

'replace-transform'

(
  • transform
)

This message performs an immediate transform of the entity by returning the entity to an identity transform before performing a matrix multiplication.

Parameters:

  • transform Array | String

    A 3x3 @D Array or a string describing a transformation.

'transform'

(
  • transform
)

Defined in 'transform':467

This message performs an immediate transform of the entity by performing the transformation via a prepended matrix multiplication.

Parameters:

  • transform Array | String

    A 3x3 @D Array or a string describing a transformation.

'tween-transform'

(
  • options
)

This message causes the component to begin tweening the entity's orientation over a span of time into the new orientation.

Parameters:

  • options Object

    A list of key/value pairs describing the tween options.

    • matrix Array

      A transformation matrix: only required if transform is not provided

    • transform String

      A transformation type: only required if matrix is not provided.

    • time Number

      The time over which the tween occurs. 0 makes it instantaneous.

    • [anchor] platypus.Vector optional

      The anchor of the orientation change. If not provided, the owner's position is used.

    • [offset] platypus.Vector optional

      If an anchor is supplied, this vector describes the entity's distance from the anchor. It defaults to the entity's current position relative to the anchor position.

    • [angle] Number optional

      Angle in radians to transform. This is only valid for rotations and is derived from the transform if not provided.

    • [tween] Function optional

      A function describing the transition. Performs a linear transition by default. See CreateJS Ease for other options.

    • [beforeTick] Function optional

      A function that should be processed before each tick as the tween occurs. This function should return true, otherwise the tween doesn't take a step.

    • [afterTick] Function optional

      A function that should be processed after each tick as the tween occurs.

    • [onTick] Function optional

      Deprecated in favor of beforeTick and afterTick.

    • [onFinished] Function optional

      A function that should be run once the transition is complete.

addEventListener

(
  • event
  • callback
)
Function private
This method adds an event listener to the entity.

Parameters:

  • event String
    The event that this component should listen for.
  • callback Function
    The handler for the event.

Returns:

Function: handler A reference to the bound handler.

addMethod

(
  • name
  • func
)
private
This method adds a method to the entity.

Parameters:

  • name String
    The name of the method. For example, if name is "turnYellow", the method is accessible on the entity as entity.turnYellow().
  • func Function
    The function describing the method.

destroy

() private

Inherited from platypus.Component: destroy:54

This method cleans up listeners and methods that this component added to the entity. It should never be called by the component itself. Call this.owner.removeComponent(this) instead.

getAssetList

(
  • definition
  • properties
  • defaultProperties
)
Array
This method can be overwritten to provide the list of assets this component requires. This method is invoked when the list of game scenes is created to determine assets for each scene.

Parameters:

  • definition Object
    The definition for the component.
  • properties Object
    The properties of the Entity.
  • defaultProperties Object
    The default properties of the Entity.

Returns:

Array: A list of the necessary assets to load.

getLateAssetList

(
  • data
)
Array
This method can be overwritten to provide the list of assets this component requires. This method is invoked when the list of game scenes is created to determine assets for each scene.

Parameters:

  • data Object
    Scene data that affects the list of assets.

Returns:

Array: A list of the necessary assets to load.

removeEventListener

(
  • event
  • callback
)
private
This method removes an event listener from the entity.

Parameters:

  • event String
    The event for which to remove a listener.
  • callback Function
    The listener to remove. If not supplied, all event listeners for the provided event are removed.

removeEventListeners

(
  • [listeners]
)
private
This method removes multiple event listeners from the entity.

Parameters:

  • [listeners] Array optional
    The list of listeners to remove. If not supplied, all event listeners are removed.

removeMethod

(
  • name
)
private
This method removes a method from the entity.

Parameters:

  • name String
    The name of the method to be removed.

toJSON

() Object

Inherited from platypus.Component: toJSON:45

Available since 0.11.0

Returns a JSON object describing the component.

Returns:

Object: Returns a JSON definition that can be used to recreate the component.

toString

() String
Returns a string describing the component.

Returns:

String: Returns the component type as a string of the form "[Component ComponentType]".

Properties

orientation

Number

Defined in orientation:137

The Entity's orientation is an angle in radians describing an entity's orientation around the Z-axis. This property is affected by a changing entity.orientationMatrix but does not itself change the orientation matrix.

Default: 0

orientationMatrix

Array

The entity's orientation matrix determines the orientation of an entity and its vectors. It's a 3x3 2D Array describing an affine transformation of the entity.

Default: 3x3 identity matrix

rotation

Number

Defined in rotation:128

The Entity's rotation will rotate entity's initial orientation if it is a multiple of 90 degrees. This value is available via entity.rotation, but is not manipulated by this component after instantiation.

Default: 0

scaleX

Number

Defined in scaleX:110

The Entity's scale along the X-axis will mirror the entity's initial orientation if it is negative. This value is available via entity.scaleX, but is not manipulated by this component after instantiation.

Default: 1

scaleY

Number

Defined in scaleY:119

The Entity's scale along the Y-axis will flip the entity's initial orientation if it is negative. This value is available via entity.scaleY, but is not manipulated by this component after instantiation.

Default: 1

Events

'orientation-updated'

Once a transform is complete, this event is triggered to notify the entity of the completed transformation.

Event Payload:

  • matrix Array

    A 3x3 2D array describing the change in orientation.