class flaxen.component.ActionQueue implements Completable
Available on all platforms
In an entity-component-system, systems represent the behavior. Systems examine the state of the game via the entities and their components, and react to it, by adding/removing entities and modifying components. This in turn can trigger another reaction, which triggers another. While systems can be used for complicated chain of actions and reactions, sometimes it can make the design needlessly complicated.
An alternative way to encode a series of actions is through an action queue. ActionQueue is a chain of steps that modifies the game state in sequence. Consider a dead enemy that you want to fade to white over two seconds, leaving a puff of smoke and eliminating the corpse. You overlay the corpse with an all white corpseFx entity and give it an Alpha of 0 (transparent). You fade in corpseFX, remove the original corpse, invoke a particle effect, wait for that effect to complete, and then clean up by removing the corpseFX entity.
f.newActionQueue()
.waitForWrap(new Tween(2.0)
.addTarget(corpseFX.get(Alpha), "value", 1.0)
.onComplete(DestroyEntity));
.removeEntity(corpse)
.addComponent(corpseFX, smokeEmitter)
.waitForComplete(smokeEmitter)
.removeEntity(corpseFX);This could be done with systems instead, and in many cases it should. Systems require more boilerplate and time to implement, so for one-off effects often an ActionQueue is preferable.
For an action queue to be processed, you must use ActionSystem, the ActionQueue instance must be added to an entity, the entity must be added to Ash, and either autoStart must be true on creation, or running set to true after creation.
- NOTE: ActionQueues cannot be shared between entities.
-
CONSIDER: Could the AQ retain a copy of the last entity/component/object it worked on, and then recall that entity with a special construct?
Instance Fields
var name:String
The name is primarily intended for the holding entity's name, which can be
helpful in some cases; Flaxen.newActionQueue sets this automatically;
can be null if not defined
var running:Bool
The action queue is only being processed when running is true; you can set this false to pause the processing; you can pass false for autoStart to delay execution
function new(?f:Flaxen, ?onComplete:OnComplete, ?autoStart:Bool = true, ?name:String):Void
Creates a new ActionQueue.
| flaxen | The Flaxen object |
| onComplete | What to do after the queue completes |
| autoStart | If true (default) runs the queue automatically; if false, you may run the queue manually by setting |
| name | The name of the ActionQueue; see |
function add(action:Action, ?priority:Bool = false):ActionQueue
Adds an action to the queue.
The priority flag is intended to allow a callback action to modify the queue while its still being processed. To do this, pass true for priority as the last parameter. Priority actions are kept in a secondary queue, and will be added to front of the main queue when the callback completes.
| action | An action (command) object to add to the queue |
| priority | Set true if this is a priority action |
| returns | This ActionQueue object |
function addComponent(entityRef:EntityRef, component:Dynamic, ?priority:Bool = false):ActionQueue
Adds a component to an existing entity
| entityRef | The existing entity to receive the component |
| component | The component to be added |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function addEntity(entityRef:EntityRef, ?priority:Bool = false):ActionQueue
Adds an entity to Ash that hasn't been added yet.
See newEntity(..., false) in Flaxen or new Entity() in Ash.
| entityRef | An entity to be added |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function addSet(entityRef:EntityRef, setName:String, ?priority:Bool = false):ActionQueue
Adds a component set to an entity.
Applies all the batch operations stored in the component set to the supplied entity.
See ComponentSet.
| entityRef | The existing entity to which the |
| setName | The name of the |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function call(func:Void ->Void, ?priority:Bool = false):ActionQueue
Calls a function that accepts no parameters and returns nothing.
| func | An anonymous function in the form of Void->Void |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function execute():Bool
Executes the next action(s) and returns true if the action queue is empty When actions are completed, they are removed from the queue and the next action is executed. An action can hold up the queue by returning false for its execute method, in which case it will be called again later. See ActionSystem.
| returns | True if the all actions have been processed; if false, call execute again to process actions further. |
function log(message:String, ?priority:Bool = false):ActionQueue
Logs a message to the console.
| message | The string to log |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function pause():ActionQueue
Pauses the action queue.
Call resume to continue.
| returns | This action queue instance |
function removeComponent(entityRef:EntityRef, component:Class<Dynamic>, ?priority:Bool = false):ActionQueue
Removes a component from an entity.
| entityRef | The entity with the component |
| component | The component to be removed |
| priority | Set true if this is a priority action; see |
| returns | This ActionQueue object |
function removeEntity(entityRef:EntityRef, ?priority:Bool = false):ActionQueue
Removes an entity from Ash.
| entityRef | An entity object to be removed, or the string name of such an entity |
| priority | Set true if this is a priority action (see |
function setName(name:String):ActionQueue
Sets the name of this action queue.
The name is primarily intended for the holding entity's name, which can be
used to look up the entity in Ash. See name for more.
| name | The name of the action queue |
| returns | This ActionQueue object |
function setOnComplete(onComplete:OnComplete):ActionQueue
Immediately sets onComplete.
| OnComplete | What to do after the action queue completes |
| returns | This ActionQueue object |
function setProperty(object:Dynamic, property:String, value:Dynamic, ?priority:Bool = false):ActionQueue
Sets the property of an object to a value. As in, object.property = value;.
| object | An object with a matching property |
| property | A string representing the name of the property |
| value | The value to set the property to |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function wait(seconds:Float, ?priority:Bool = false):ActionQueue
Delays an amount of time before continuing the action queue.
| seconds | The number seconds to wait |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function waitForCall(func:Void ->Bool, ?priority:Bool = false):ActionQueue
Calls a function repeatedly, that accepts no parameters and returns a boolean value, until that function returns true. This works sort of like a thread.
| func | An anonymous function in the form of Void->Bool |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function waitForProperty(object:Dynamic, property:String, value:Dynamic, ?priority:Bool = false):ActionQueue
Waits for the value of an object's property to reach a certain value.
| object | An object with a matching property |
| property | A string representing the name of the property |
| value | The value to wait for |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function waitForWrap(completable:Completable, ?name:String = null, ?priority:Bool = false):ActionQueue
Wraps a Completable component into a new entity.
Creates a new entity with an unique name, adds it to Ash, and adds the component to the entity.
Waits until the component's complete property to become true.
This is useful for adding new Tweens and Sounds, for instance, or perhaps a nested ActionQueue.
| component | A Completable component to wrap into a new entity and wait for |
| name | An optional name or pattern the the wrapping entity; see |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |
function waitOnce(?priority:Bool = false):ActionQueue
During testing I've found at times to have an action that waits one frame before resuming. This achieves that.
| returns | This ActionQueue object |
function wrap(component:Dynamic, ?name:String = null, ?priority:Bool = false):ActionQueue
Wraps a component into a new entity. Creates a new entity with an unique name, adds it to ash, and adds the component to the entity.
| component | The component to "wrap" into a new entity |
| name | An optional name or pattern the the wrapping entity; see |
| priority | Set true if this is a priority action (see |
| returns | This ActionQueue object |