dao::abilities
Abilities: their names, whether a creature can use one now and what it costs, and cooldowns.
Declared in dao/Abilities.h.
Classes
| Class | |
|---|---|
| Cooldown | An ability’s cooldown on a creature, in seconds of game time. |
| CooldownSet | A cooldown the scripts’ SetCooldown has just set, as reported to OnCooldownSet. |
| RunningCooldown | A cooldown running on a creature. |
| Use | Whether a creature can use an ability now, and if not, why not. |
Enumerations
Kind
enum class Kind : std::int32_t
The kinds of ability, numbered like the scripts’ ABILITY_TYPE_* constants.
| Value | |
|---|---|
All = 0 |
|
Talent = 1 |
|
Spell = 2 |
|
Skill = 3 |
|
Item = 4 |
abilities of usable items, such as a poultice |
Functions
CanUse()
std::optional<Use> CanUse(ObjectId creature, std::int32_t ability, std::wstring_view itemTag={})
Checks whether a creature can use an ability now, with the same test the game uses to grey out a quickbar button.
Call it on the game thread. It checks the item, active modes, disabling effects, the cost, the ability’s requirements (such as a weapon or a shield), the cooldown, and whether the ability is already being cast. The scripts check the cost again, slightly differently, when the command runs, so a sustained (modal) ability this reports as usable can still fail.
| Parameter | |
|---|---|
itemTag |
as for GetCooldown |
Returns the result, or nullopt if the creature does not exist
Cooldowns()
std::vector<RunningCooldown> Cooldowns(ObjectId creature)
Returns every cooldown running on a creature, whatever started it: using the ability, a script, an item, or SetCooldown.
Call it on the game thread.
Returns the cooldowns, or an empty vector if the creature does not exist or has none running
Cost()
std::optional<float> Cost(ObjectId creature, std::int32_t ability)
Returns what an ability costs a creature now in mana or stamina, as CanUse calculates it: the ability table’s cost, raised by the creature’s fatigue.
Compare it with the creature’s remaining mana or stamina (CCCreature::ManaStamina).
Returns the cost, or nullopt if the creature does not exist or the ability has no row
GetCooldown()
std::optional<Cooldown> GetCooldown(ObjectId creature, std::int32_t ability, std::wstring_view itemTag={})
Returns an ability’s cooldown on a creature.
| Parameter | |
|---|---|
itemTag |
the tag of the item the ability comes from, like the scripts’ sSourceItemTag; empty for the creature’s own ability |
Returns the cooldown, or nullopt if the creature does not exist or does not have the ability
Known()
std::vector<std::int32_t> Known(ObjectId creature, Kind kind=Kind::All)
Returns every ability of one kind that a creature has, or of all kinds: its whole character sheet, not only what is on the quickbar.
The list includes hidden abilities, such as the class’s own, and a skill appears once for each rank the creature has, each with its own id.
| Parameter | |
|---|---|
kind |
the kind to list; Kind::All for every kind |
Returns the ability ids, or an empty vector if the creature does not exist
Label()
std::optional<std::wstring> Label(std::int32_t ability)
Returns an ability’s label in the ability table, for example L”FIREBALL”.
| Parameter | |
|---|---|
ability |
the ability’s id, a row of the ABI_base table |
Returns the label, or nullopt if no row has that id or the tables are not loaded yet
Name()
std::optional<std::wstring> Name(std::int32_t ability)
Returns an ability’s name in the player’s language, for example L”Fireball”.
| Parameter | |
|---|---|
ability |
the ability’s id, a row of the ABI_base table |
Returns the name; the label if the row has no name string; nullopt if no row has that id or the tables are not loaded yet
OnCooldownSet()
void OnCooldownSet(std::function<void(const CooldownSet &)> observer)
Registers a callback for every cooldown the scripts set, which includes every cooldown the game starts when an ability is used.
It runs on the game thread after the game’s write, so a cooldown you set from the callback replaces the script’s. It does not run for this library’s own SetCooldown.
| Parameter | |
|---|---|
observer |
receives the cooldown after the game has written it |
SetCooldown()
bool SetCooldown(ObjectId creature, std::int32_t ability, float remaining, float total, std::wstring_view itemTag={})
Sets an ability’s cooldown to remaining seconds left out of total.
Call it on the game thread. The scripts’ SetCooldown sets both numbers to the same time; this lets the sweep start partly full. OnCooldownSet does not report calls to it.
| Parameter | |
|---|---|
remaining |
seconds of game time until the ability can be used again; 0 ends the cooldown, and a negative value counts as 0 |
total |
the length the quickbar’s sweep measures remaining against |
itemTag |
as for GetCooldown |
Returns false, changing nothing, if the creature does not exist or does not have the ability, or if total is 0 or less while remaining is not 0