ReadonlycausesEntity IDs for all the actions recorded as causes of the queued construct.
Whenever an action is ultimately performed by virtue of the queued construct -- even if transitively, e.g., via a plan queueing a plan queueing a plan that queues an action that is performed -- these causes will be recorded for the action as a matter of causal bookkeeping. This enables story sifting later on.
Note that the causes here may contain multiple entries, which occurs when an action relays knowledge about
the action to which the reaction was actually attached. To illustrate, consider the case of a reaction R
that is attached to an action A1, which ultimately causes a queued action to be performed, which we will
call Q. Now let's further say that Q's initiator, C, learned about A1, the direct cause of Q, via another
action, A2, which relays knowledge about A1 -- i.e., A2 casts A1 in one of its roles. In this case, when
C experiences A2, as a matter of course C will be cast in A1's special hearer role, with A1's effects
and reactions being handled for C accordingly. It is through this process that Q, a reaction on A1,
would be queued for C as a result of C learning about A1 via A2. In this case, both A1 and A2 would be
included in the causes for Q, with A1 being the zeroth entry (see the note on this just below). Note
that if A1 relays knowledge about an earlier action, A0, we will not evaluate A0's reactions upon C
learning about A1 via A2. We only follow a single chain link for effect and reaction handling, since
knowledge propagation would get out of hand otherwise.
Because reaction declarations can be wrapped in conditionals and loops, the only way for the causes
to make their way into the queued construct is insertion into the evaluation context, which we do
via the special __causes__ field in the evaluation context.
Some more notes: no duplicates will appear here, and the zeroth entry will always be the action that directly triggered queuing. We place this one first in order to ground temporal constraints on reactions, which may be anchored in the timestamp of the action that triggered the reaction.
If a plan triggered queueing, the action that queued the plan -- or the action that queued the plan that queued the plan, etc. -- will be the zeroth entry.
ReadonlyconstructThe name of the queued action.
ReadonlyidA unique identifier for the queued construct, provisioned by the host application via a call to the HostApplicationAdapter.provisionActionID adapter function. Should an actual action be performed or an actual plan be launched, the resulting action or plan will take on this UID.
ReadonlyinitiatorEntity ID for the prospective initiator of the action (selector).
ReadonlyprecastA mapping from a role name to an array of entity IDs for entities precast in that role.
ReadonlypriorityA numeric priority value that governs insertion into the initiator's queue. If the queued action
is also marked urgent, this will be used as a secondary ordering key inside the urgency bucket.
Higher values indicating a higher priority, and thus an earlier position in the queue.
ReadonlytypeDiscriminator for a queued action.
ReadonlyurgentWhether the queued construct is to be marked urgent.
For a queued action or action selector, this will cause it to be placed in the urgent heap of the associated initiator's action queue. For a queued plan or plan selector, this will cause the resulting plan to be immediately targeted (and potentially launched) upon being queued. This allows authors to specify complex action machinery that is intended to play out on the same timestep as precipitating action.
OptionalabandonmentAbandonment conditions for the queued construct.
If all these hold at any point at which the queued construct is being targeted, it will be dequeued.
OptionallocationIf present, predicates that will constrain where the eventual action may be performed.
OptionalrepeatRepeat logic for the queued construct.
OptionaltimeTemporal constraints on when exactly the eventual action may be performed. The constraints may specify a time-of-day window and/or a point-in-time window, with story time being the domain in each case. Note that the interpreter is tasked with grounding constraints into actual story time, as needed, by making use of the host application's Viv adapter.
An action that is queued for potential future performance by a given character.
Concretely, an action is queued when a reaction declaration for another action (or a plan) is acted upon. Queueing entails insertion into the prospective initiator's action queue, and ultimately there is no guarantee the action will actually be performed, since the author can constrain performance in various ways, including via expiration and abandonment criteria.