5. Entities and symbols

This chapter describes the Viv type universe, meaning the kinds of things that can be cast in roles.

Simulated storyworld

Viv interacts with a running simulation instance managed by the host application, which in Viv parlance is often called the simulated storyworld, or just storyworld.

Entities

An entity is a persistent thing in the simulated storyworld.

Each entity has a unique identifier called an entity ID, which is a string provisioned by the host application, and persistent data that the Viv runtime may read and write via the host application’s Viv adapter.

Entity types

There are four entity types in Viv: characters, items, locations, and actions. Roles and variables binding entity values are prefixed with the entity sigil @.

Characters

Characters initiate actions, participate in them in other ways, and witness events as bystanders. They also form memories when they experience or otherwise learn about actions, which can be searched via queries and sifting patterns. The Viv runtime assumes that each character is in a discrete storyworld location at any given point.

Items

Items are inanimate objects in the storyworld that characters can involve in actions. While the exact sense of ‘item’ depends on the host application, items do not take action or form memories. Knowledge about past actions can be inscribed onto items and later revealed to characters via inspection. As with characters, the Viv runtime assumes that each item is in a discrete storyworld location at any given point.

Locations

Locations are discrete storyworld locales that characters can involve in actions. They are also the places where characters and items may be located.

Actions

Past actions are themselves entities to which subsequent actions can refer. Critically, the Viv runtime tracks causal relations between actions, which enables story sifting.

Symbols

A symbol is a value that does not correspond to an entity in the host application.

Generally speaking, a symbol role allows an author to hoist an arbitrary value into the core data for an action (or another construct). As an example, consider the &evidence role here, which provides additional flavor to the action by selecting from a list literal of strings serving a one-off casting pool:

action botched-burglary:
    gloss: "@burglar burgled and left &evidence at the scene"
    roles:
        @burglar:
            as: initiator
        &evidence:
            as: symbol
            from: ["fingerprints", "a strand of hair", "their wallet"]

Scratch variables and local variables can also take symbol values. As with symbol roles, the binding type is marked by the symbol sigil &: $&thing, _&thing.

Role labels by type

The mapping between types and role labels is as follows. Note that symbols are not entities, but they can be cast in roles.

Type	Role labels
Character	character, initiator, partner, recipient, bystander
Item	item
Location	location
Action	action
Symbol	symbol