The Action Queue

By default, all actions get added to the ActionQueue. The queue is shared between all scripts to prevent them from fighting over running actions at the same time. The queue self manages action priorities by default, to allow automatic prioritizing of actions like healing. You can override priorities for specific actions as needed, see Action priorities further down in this page.

[!TIP] It is possible to bypass this queue but in general it is not recommended. If you are looking to bypass, check out the advanced action queue usage docs.

A benefit of using the action queue is that all actions can detect temporary failures / timeouts, and retry themselves. See Action options for customizing this behavior per action.

Adding actions to the queue

There are a few ways to add actions to the queue. The easiest is using the Game.Actions interface. It gives access to all supported client actions in a single place. As an example, lets use it to create a fellowship.

Open the HelloWorld script from Creating your first script and change the contents to the following:

game.actions.fellowCreate("My Fellowship")

The FellowCreate action creates a new fellowship with the specified name if you aren't already in one. Now when you run the HelloWorld script, it should immediately create a fellowship called My Fellowship. Note that this will only work if you aren't already in a fellowship. We'll go over checking the results of an action in the next section.

An alternative to using the Game.Actions interface is to create the action and manually add it to the queue. We can accomplish the same as above with the following:

local myCreateFellowAction = FellowCreateAction.new("My Fellowship")
game.actionQueue.add(myCreateFellowAction)

This does the exact same thing as our first script, we just created the FellowCreateAction and added it to the queue manually with ActionQueue.Add. This method of creating actions will be useful later, when we are grouping actions.

Action options

When calling or creating an action, you are able to pass it a set of options to change its default behavior. For example you can give it a custom priority, change its default timeout, or change the max retry count. Lets create the same action as above, but this time we'll give it a custom priority and change the maximum number of retries.

local options = ActionOptions.new()
options.priority = 50000
options.maxRetryCount = 1
game.actions.fellowCreate("My Fellowship", true, options)

This time when we callFellowCreate, we pass the second argument that sets shareExperience, and a third argument with custom options. The custom options uses a max retry count of 1, and sets the priority to 50000 (see Action priorities for more information about how priorities work).

You can also pass custom options when creating an action manually:

local options = ActionOptions.new()
options.timeoutMilliseconds= 5000
local myCreateFellowAction = FellowCreateAction.new("My Fellowship", true, options)
game.actionQueue.add(myCreateFellowAction)

The above creates a new FellowCreateAction with the specified ActionOptions and adds it to the queue manually with ActionQueue.Add.

Checking the results of an action

Of course when you perform an action, you probably want to be notified of if it completed, and when. You can do that by using callbacks or promises. Lets see how callbacks work first. Replace the contents of your script with the following:

local fellowCreateCallback = function(action)
  if action.Success then
    print("Successfully created a fellowship called:", action.FellowshipName)
  else
    print("Unable to create a fellowship!", action.Error, ":", action.ErrorDetails)
  end
end

game.Actions.FellowCreate("My Fellowship", true, nil, fellowCreateCallback)

In the above, we defined a callback called fellowCreateCallback that gets called when our action completes. Callbacks get passed the action that generated them, so in our case the action parameter in our fellowCreateCallback handler is a FellowCreateAction. We can check the QueueAction.Success property and print the results or error accordingly. We are able to see what error occurred by checking QueueAction.Error.

[!TIP] Some errors will provide more details in QueueAction.ErrorDetails. Be sure to check out the api docs for UBScript.Actions to see what properties are available on each action.

Try running the script twice. The first time (assuming you aren't in a fellowship), it should print a success message. The second time you run the script it should fail because you are already in a fellowship.

Grouping actions

There is a special action called RunAllOrderedAction that allows running a grouped set of actions in the specified order. This action groups up its child actions and makes sure to run them in the order passed, regardless of priority. Here's an example grouped action that creates a fellowship and then sets the fellowship open status to false:

local myActions = {
  FellowCreateAction.new("My Fellowship"),
  FellowSetOpenAction.new(false)
}
game.actions.runAllOrdered(myActions)

This is handy for making sure that the passed set of actions maintains a custom order without messing with priorities, as well as preventing other actions from interrupting this action group. Grouped actions are treated like a singular action, so once it starts running it will only complete once all child actions have completed.

Action priorities

By default, actions are performed based on their ActionType. These are the default priorities for each type:

        /// <summary>
        /// Wielding an item. This is highest default priority because we want to switch to the correct
        /// weapon before switching combat modes / casting spells / etc.
        /// </summary>
        Wield = 20000,

        /// <summary>
        /// Restoring health (spells / kits / pots)
        /// </summary>
        RestoreHealth = 19000,

        /// <summary>
        /// Restoring stamina (spells / kits / pots)
        /// </summary>
        RestoreStamina = 18000,

        /// <summary>
        /// Restoring mana (spells / kits / pots)
        /// </summary>
        RestoreMana = 17000,

        /// <summary>
        /// Logging in / out
        /// </summary>
        LoginLogoff = 16000,

        /// <summary>
        /// Trading with other players
        /// </summary>
        Trade = 15000,

        /// <summary>
        /// Combat
        /// </summary>
        Combat = 14000,

        /// <summary>
        /// Casting spells
        /// </summary>
        CastSpell = 13000,

        /// <summary>
        /// Navigating
        /// </summary>
        Navigation = 12000,

        /// <summary>
        /// Managing fellowships
        /// </summary>
        Fellow = 11000,

        /// <summary>
        /// Allegiance actions
        /// </summary>
        Allegiance = 10000,

        /// <summary>
        /// Inventory management
        /// </summary>
        Inventory = 9000,

        /// <summary>
        /// Misc...
        /// </summary>
        Misc = 8000,

Inspecting the queue

You can inspect the current queue by looking at ActionQueue.Queue or for immediate actions, ActionQueue.ImmediateQueue. For example, here's how you would loop through and print out each action current in the queue:

for action in game.ActionQueue.Queue do
  print(action)
end

Removing actions from the queue

You can remove an action from the queue manually with ActionQueue.Remove. For example:

-- create a new action
local myCreateFellowAction = FellowCreateAction.new("My Fellowship")

-- add the action to the queue
game.ActionQueue.add(myCreateFellowAction)

-- remove the action from the queue
game.ActionQueue.remove(myCreateFellowAction)