The SBIR Binary Format

SBIR (Storybook Intermediate Representation) is the compiled binary format produced by the Storybook compiler. It transforms human-readable .sb files into an optimized, machine-consumable format for simulation runtimes.

Compilation Pipeline

.sb files → Lexer → Parser → AST → Resolver → SBIR Binary
  1. Lexer: Tokenizes raw text into tokens
  2. Parser: Builds an Abstract Syntax Tree (AST) from tokens
  3. Resolver: Validates, resolves cross-references, merges templates, and produces SBIR

What SBIR Contains

SBIR represents the fully resolved state of a Storybook project:

  • Characters: All fields resolved (species + templates merged, overrides applied)
  • Behaviors: Behavior trees with all subtree references inlined
  • Life Arcs: State machines with validated transitions
  • Schedules: Time blocks with resolved action references
  • Relationships: Participants with resolved entity references
  • Institutions: Fully resolved field sets
  • Locations: Fully resolved field sets
  • Species: Fully resolved inheritance chains
  • Enums: Complete variant lists

Resolution Process

Template Merging

When a character uses templates, SBIR contains the fully merged result:

Source:

species Human { lifespan: 70, speed: 1.0 }
template Warrior { speed: 1.5, strength: 10 }

character Conan: Human from Warrior {
    strength: 20
}

In SBIR, Conan’s fields are:

  • lifespan: 70 (from Human)
  • speed: 1.5 (Warrior overrides Human)
  • strength: 20 (Conan overrides Warrior)

Cross-File Reference Resolution

SBIR resolves all use statements and qualified paths. A relationship referencing Martha in a different file is resolved to the concrete character definition.

Validation

Before producing SBIR, the resolver validates all constraints documented in Validation Rules:

  • All references resolve to defined declarations
  • No circular dependencies
  • Type consistency
  • Domain constraints (bond ranges, schedule validity)

Design Goals

Compact: SBIR strips comments, whitespace, and redundant structure.

Self-contained: No external references – everything is resolved and inlined.

Fast to load: Simulation runtimes can load SBIR without re-parsing or re-resolving.

Validated: If SBIR was produced, the source was valid. Runtimes do not need to re-validate.

Usage

SBIR is consumed by simulation runtimes that drive character behavior, schedule execution, life arc transitions, and relationship queries. The specific binary format is implementation-defined and may evolve between versions.

For the current SBIR specification, see the SBIR v0.2.0 Spec.

Cross-References