Options
All
  • Public
  • Public/Protected
  • All
Menu

The fluent Action API allows you to perform "actions" on Actors such as following, moving, rotating, and more. You can implement your own actions by implementing the IAction interface.

Actions can be chained together and can be set to repeat, or can be interrupted to change.

Actor actions are available off of Actor.actions.

Chaining Actions

You can chain actions to create a script because the action methods return the context, allowing you to build a queue of actions that get executed as part of an ActionQueue.

class Enemy extends ex.Actor {
  public patrol() {
    // clear existing queue
    this.actions.clearActions();
    // guard a choke point
    // move to 100, 100 and take 1.2s
    // wait for 3s
    // move back to 0, 100 and take 1.2s
    // wait for 3s
    // repeat
    this.actions
      .moveTo(100, 100, 1200)
      .delay(3000)
      .moveTo(0, 100, 1200)
      .delay(3000)
      .repeatForever();
  }
}

Example: Follow a Path

You can use Actor.actions.moveTo to move to a specific point, allowing you to chain together actions to form a path.

This example has a Ship follow a path that it guards by spawning at the start point, moving to the end, then reversing itself and repeating that forever.

public Ship extends ex.Actor {
  public onInitialize() {
    var path = [
      new ex.Vector(20, 20),
      new ex.Vector(50, 40),
      new ex.Vector(25, 30),
      new ex.Vector(75, 80)
    ];
    // spawn at start point
    this.x = path[0].x;
    this.y = path[0].y;
    // create action queue
    // forward path (skip first spawn point)
    for (var i = 1; i < path.length; i++) {
      this.actions.moveTo(path[i].x, path[i].y, 300);
    }

    // reverse path (skip last point)
    for (var j = path.length - 2; j >= 0; j--) {
      this.actions.moveTo(path[j].x, path[j].y, 300);
    }
    // repeat
    this.actions.repeatForever();
  }
}

While this is a trivial example, the Action API allows complex routines to be programmed for Actors. For example, using the Tiled Map Editor you can create a map that uses polylines to create paths, load in the JSON using a Generic Resource, create a TileMap, and spawn ships programmatically while utilizing the polylines to automatically generate the actions needed to do pathing.

Custom Actions

The API does allow you to implement new actions by implementing the IAction interface, but this will be improved in future versions as right now it is meant for the Excalibur team and can be advanced to implement.

You can manually manipulate an Actor's ActionQueue using Actor.actionQueue. For example, using ActionQueue.add for custom actions.

Future Plans

The Excalibur team is working on extending and rebuilding the Action API in future versions to support multiple timelines/scripts, better eventing, and a more robust API to allow for complex and customized actions.

Hierarchy

  • ActionContext

Index

Constructors

constructor

Methods

addActorToContext

  • addActorToContext(actor: Actor): void

asPromise

blink

  • blink(timeVisible: number, timeNotVisible: number, numBlinks?: number): ActionContext
  • This method will cause an actor to blink (become visible and not visible). Optionally, you may specify the number of blinks. Specify the amount of time the actor should be visible per blink, and the amount of time not visible. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • timeVisible: number

      The amount of time to stay visible per blink in milliseconds

    • timeNotVisible: number

      The amount of time to stay not visible per blink in milliseconds

    • Default value numBlinks: number = 1

      The number of times to blink

    Returns ActionContext

callMethod

  • This method allows you to call an arbitrary method as the next action in the action queue. This is useful if you want to execute code in after a specific action, i.e An actor arrives at a destination after traversing a path

    Parameters

    • method: function
        • (): any
        • Returns any

    Returns ActionContext

clearActions

  • clearActions(): void

delay

  • This method will delay the next action from executing for a certain amount of time (in milliseconds). This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • time: number

      The amount of time to delay the next action in the queue from executing in milliseconds

    Returns ActionContext

die

  • This method will add an action to the queue that will remove the actor from the scene once it has completed its previous actions. Any actions on the action queue after this action will not be executed.

    Returns ActionContext

easeTo

  • easeTo(x: number, y: number, duration: number, easingFcn?: EasingFunction): this
  • This method will move an actor to the specified x and y position over the specified duration using a given EasingFunctions and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • x: number

      The x location to move the actor to

    • y: number

      The y location to move the actor to

    • duration: number

      The time it should take the actor to move to the new location in milliseconds

    • Default value easingFcn: EasingFunction = EasingFunctions.Linear

      Use EasingFunctions or a custom function to use to calculate position

    Returns this

fade

  • This method will cause an actor's opacity to change from its current value to the provided value by a specified time (in milliseconds). This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • opacity: number

      The ending opacity

    • time: number

      The time it should take to fade the actor (in milliseconds)

    Returns ActionContext

follow

  • This method will cause the actor to follow another at a specified distance

    Parameters

    • actor: Actor

      The actor to follow

    • Optional followDistance: number

      The distance to maintain when following, if not specified the actor will follow at the current distance.

    Returns ActionContext

meet

  • This method will cause the actor to move towards another until they collide "meet" at a specified speed.

    Parameters

    • actor: Actor

      The actor to meet

    • Optional speed: number

      The speed in pixels per second to move, if not specified it will match the speed of the other actor

    Returns ActionContext

moveBy

  • This method will move an actor to the specified x and y position by a certain time (in milliseconds). This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • x: number

      The x location to move the actor to

    • y: number

      The y location to move the actor to

    • time: number

      The time it should take the actor to move to the new location in milliseconds

    Returns ActionContext

moveTo

  • This method will move an actor to the specified x and y position at the speed specified (in pixels per second) and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • x: number

      The x location to move the actor to

    • y: number

      The y location to move the actor to

    • speed: number

      The speed in pixels per second to move

    Returns ActionContext

removeActorFromContext

  • removeActorFromContext(actor: Actor): void

repeat

  • This method will cause the actor to repeat all of the previously called actions a certain number of times. If the number of repeats is not specified it will repeat forever. This method is part of the actor 'Action' fluent API allowing action chaining

    Parameters

    • Optional times: number

      The number of times to repeat all the previous actions in the action queue. If nothing is specified the actions will repeat forever

    Returns ActionContext

repeatForever

  • This method will cause the actor to repeat all of the previously called actions forever. This method is part of the actor 'Action' fluent API allowing action chaining.

    Returns ActionContext

rotateBy

  • This method will rotate an actor to the specified angle by a certain time (in milliseconds) and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • angleRadians: number

      The angle to rotate to in radians

    • time: number

      The time it should take the actor to complete the rotation in milliseconds

    • Optional rotationType: RotationType

      The RotationType to use for this rotation

    Returns ActionContext

rotateTo

  • This method will rotate an actor to the specified angle at the speed specified (in radians per second) and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • angleRadians: number

      The angle to rotate to in radians

    • speed: number

      The angular velocity of the rotation specified in radians per second

    • Optional rotationType: RotationType

      The RotationType to use for this rotation

    Returns ActionContext

scaleBy

  • scaleBy(sizeX: number, sizeY: number, time: number): ActionContext
  • This method will scale an actor to the specified size by a certain time (in milliseconds) and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • sizeX: number

      The scaling factor to apply on X axis

    • sizeY: number

      The scaling factor to apply on Y axis

    • time: number

      The time it should take to complete the scaling in milliseconds

    Returns ActionContext

scaleTo

  • scaleTo(sizeX: number, sizeY: number, speedX: number, speedY: number): ActionContext
  • This method will scale an actor to the specified size at the speed specified (in magnitude increase per second) and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.

    Parameters

    • sizeX: number

      The scaling factor to apply on X axis

    • sizeY: number

      The scaling factor to apply on Y axis

    • speedX: number

      The speed of scaling specified in magnitude increase per second on X axis

    • speedY: number

      The speed of scaling specified in magnitude increase per second on Y axis

    Returns ActionContext