Viv

The goals we set for the system are heroic, and demand heroic test cases.

— Sheldon Klein (1976)

Overview

Emergent Narrative You write Viv code, put characters in your game (or other simulation), and Viv makes the magic happen. Stories emerge according to what you authored.

Story Sifting Viv detects emergent storylines as they develop, allowing your game to understand—and surface—the narrative that happens to happen in a given playthrough.

Source-Available Anyone can view the full codebase on GitHub. Non-commercial use is freely permitted, while commercial use requires a license from Sifty, the studio behind Viv.

A Labor of Love Viv is designed, built, and maintained by me, James Ryan. It's based on my PhD work at UC Santa Cruz—and thousands of hours of follow-on work in industry contexts.

Features

Actions & Reactions Characters perform actions, and actions trigger reactions, growing emergent storylines through causal connections.

Knowledge Propagation Characters remember actions. This knowledge can then be spread via subsequent actions and item inscriptions—and characters react to what they learn.

Plans Write tiny programs that queue reactions over diegetic spans ranging from a single timestep to an entire century or more.

Queries & Sifting Patterns Author queries and higher-order patterns that match actions and full-fledged emergent storylines. Then run them over historical actions—or a character's memories.

Causal Bookkeeping The system automatically records causal links between actions as they occur, under the operational semantics of the language, making the full causal graph a given for story sifting.

Authorial Control Viv is a symbolic AI system, with no LLMs in the loop at runtime. Behavior is fully specified by your authored Viv code, making the system highly controllable.

Usage

Write Viv Code Write code in the Viv language, using the plugin for your preferred IDE or lightweight code editor.

Compile Viv Code Compile your code into a content bundle by invoking the Viv compiler—without leaving your IDE.

Plug Into Your Project Create a Viv adapter that connects the Viv runtime to your host application, enabling Viv to read and write your sim data.

Run Viv Code Invoke the Viv runtime to act on your content bundle for action selection, plan execution, story sifting, and more.

Simple Example

Here’s a simple, yet potent, Viv action that shows off a bit of the syntax.

This action is initiated by a character who searches over their own memories to find evidence of another character repeatedly mistreating them, and it can only be performed if such memories exist. As a result of the action, the initiator will lower their affinity toward the character in question—and may even plot revenge as a result.

// A character processes their repeated mistreatment by another character
action contemplate-mistreatment:
    roles:
        @thinker:
            as: initiator
        @subject:
            as: character, anywhere  // Not physically present
        @mistreatments*:  // 3-5 past actions where @subject harmed @thinker
            as: action
            n: 3-5
            from:
                search query harm:  // Defined elsewhere: a query for finding harmful actions
                    over: @thinker  // Search over @thinker's memories
                    with:
                        @perpetrator: @subject
                        @victim: @thinker
    effects:
        // Affinity isn't modeled in Viv, but you can read and write arbitrary sim data
        @thinker.affinity[@subject] -= #BIG
    reactions:
        if @thinker.personality.vengeful:  // More arbitrary sim data (from Viv's view)
            queue plan plot-revenge:  // Defined elsewhere: a plan for orchestrating the actions of a revenge scheme
                with:
                    @plotter: @thinker
                    @target: @subject
        end

As these events unfold, Viv will work behind the scenes to automatically track all the causal threads: the @mistreatments* actions → contemplate-mistreatment → the plot-revenge actions. This happens automatically behind the scenes, via Viv’s mechanism for causal bookkeeping. Later on, the emergent storylines embedded in this graph can easily be detected via Viv’s facilities for story sifting.

All the while, the Viv author has not been tasked with explicitly marking these links—they simply wrote down what kinds of past actions might lead someone to perform contemplate-mistreatment, and what kinds of follow-on actions might happen as a result of its performance.

For a more extensive example of Viv code, see the working example here.

Learn More

Quickstart Get up and running in no time.

Introduction Features, design philosophy, and an extensive tour.

Tour: A Revenge Story A whirlwind tour of the Viv language, from gossip notes to arson to knowledge-propagating monuments.

A Brief History A brief account of the Viv project and its origins.

Language Reference A complete specification of the Viv language.

JavaScript Runtime API Reference for the Viv JavaScript runtime system.

Install the Components

Compiler The Viv compiler, published on PyPI.

JavaScript Runtime The Viv JavaScript runtime, published on npm.

JetBrains Plugin Full-featured IDE support for Viv code.

VS Code Extension Lightweight editor support for Viv code.

Sublime Text Package Lightweight editor support for Viv code.

Claude Code Plugin LLM-powered Viv expertise in your terminal.

View the Codebase

Viv Monorepo The entire Viv codebase is available for viewing on GitHub.