dao::commands
A creature’s commands: when they start and end, the steps they run, and holding a spell’s conjure.
Declared in dao/CommandEvents.h, dao/Conjure.h, dao/SubActions.h.
Classes
| Class | |
|---|---|
| Conjuring | How far along a conjure is. |
| Held | How much longer a command will keep a creature busy. |
| Hold | An effect’s hold on a creature: the effect its current command shows, and how much longer it keeps the creature busy. |
| SubAction | One step of a command. Times are in milliseconds of the creature’s own clock. |
Functions
Conjure()
std::optional<Conjuring> Conjure(ObjectId caster)
Returns how far along a caster’s conjure is, held or not.
Call it on the game thread (dao/Frame.h).
Returns nullopt if the caster is not conjuring or is not a creature, or if no game update has run since this part of the library was first used
ConjureHeld()
bool ConjureHeld(ObjectId caster)
Returns whether a caster’s conjures are held.
FeedConjure()
void FeedConjure(ObjectId caster, float seconds)
Gives a held caster’s conjure more time.
The conjure never runs past its duration. Time given while no conjure is running waits for the next one. Does nothing for a caster that is not held.
| Parameter | |
|---|---|
seconds |
the time to give, in game seconds; fractions of a millisecond carry over, and 0 or less does nothing |
HeldFor()
std::optional<Held> HeldFor(ObjectId creature)
Estimates from its sub-actions how much longer the creature’s current command will keep it busy.
Call it on the game thread. If known is false, the creature is busy for at least seconds. For example, the fall and the getting up after a knockback are not timed in advance.
Returns nullopt if the creature has no current command, or the ID is not a creature
HoldConjure()
void HoldConjure(ObjectId caster, bool hold=true)
Makes a caster’s conjures progress only through FeedConjure, or releases them.
A conjure already under way is held where it is. Moving into range, the cast, and everything after the conjure still run in real time.
| Parameter | |
|---|---|
hold |
true to hold; false to let the current conjure run on in real time from where it is |
HoldOf()
std::optional<Hold> HoldOf(ObjectId creature)
Returns the hold a creature is in: whether its current command is an effect’s (the engine’s ExecuteEffect, which a knockdown, stun, paralysis or sleep queues on it), and which effect.
The effect is the one the command’s step shows now: the creature’s effect of the highest priority, which a stronger effect arriving replaces. Call it on the game thread.
Returns nullopt if the creature’s current command is not an effect’s, or it is not a creature
OnEnd()
void OnEnd(std::function<void(ObjectId object, const Command &command, std::int32_t result)> observer)
Calls observer each time a creature or object ends a command, before the command is freed.
The observer runs on the game thread while the object’s queue is being processed, so keep it short, and don’t add or clear commands from it. The ExecuteEffect command that a dying creature starts never ends, so don’t wait for it.
| Parameter | |
|---|---|
observer |
receives the object, the command and its result: kSuccess, kLooping, kFailed, kCleared or a script::CommandFailed value |
OnHold()
void OnHold(std::function<void(ObjectId creature, const Hold &hold)> observer)
Calls observer when an effect’s command takes hold of a creature, on the frame after it starts, with the hold as HoldOf has it then.
Callbacks run on the game thread.
OnStart()
void OnStart(std::function<void(ObjectId object, const Command &command)> observer)
Calls observer each time a creature or object starts a command, before the command runs.
The observer runs on the game thread while the object’s queue is being processed, so keep it short, and don’t add or clear commands from it. A command can start and never end; see OnEnd.
| Parameter | |
|---|---|
observer |
receives the object and the command it is starting |
ResultName()
std::string_view ResultName(std::int32_t result)
Returns a name for a result, for logging: “success”, “looping”, “COMMAND_FAILED”, or the script name of a failure, such as “COMMAND_FAILED_TIMEOUT”.
The name only translates the number; it does not tell you whether the command worked. A use-object command that opens its door still ends with COMMAND_FAILED, for example.
Returns an empty view for a result that has no constant
RunningSubAction()
std::uint32_t RunningSubAction(ObjectId creature)
Returns the type of the sub-action that a creature’s current command is running or is about to run.
The game carries out a command, such as an attack, as a series of sub-actions: approach, aim, blow, and so on. This is the same value the IsConjuring script command returns. The known types:
- 1: a melee blow
- 2: a shot
- 4: the approach for a melee attack (dao/Attack.h)
- 6: a ranged attack’s aim
- 7: a spell’s conjure
- 8: an ability’s cost being taken, after the conjure
- 15: the approach for a ranged attack or an ability
- 37: a timed animation, such as a cast
- 39: turning to face the target
The creature walks only in 4 and 15. Call it on the game thread.
Returns the type; 0 if the creature has no current command, has no sub-action left in it, or is not a creature
SubActions()
std::vector<SubAction> SubActions(ObjectId creature)
Returns the sub-actions left in the creature’s current command, the running one first.
Call it on the game thread.
Returns an empty list if the creature has no command or no sub-actions left, or the ID is not a creature
Variables
kCleared
constexpr std::int32_t kCleared = -2
COMMAND_FAILED_COMMAND_CLEARED: cleared from the queue.
kFailed
constexpr std::int32_t kFailed = -1
COMMAND_FAILED.
kLooping
constexpr std::int32_t kLooping = 2
COMMAND_LOOPING: a looping animation ended.
kSuccess
constexpr std::int32_t kSuccess = 1
Results a command can end with, under their names in script.ldf.
The other failures are the COMMAND_FAILED_* values of script::CommandFailed. COMMAND_SUCCESSFUL