Optional ReadonlyappendA function that accepts an entity ID for a parent action and a child action,
and appends the latter to the former's caused property.
Here, 'parent' and 'child' refer to direct causal relations.
If this fast path is not supplied, the Viv runtime will fall back various other fast paths, to the degree they have been supplied.
Entity ID for the parent action whose caused property will be updated.
Entity ID for the child action, which just occurred and is thus not already
in caused (i.e., no need to worry about deduplication).
Nothing.
Optional ReadonlyappendA function that accepts an entity ID for an ancestor action and a descendant action,
and appends the latter to the former's descendants property.
Here, 'ancestor' and 'descendant' refer to causal relations, either direct or indirect.
If this fast path is not supplied, the Viv runtime will fall back various other fast paths, to the degree they have been supplied.
Entity ID for the ancestor action whose descendants property will be updated.
Entity ID for the descendant action, which just occurred and is thus not
already in descendants (i.e., no need to worry about deduplication).
Nothing.
Optional ReadonlyappendA function that updates the given entity's data by appending the given value to the array property at the specified path, potentially with deduplication.
If this fast path is not supplied, this will be implemented using other fast paths, to the degree that they are supplied.
Important: As explained in HostApplicationAdapterFastPaths.getEntityProperty, Viv supports autovivification, a policy that must also be honored here. In addition to creating any intermediate structure, if the property to which the value will be appended does not yet exist, it must be created first.
The entity ID of the entity whose data is to be updated.
A path to the particular property of the entity data that is to be updated, structured
as an array of property keys and/or array indices -- examples: ["friends", 2, "status"] and
["nearby", "artifacts.treatise", "school of thought"]. Note that property keys are arbitrary strings
that may contain dots, whitespace, or any other character. If you plan to convert the path array into
a string so that you can use something like Lodash to execute the entity update, you'll need to take
care to ensure that your conversion procedure is properly robust. And again, as stated above, you must
support autovivification for any undefined substructures along this property path.
The value to append to the property specified by propertyPath.
Whether the resulting array property value should have no duplicates. If true,
you must only append value if it is not already present in the array property.
Nothing.
Optional ReadonlydeleteA function that deletes the plan state for the plan with the given UID (i.e., deletes this
key and its associated entry from the activePlans field of the VivInternalState).
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, deleting the applicable plan state, and setting the entire VivInternalState via HostApplicationAdapter.saveVivInternalState.
Note: This function will never be called for a plan whose state has not been initialized yet.
UID for the plan whose state is to be deleted.
Nothing.
Optional ReadonlygetA function that accepts an entity ID for an action and returns an array containing
entity IDs for all causal ancestors of the given one (i.e., its ancestors property).
If this fast path is not supplied, the Viv runtime will fall back to the HostApplicationAdapterFastPaths.getEntityProperty fast path, if supplied, and otherwise to HostApplicationAdapter.getEntityView.
Important: Viv assumes that it can freely mutate the furnished data, with any actual updates being persisted via adapter functions or CustomFunction, so be sure to clone as needed.
Entity ID for the action whose causal ancestors will be returned.
An array containing entity IDs for all the causal ancestors of the given one.
Optional ReadonlygetA function that accepts an entity ID for an action and returns an array containing entity
IDs for all causal descendants of the given one (i.e., its descendants property).
If this fast path is not supplied, the Viv runtime will fall back to the HostApplicationAdapterFastPaths.getEntityProperty fast path, if supplied, and otherwise to HostApplicationAdapter.getEntityView.
Important: Viv assumes that it can freely mutate the furnished data, with any actual updates being persisted via adapter functions or CustomFunction, so be sure to clone as needed.
Entity ID for the action whose causal descendants will be returned.
An array containing entity IDs for all the causal descendants of the given one.
Optional ReadonlygetA function that returns the action queue for the character with the given entity ID, if any, else an empty array.
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, and pulling the desired action queue from there.
Entity ID for the character whose action queue is to be retrieved.
The action queue for the character with the given entity ID, if any, else an empty array.
Optional ReadonlygetA function that returns all active plan states (i.e., the value for the activePlans field
of the VivInternalState).
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, and pulling the active plan states from there.
All active plan states.
Optional ReadonlygetA function that accepts an entity ID for a character and an entity ID for an action and returns
the given character's memory of the given action, if they have one, else null.
If this fast path is not supplied, the Viv runtime will fall back to the HostApplicationAdapterFastPaths.getEntityProperty fast path, if supplied, and otherwise to HostApplicationAdapter.getEntityView.
Important: Viv assumes that it can freely mutate the furnished data, with any actual updates being persisted via adapter functions or CustomFunction, so be sure to clone as needed.
Entity ID for the character whose memory will be returned.
Entity ID for the action whose associated memory will be returned.
The given character's memory of the given action, if they have one, else null.
Optional ReadonlygetA function that returns the entity ID for the current location of the given entity.
If this fast path is not supplied, the Viv runtime will fall back to the HostApplicationAdapterFastPaths.getEntityProperty fast path, if supplied, and otherwise to HostApplicationAdapter.getEntityView.
Entity ID for the entity whose location will be returned.
The Entity ID for the given entity's current location.
Optional ReadonlygetA function that returns the value stored at the specified path in the given entity's data.
If this fast path is not supplied, the Viv runtime will fall back to using HostApplicationAdapter.getEntityView.
Important: Viv assumes that it can freely mutate the furnished data, with any actual updates being persisted via adapter functions or CustomFunction, so be sure to clone as needed.
The entity ID of the entity whose data is to be retrieved.
A path to the particular property of the entity data that is to be updated, structured
as an array of property keys and/or array indices -- examples: ["targets", 2, "status"] and
["stats", "equipment.weapon", "critical hit chance"]. Note that property keys are arbitrary strings
that may contain dots, whitespace, or any other character. If you plan to convert the path array into
a string so that you can use something like Lodash to carry out the retrieval, you'll need to take
care to ensure that your conversion procedure is properly robust.
The value stored at the specified path in the given entity's data.
Optional ReadonlygetA function that returns the entity type for the given entity.
If this fast path is not supplied, the Viv runtime will fall back to the HostApplicationAdapterFastPaths.getEntityProperty fast path, if supplied, and otherwise to HostApplicationAdapter.getEntityView.
Entity ID for the entity whose entity type will be returned.
The entity type for the given entity.
Optional ReadonlygetA function that returns the inscriptions for the given item.
If this fast path is not supplied, the Viv runtime will fall back to the HostApplicationAdapterFastPaths.getEntityProperty fast path, if supplied, and otherwise to HostApplicationAdapter.getEntityView.
Entity ID for the item whose inscriptions will be returned.
The inscriptions for the given item.
Optional ReadonlygetA function that returns the global plan queue contained in the VivInternalState.
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, and pulling the global plan queue from there.
The global plan queue contained in the VivInternalState.
Optional ReadonlygetA function that returns the plan state for the plan with the given UID (i.e., the entry for this
key in the activePlans field of the VivInternalState).
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, and pulling the desired plan state from there.
Note: This function will never be called for a plan whose state has not been initialized yet.
UID for the plan whose state is to be retrieved.
The plan state for the plan with the given UID.
Optional ReadonlygetA function that returns the queued-construct statuses stored in the VivInternalState.
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire VivInternalState, via HostApplicationAdapter.getVivInternalState, and pulling the queued-construct statuses from there.
The queued-construct statuses stored in the VivInternalState.
Optional ReadonlyisA function that returns whether a given string is the entity ID for some entity in the host application.
If this fast path is not supplied, the Viv runtime will fall back to calling HostApplicationAdapter.getEntityView and catching the errors thrown in cases of undefined entities.
This function is used by the runtime to determine whether it needs to hydrate a potential entity ID into an entity view.
Important: Because Viv's fallback implementation relies on HostApplicationAdapter.getEntityView throwing an error in the case of a missing entity, you should implement this fast path if your HostApplicationAdapter.getEntityView can fail for reasons other than a missing entity (e.g., a DB connection issue).
A string whose status as an entity ID is to be tested.
Whether the given string is an entity ID.
Optional ReadonlysaveA function that updates the action queue for the character with the given entity ID.
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, updating the action queue for the character in question, and setting the entire VivInternalState via HostApplicationAdapter.saveVivInternalState.
Entity ID for the character whose action queue is to be updated.
The updated action queue to set.
Nothing.
Optional ReadonlysaveA function that updates the global plan queue contained in the VivInternalState.
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, updating its global plan queue, and setting the entire VivInternalState via HostApplicationAdapter.saveVivInternalState.
The updated global plan queue to set.
Nothing.
Optional ReadonlysaveA function that updates the plan state for the plan with the given UID (i.e., the entry for this
key in the activePlans field of the VivInternalState).
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, updating the applicable plan state, and setting the entire VivInternalState via HostApplicationAdapter.saveVivInternalState.
UID for the plan whose state is to be updated.
The updated plan state to set.
Nothing.
Optional ReadonlysaveA function that accepts a UID and (potentially updated) status for a queued construct and persists that status in the VivInternalState.
If this fast path is not supplied, the Viv runtime will fall back to retrieving the entire Viv internal state, via HostApplicationAdapter.getVivInternalState, updating the associated queued-construct status, and setting the entire VivInternalState via HostApplicationAdapter.saveVivInternalState.
UID for the queued construct whose status will be set.
The status to set for the queued construct.
Nothing.
A collection of optional functions implementing frequent read and write operations, so as to be optimized according to implementation details specific to the host application at hand.
All the entries here are optional. If a given entry isn't present, the Viv runtime will use a corresponding naive procedure with the same semantics. For instance, if an HostApplicationAdapter.updateEntityProperty fast path is not supplied, the Viv runtime will read the complete entity data, mutate it to capture the property update, and then write the complete updated entity data.