storybook/examples/alice-in-wonderland/README.md

Alice's Adventures in Wonderland - Storybook Example

A comprehensive demonstration of the Storybook DSL, modeling Lewis Carroll's Alice's Adventures in Wonderland with accuracy to the source material and showcasing all advanced language features.

Overview

This example shows how Storybook enables complex narrative modeling for agent simulation games. It demonstrates:

• Advanced behavior trees for complex, context-dependent character actions
• Life arcs tracking transformative character journeys
• Schedules modeling eternal time loops and recurring events
• Template composition with inheritance and strict mode
• Bidirectional relationships with asymmetric perspectives
• Cross-file references creating an interconnected world model

Contents

Schema Layer

schema/core_enums.sb

• Core value types used throughout: Size, EmotionalState, CardSuit, CardRank, TimeState, ManifestationLevel
• Demonstrates enumeration definitions

schema/templates.sb

• Base template WonderlandCreature for all sentient beings
• Specialized templates with include: SizeChanging, MadTeaPartyMember, Supernatural
• Strict template PlayingCard enforcing concrete values
• Shows vertical inheritance (includes) and horizontal composition (multiple from clauses)

schema/species.sb

• Species definitions: Human, Rabbit, Cat, Hare, Dormouse, Caterpillar, PlayingCardPerson
• Rich prose blocks describing characteristics and abilities

World Layer

Characters

alice.sb - The protagonist

• Inherits from SizeChanging template
• Life arc AliceJourney with states: falling, tiny_alice, giant_alice, normal_alice_garden, enlightened_alice
• Shows how life arcs track transformative journeys with state-specific field modifications

white_rabbit.sb - The anxious herald

• Behavior tree WhiteRabbit_ConstantlyLate using selectors (?) and sequences (>)
• Demonstrates hierarchical behavior modeling with panic strategies

cheshire_cat.sb - The enigmatic guide

• Three behavior trees:
  • CheshireCat_AppearDisappear - context-dependent materialization
  • CheshireCat_GradualManifestation - piece-by-piece appearance (grin first!)
  • CheshireCat_GradualDematerialization - fading away (grin lingers longest)
• Shows complex multi-step sequences with timing and state transitions

mad_tea_party.sb - The eternal tea party trio

• Three characters: MadHatter, MarchHare, Dormouse
• Schedule MadTeaPartyRotation modeling the time loop (always 6 o'clock)
• Behavior MadTeaParty_CoordinatedMadness showing multi-agent coordination
• Demonstrates repeater decorator (*) for infinite loops

royal_court.sb - The Court of Hearts

• Characters: QueenOfHearts, KingOfHearts, CardGardenerTwo, CardGardenerFive, CardGardenerSeven
• Inherits from PlayingCard strict template - card suit/rank must be concrete
• Behavior QueenOfHearts_RagePattern - hair-trigger temper response
• Behavior KingOfHearts_SecretPardons - background mercy system

caterpillar.sb - The philosophical teacher

• Behavior Caterpillar_SocraticMethod - interrogative teaching style
• Shows question-answer tree structures

Locations

wonderland_places.sb

• RabbitHole, HallOfDoors, Garden, MadTeaPartyTable, CroquetGround, QueensPalace, MushroomTop
• Each location has physical properties, symbolic meaning, and narrative significance
• Demonstrates rich prose blocks for description and analysis

Institutions

wonderland_institutions.sb

• CourtOfHearts - tyrannical monarchy with interesting power dynamics
• MadTeaParty - eternal social gathering stuck in time
• WonderlandDreamLogic - the meta-institution governing reality itself
• Shows how social structures can be modeled with hierarchies and rules

Relationships

wonderland_relationships.sb

• Bidirectional relationships with self and other blocks showing asymmetric perspectives:
  • AliceAndWhiteRabbit - pursuer/unwitting guide
  • AliceAndCheshireCat - seeker/amused observer
  • QueenAndKing - tyrant/secret rebel
  • AliceAndCaterpillar - frustrated student/Socratic teacher
• Demonstrates how different characters perceive the same relationship differently

Behaviors

alice_behaviors.sb - Alice's strategic behaviors

• Alice_SizeManagement - learning to control size through trial and error
• Alice_NavigateConversation - dealing with nonsensical logic
• Alice_EmotionalJourney - state transitions from curiosity to enlightenment
• Alice_ProblemSolving - adapting normal-world logic to Wonderland

Language Features Demonstrated

1. Template Composition

template WonderlandCreature {
    current_size: Size
    emotional_state: EmotionalState
    follows_logic: false..true
}

template SizeChanging {
    include WonderlandCreature
    natural_size: Size
    size_changes_today: 0..50
}

character Alice from SizeChanging {
    // Inherits all fields from WonderlandCreature and SizeChanging
    age: 7
    current_size: normal
}

2. Strict Templates

template strict PlayingCard {
    suit: CardSuit
    rank: CardRank
    // Characters using this template MUST provide concrete values
}

character QueenOfHearts from PlayingCard {
    suit: hearts    // Required: must be concrete enum value
    rank: queen     // Required: must be concrete enum value
}

3. Life Arcs

life_arc AliceJourney {
    state tiny_alice {
        on enter {
            Alice.current_size: tiny
            Alice.size_changes_today: +1
        }
    }

    state giant_alice {
        on enter {
            Alice.current_size: huge
        }
    }
}

4. Schedules

schedule MadTeaPartyRotation {
    18:00 -> 18:01: TeaRound { }
    18:01 -> 18:02: RiddlePhase { }
    // ... more phases
    18:05 -> 18:00: LoopToBeginning { }  // Loops back!
}

5. Behavior Trees

behavior CheshireCat_AppearDisappear {
    ? {  // Selector: try branches until one succeeds
        > {  // Sequence: all must succeed in order
            IsInvisible
            DecideToAppear
            GradualManifestation
        }
        > {
            IsVisible
            DecideToLeave
            GradualDematerialization
        }
    }
}

6. Repeater Decorator

behavior MadTeaParty_CoordinatedMadness {
    * {  // Repeater: loop forever
        ? {
            > { AskRiddle; ReceiveNoAnswer }
            > { RotateSeats; CheckTime }
        }
    }
}

7. Bidirectional Relationships

relationship QueenAndKing {
    QueenOfHearts
    KingOfHearts

    bond: 0.4

    self {
        // Queen's perspective
        role: dominant_spouse
        aware_of_pardons: false
    }

    other {
        // King's perspective
        role: secret_moderator
        subverts_authority: 1.0
    }
}

8. Rich Prose Blocks

character CheshireCat {
    ---description
    A large cat with a permanent, unsettling grin. Possesses the
    ability to appear and disappear at will, often leaving only
    its grin behind.
    ---

    ---philosophy
    The Cheshire Cat represents the absurdist nature of Wonderland
    itself. His vanishing act defies physical law but seems
    perfectly natural in Wonderland's logic.
    ---
}

9. Cross-File References

// In alice.sb
use schema::core_enums::{Size, EmotionalState};
use schema::templates::SizeChanging;

character Alice from SizeChanging {
    current_size: normal  // Uses Size enum from core_enums
}

10. Field Modifications in Life Arcs

state enlightened_alice {
    on enter {
        Alice.emotional_state: brave
        Alice.awareness_of_absurdity: 1.0  // Absolute assignment
        Alice.size_changes_today: +1       // Increment
    }
}

Accuracy to Source Material

This example stays faithful to Carroll's original text:

• Mad Tea Party: Time frozen at 6 o'clock, rotating seats, butter in the watch
• Cheshire Cat: Grin appearing first/last, cryptic directions, "we're all mad here"
• Queen of Hearts: Constant "Off with their heads!", card gardeners, croquet with flamingos
• Alice's transformations: Specific size states from the book
• Caterpillar's advice: Terse questions, mushroom sides
• Character dynamics: White Rabbit's anxiety, Dormouse's drowsiness, King's secret mercy

Running the Example

# Validate the entire project
sb validate examples/alice-in-wonderland/

# Query characters
sb query "characters where follows_logic == false"

# Inspect a specific character
sb inspect Alice

# Show all relationships
sb query "relationships where bond > 0.5"

What This Demonstrates

For Content Authors (Lonni)

• Rich character modeling: Personality traits, motivations, relationships
• Narrative structure: Life arcs track character journeys
• World building: Locations, institutions, social dynamics
• Prose integration: Backstories, descriptions, and philosophical notes

For Developers (Sienna)

• Complex behavior trees: Multi-level selectors, sequences, repeaters
• State management: Life arcs with field modifications
• Scheduling systems: Time loops and recurring events
• Type safety: Strict templates enforce constraints
• Cross-referencing: Build interconnected world models

For Agent Simulation

This model could drive an agent-based simulation where:

• Alice's behavior tree decides how to navigate conversations and obstacles
• The Mad Tea Party schedule creates a time-loop environment
• Cheshire Cat's appearance/disappearance behavior creates mystery
• Queen's rage pattern generates conflict
• Relationships determine interaction dynamics

Extending This Example

Ideas for additions:

• More chapters: Mock Turtle, Gryphon, Trial scene
• Croquet game logic: Behavior trees for live hedgehog/flamingo equipment
• Size change mechanics: Fine-grained mushroom nibbling behavior
• Dream logic system: Meta-rules governing Wonderland physics
• Alice's awakening: Final life arc state transitioning back to reality

License

Source material: Alice's Adventures in Wonderland by Lewis Carroll (public domain) Storybook adaptation: MIT License