See AttemptActionArgs.
const actionID = await attemptAction({
actionName: "give-gift",
initiatorID: "cid-alice",
precastBindings: { "giver": ["cid-alice"], "receiver": ["cid-bob"], "gift": ["chocolate"] },
causes: ["aid-97", "aid-1732"],
suppressConditions: true
});
if (actionID === null) {
console.log("No action performed");
}
VivNotInitializedError If Viv has not been initialized.
VivInterpreterError If the Viv interpreter encounters an issue in the course of action selection.
VivValidationError If the supplied args do not conform to the expected schema.
VivValidationError If there is no defined action with the given actionName.
VivValidationError If initiatorID is provided, but is not an entity ID for a character.
VivValidationError If both initiatorID and precastBindings are provided, but initiatorID
does not appear in precastBindings under the initiator role.
VivValidationError If precastBindings is provided, and the precast bindings fail validation.
VivValidationError If causes is provided, but contains something
other than an entity ID for an action.
Invokes the Viv action manager to force targeting of the specific given action.
This function can be useful for debugging, and it can also support designs where a host application takes a more direct role in action selection. For instance, a host application might implement a lightweight drama manager that occasionally intervenes to force targeting of a particular action that is narratively desirable at some point. As another example, an application might incorporate player activity into the Viv action system by representing the player as a character who is cast as initiator in actions that are defined in the content bundle. In the latter situation, non-player characters (NPCs) would "understand" those actions for free, leading to believable reactions and, ultimately, emergent storylines that weave together player and NPC activities.