TimedActionUtils

local TimedActionUtils = require("Starlit/timedActions/TimedActionUtils")

The TimedActionUtils module provides utilities for creating and working with timed actions. Currently it focuses primarily on handling prerequisite timed actions (e.g. equip item used in next timed action).

Note

This module is for working with Vanilla timed actions. It is intended to mostly be replaced by the Action framework in v42-1.5.0.

Functions

TimedActionUtils.transfer(character: IsoGameCharacter, item: InventoryItem)

Queues an action to transfer an item to the characters’s inventory. Does nothing if the item is already in the character’s inventory.

Parameters:

character (IsoGameCharacter) – The character.
item (InventoryItem) – The item to transfer.

TimedActionUtils.transferFirstValid(character: IsoGameCharacter, type: string | nil, predicate: umbrella.ItemContainer_Predicate | nil, predicateArg: any)

Queues an action to transfer the first item matching the criteria from the characters’s containers into their main inventory. This differs from regular transfer as the item is picked at the start of the action. This prevents issues where multiple queued actions target the same item, causing later actions to fail even though there are still valid items in the player’s inventory.

Parameters:

IsoGameCharacter (character) – The character.
type (string | nil) – The item type to transfer. If nil does not check item type.
predicate (umbrella.ItemContainer_Predicate | nil) – Optional item evaluation function.
predicateArg (any) – Optional predicate argument.

TimedActionUtils.transferSomeValid(character: IsoGameCharacter, type: string | nil, predicate: umbrella.ItemContainer_Predicate | nil, predicateArg: any, amount: integer)

Queues an action to transfer items matching the criteria from the character’s containers into their main inventory. This differs from regular transfer as the item is picked at the start of the action. This prevents issues where multiple queued actions target the same item, causing later actions to fail even though there are still valid items in the player’s inventory.

Parameters:

character (IsoGameCharacter) – The character.
type (string | nil) – The item type to transfer. If nil does not check item type.
predicate (umbrella.ItemContainer_Predicate | nil) – Optional item evaluation function.
predicateArg (any) – Optional predicate argument.
amount (integer) – Amount of items to transfer.

TimedActionUtils.transferAndEquip(character: IsoGameCharacter, item: InventoryItem | nil, slot: "primary" | "secondary" | "nil")

Queues actions to transfer an item to the character’s inventory and equip it. Actions will be skipped as appropriate if the item is already in the player’s inventory or already equipped in that slot.

Parameters:

character (IsoGameCharacter) – The character.
item (InventoryItem | nil) – The item to equip. If nil, the item already equipped in the slot will be unequipped, if any.
slot ("primary" | "secondary" | nil) – Which slot to equip it in. If not passed, primary is assumed.

TimedActionUtils.transferAndEquipFirstEval(character: IsoGameCharacter, eval: umbrella.ItemContainer_Predicate, slot: "primary"\ | "secondary" | nil) → found: boolean

Finds an item and queues actions to transfer it to the character’s inventory and equip it. Actions will be skipped as appropriate if a passing item is already in the player’s inventory or already equipped in that slot. No actions are queued if no item was found.

Parameters:

character (IsoGameCharacter) – The character
eval (umbrella.ItemContainer_Predicate) – Item evaluation function
slot ("primary" | "secondary" | nil) – Which slot to equip it in. If not passed, primary is assumed

Returns:

found (boolean) – Whether an item was found. This doesn’t necessarily mean the actions will go through, as the item could already be equipped.

TimedActionUtils.transferAndWear(character: IsoGameCharacter, item: Clothing)

Queues actions to transfer an item to the character’s inventory and wear it. Actions will be skipped as appropriate if the item is already in the player’s inventory or already worn.

Parameters:

character (IsoGameCharacter) – The character.
item (Clothing) – The item to equip.

TimedActionUtils.transferAndWearFirstEval(character: IsoGameCharacter, eval: umbrella.ItemContainer_Predicate) → found: boolean

Finds an item and queues actions to transfer it to the character’s inventory and wear it. Actions will be skipped as appropriate if the item is already in the player’s inventory or already worn. No actions are queued if no item was found.

Parameters:

character (IsoGameCharacter) – The character
eval (umbrella.ItemContainer_Predicate) – Item evaluation function. It must not return true for items that cannot be worn.

Returns:

found (boolean) – Whether an item was found. This doesn’t necessarily mean the actions will go through, as the item could already be equipped.

TimedActionUtils.unequip(character: IsoGameCharacter, item: InventoryItem)

Queues actions to unequip an item if it is equipped or worn. Does nothing if the item is not equipped or worn.

Parameters:

character (IsoGameCharacter) – The character.
item (InventoryItem) – The item to unequip.

Deprecated since version Replaced: by TimedActionUtils.transferFirstValid(), which incorporates the same functionality and more.

TimedActionUtils.transferFirstType(character: IsoGameCharacter, type: string, predicate: umbrella.ItemContainer_Predicate | nil, predicateArg: any)

Queues an action to transfer the first item of a type to the character’s inventory. This differs from regular transfer as the item is picked at the start of the action. This prevents issues where multiple queued actions target the same item, causing later actions to fail even though there are still valid items in the player’s inventory.

Parameters:

character (IsoGameCharacter) – The character.
type (string) – The item type to transfer.
predicate (umbrella.ItemContainer_Predicate | nil) – Optional item evaluation function.
any (predicateArg) – Optional predicate argument.