Bukkit

Actions - overview

The actions provided by this API are showing a very easy way to make the entity do what you want it to do.

Any action you add personally will override any action added by the AI of the entity. Executing multiple actions at the same time is possible, but you most likely don't want to do this - it could result in unexpected behavior.

The action queue

You maybe don't want that the entity executes multiple actions at the same time, but execute them one after another. To easily realize this, the API provides a built-in action queue. Any action can be executed directly or added to the action queue.

When all running actions have been finished, the next element of the action queue is fetched and starts its execution. The queue works corresponding to FIFO-concept (first in, first out) - the first action you added, will also be the first one to execute, no matter how many other actions are following. If the first action of the queue has finished aswell, it continues with the second action, and so on. If you add an action to the queue when no actions are currently running, it is being executed directly instead.

You can add callbacks to the action queue to receive an event after some actions of the queue have been executed. Have a look at the callback-method in the section below.

Managing actions

Adding an action

Call methods provided by an instance of ControllableMobActions to plan or execute actions. You can retrieve this instance by calling controlledEntity.getActions(). Every method lets you specify a parameter called "queue" - if set to true, the action will not be executed immediately, but added to the action queue. Here is a list of basic methods:

These methods will return an instance of ControllableMobAction. I will reference to it as action. You can use this instance to:

• get the actions state ( action.getState(), returns an ActionState)
• cancel the action (see below)

Removing an action

You have two options to remove an added action:

• call action.cancel() - removes the action from the queue or stops it if it is already running
• call the same method you used to start the action again with the argument null. For example: controlledEntity.getActions().moveTo(null) - This will stop any currently running action of this type, however, the queue is not affected. Whenever you remove an action its state is set to CANCELLED.

Quote:

Hint: calling

controlledEntity.getActions().target(null);

will also remove targets which were auto-assigned by the AI!

Clearing actions

If you want to interrupt the entity (whatever it is currently doing), you may call

controlledEntity.getActions().clearActions();

This will stop and remove all actions, those running and those in the queue aswell.

If you just want to remove all actions from the queue, call

controlledEntity.getActions().clearActionQueue();

If you just want to stop and remove all currently running actions and continue those in the queue, call

controlledEntity.getActions().clearActionsRunning();

Retrieving actions

If you want to know whether an action of a specific ActionType is currently running, you can call

controlledEntity.getActions().isActionRunning(type);