Viv Language Reference

The Viv language reference is the complete specification of the Viv domain-specific language (DSL). It documents the syntax and semantics of every construct in the language.

Below you’ll find a listing of its chapters.

Foundations

Introduction A high-level overview of the language and how to read this reference.

Lexical elements Tokens, keywords, operators, punctuation, and whitespace.

File structure How constructs are organized in .viv source files.

Includes Splitting source code across multiple files with include statements.

Entities and symbols Characters, items, enums, and function references.

Names and sigils Identifiers, role prefixes, and naming conventions.

Expressions Values, operators, and the computation sublanguage.

Statements and control flow Conditionals, loops, and imperative blocks.

Constructs

Roles Casting characters, items, and past actions into construct slots.

Actions The core simulation unit: what characters do.

Reactions Queued responses to past actions, with automatic causal tracking.

Temporal constraints Timing, delays, and intervals for reactions and plans.

Bindings Passing values between constructs.

Tropes Reusable bundles of conditions with a name.

Queries Rich criteria for searching the chronicle or character memories.

Sifting patterns Matching sequences of actions—emergent storylines.

Plans Multi-phase orchestrators for coordinating reactions over time.

Selectors Tiny programs for choosing actions or plans from candidates.

System

Compiler output The shape of the JSON content bundle emitted by the compiler.

Runtime model How the runtime executes content bundles.

Appendices

Appendix A: Implementation notes Internals for curious contributors.

Glossary Definitions of terms used throughout the reference.

Compiler Reference How to compile Viv source files into JSON content bundles.

JavaScript Runtime API How to execute compiled content bundles at runtime.