Interface HostApplicationAdapter

A function that returns the current timestamp (in story time) in the running simulation instance associated with the host application.

Here, story time refers to the concept of time within the storyworld being simulated by the host application, as opposed to clock time in the real world as the host application operates. In other words, diegetic time.

Important: Viv assumes that a DiegeticTimestamp is represented as the number of minutes, in story time, that have passed since some initial reference point in the simulation. The starting point that is used for this determination is up to you, but the time unit must be minutes.

This allows the Viv runtime to properly handle authored temporal constraints in reaction declarations, which allow for semantics such as "this reaction can only occur between one week and six months from now".

A function that returns an array containing entity IDs for entities of the given type in the running simulation instance of the host application.

If a location is specified, the result should be limited to entities currently situated at that location. Otherwise, the result should contain entity IDs for all entities of the given type.

Important: Viv considers a character or item to be at a location if the entity's location property (in its CharacterView or ItemView) stores the entity ID for that location. Also, Viv assumes that it can freely mutate the furnished array, so be sure to clone as needed.

A function that accepts an ID for an entity and returns a label for the entity, such as its name, that is suitable for insertion into a templated string.

For example, a Viv author might write a templated string "@giver gives @item to @receiver", which the interpreter will have to render by replacing the references @giver, @item, and @receiver with strings.

To do this, the runtime will call this function for each reference. Note that, for references to values that are not entity IDs, the value itself will be inserted without any calls to an adapter function, as in @giver.name gives { ~getItemDescription(@item.id) } to @receiver.name.

A function that accepts an entity ID and returns the full entity view for that entity, if there is such an entity, else throws an error.

This function is used by the runtime to evaluate expressions such as conditions and effects. Note that the runtime will be careful to only pass an actual entity ID for entityID. How exactly the entity data is persisted is a nuance of the host application that is abstracted from the Viv runtime via the adapter interface. If fetching is expensive -- e.g., because it persists in a DB -- you might consider implementing caching in your application.

Important: Viv assumes that it can freely mutate the furnished data, with any actual updates being persisted via an adapter function (or CustomFunction), so be sure to clone as needed.

A function that returns the internal state of the Viv runtime, if it has been initialized, else null.

While the Viv runtime will manage its own internal state, it relies on the host application to persist it.

If the internal state has not been initialized -- i.e., the runtime has never called HostApplicationAdapter.saveVivInternalState -- then you should return null here.

A function that returns a newly provisioned entity ID for an action.

Note that this function is used to request IDs for queued actions that may never actually be performed. As such, not all IDs provisioned by this function will actually come to be associated with recorded actions.

This is the only case where a UID will need to be provisioned for Viv, because entities created as a result of Viv actions will be initialized via a custom function specified in the spawn field of a role definition.

A function that accepts a record describing an action and saves the underlying data in the host application.

This function is called both to create new action records and to update existing action records.

Important: The action record must be persisted such that any subsequent call to HostApplicationAdapter.getEntityView (with entityID) must produce an ActionView.

Note: If HostApplicationAdapter.updateEntityProperty is implemented, Viv authors will be free to directly set action data via assignments. How that works behind the scenes depends on the host application.

A function that accepts a record describing a character memory and saves the underlying data in the host application.

This function is called both to create new character memories and to update existing ones.

Important: The memory record must be persisted such that any subsequently retrieved CharacterView for the character in question will include the memory data in its CharacterView.memories field.

A function that accepts an item and updated inscriptions for that item and saves the underlying data in the host application.

Important: The inscriptions must be persisted such that any subsequently retrieved ItemView for the item in question will include the inscriptions value in its ItemView.inscriptions field.

A function that accepts updated internal state for the Viv runtime, and then persists the updated state in the host application.

If supplied, configuration parameters controlling various aspects of Viv system behavior. Default values will be used for parameters that are not supplied.

If supplied, settings activating debugging facilities of the Viv runtime.

If supplied, a mapping from enum names to their associated literal values in the host application.

In Viv, enums are abstract labels like #BIG or #SMALL that may be used in places like effects, in lieu of magic numbers (or strings) that are prone to changing. For instance, an author could specify an effect like @insulted.updateAffinity(@insulter, -#MEDIUM), which specifies that someone who has just been insulted should greatly lower their affinity toward their insulter. For various reasons, this is preferable to something like @insulted.updateAffinity(@insulter, -35).

Upon adapter registration, the Viv runtime will confirm that all enums referenced in your content bundle are present in this mapping here.

If supplied, 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.

If supplied, a mapping from custom-function names to CustomFunction.

A host application can expose arbitrary functions in its Viv adapter, which authors can reference using the ~ sigil, as in e.g. ~transport(@person.id, @destination.id). The author defines the arguments using Viv expressions, which will each be evaluated prior to being passed into the actual custom function. The custom function is expected to return an expression value, which is a highly permissive union of various types.

Important: Viv will dehydrate all arguments prior to passing them into a custom function, meaning any instance of entity data will be converted into its corresponding entity ID. This allows an author to write something like ~move(@person, @destination) without having to worry about whether to pass in the respective id properties.

If implemented, a function that returns the current time of day (in story time) in the running simulation instance associated with the host application.

Here, story time refers to the concept of time within the storyworld being simulated by the host application, as opposed to clock time in the real world as the host application operates. This function is needed in order to enforce time-of-day constraints that Viv authors may place on actions, specifying concerns such as "this reaction may only be performed between 10pm and 11:59pm".

If your simulation does not model time of day, you can leave this one out, in which case the adapter validator will ensure that no reactions in your content bundle reference time of day.

If implemented, a function that updates the given entity's data by setting the property at the specified path.

If this adapter function is not provided, entity data may only be updated via calls to CustomFunction. Further, the validator will ensure that no assignments in your content bundle target entities.

Important: Viv supports autovivification (no pun intended), where an author may reference potentially undefined substructures along a path that will be created as needed. As such, in your procedure backing this adapter function, all intermediate objects along propertyPath must be created if they do not already exist.

As an illustrative example, in Viv the assignment @person.foo.bar.baz = 77 is still valid even if @person.foo does not yet have a bar property. As such, your update procedure would have to set @person.foo.bar to an object {baz: 77} in this case. When setting local variables, which do not need to persist in the host application, the Viv runtime uses the default autovivification semantics of the Lodash set() function when it's given an array path: when a missing intermediate value is encountered, make it an array only if the next key is a non-negative integer, otherwise make it a plain object.