Returns a promise that resolves when the current action queue up to now is finished.
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.
The amount of time to stay visible per blink in milliseconds
The amount of time to stay not visible per blink in milliseconds
The number of times to blink
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
Clears all queued actions from the Actor
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.
The amount of time to delay the next action in the queue from executing in milliseconds
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.
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.
The x location to move the actor to
The y location to move the actor to
The time it should take the actor to move to the new location in milliseconds
Use EasingFunctions or a custom function to use to calculate position
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.
The ending opacity
The time it should take to fade the actor (in milliseconds)
This method will cause the actor to follow another at a specified distance
The actor to follow
The distance to maintain when following, if not specified the actor will follow at the current distance.
This method will cause the actor to move towards another until they collide "meet" at a specified speed.
The actor to meet
The speed in pixels per second to move, if not specified it will match the speed of the other actor
This method will move an actor by the specified x offset and y offset from its current position, at a certain speed. This method is part of the actor 'Action' fluent API allowing action chaining.
The x offset to apply to this actor
The y location to move the actor to
The speed in pixels per second the actor should move
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.
The x location to move the actor to
The y location to move the actor to
The speed in pixels per second to move
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
The number of times to repeat all the previous actions in the action queue. If nothing is specified the actions will repeat forever
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.
This method will rotate an actor by the specified angle offset, from it's current rotation given a certain speed in radians/sec and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.
The angle to rotate to in radians relative to the current rotation
The speed in radians/sec the actor should rotate at
The RotationType to use for this rotation, default is shortest path
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.
The angle to rotate to in radians
The angular velocity of the rotation specified in radians per second
The RotationType to use for this rotation
This method will scale an actor by an amount relative to the current scale at a certain speed in scale units/sec and return back the actor. This method is part of the actor 'Action' fluent API allowing action chaining.
The scaling factor to apply on X axis
The scaling factor to apply on Y axis
The speed to scale at in scale units/sec
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.
The scaling factor to apply on X axis
The scaling factor to apply on Y axis
The speed of scaling specified in magnitude increase per second on X axis
The speed of scaling specified in magnitude increase per second on Y axis
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 Action 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
Shipfollow 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() { const 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 (let i = 1; i < path.length; i++) { this.actions.moveTo(path[i].x, path[i].y, 300); } // reverse path (skip last point) for (let i = path.length - 2; i >= 0; i--) { this.actions.moveTo(path[i].x, path[i].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 Action 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.