studio/storybook
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release: Storybook v0.2.0 - Major syntax and features update

Browse Source 
BREAKING CHANGES:
- Relationship syntax now requires blocks for all participants
- Removed self/other perspective blocks from relationships
- Replaced 'guard' keyword with 'if' for behavior tree decorators

Language Features:
- Add tree-sitter grammar with improved if/condition disambiguation
- Add comprehensive tutorial and reference documentation
- Add SBIR v0.2.0 binary format specification
- Add resource linking system for behaviors and schedules
- Add year-long schedule patterns (day, season, recurrence)
- Add behavior tree enhancements (named nodes, decorators)

Documentation:
- Complete tutorial series (9 chapters) with baker family examples
- Complete reference documentation for all language features
- SBIR v0.2.0 specification with binary format details
- Added locations and institutions documentation

Examples:
- Convert all examples to baker family scenario
- Add comprehensive working examples

Tooling:
- Zed extension with LSP integration
- Tree-sitter grammar for syntax highlighting
- Build scripts and development tools

Version Updates:
- Main package: 0.1.0 → 0.2.0
- Tree-sitter grammar: 0.1.0 → 0.2.0
- Zed extension: 0.1.0 → 0.2.0
- Storybook editor: 0.1.0 → 0.2.0
This commit is contained in:
Sienna Meridian Satterwhite
2026-02-13 21:52:03 +00:00
parent 80332971b8
commit 16deb5d237
290 changed files with 90316 additions and 5827 deletions
Download Patch File Download Diff File Expand all files Collapse all files

623
docs/examples/24-baker-family-complete.md Normal file
View File

@@ -0,0 +1,623 @@
# Baker Family Complete
This example demonstrates a complete Storybook project modeling Martha's bakery and the people around it. It showcases all major language features working together.
## Project Structure
```
baker-family/
schema/
core_enums.sb # Enum definitions
templates.sb # Reusable templates
beings.sb # Species definitions
world/
characters/
martha.sb # Martha, master baker
jane.sb # Jane, pastry specialist
elena.sb # Elena, apprentice
gregory.sb # Gregory, regular customer
family.sb # David, Tommy, Emma
behaviors/
bakery_behaviors.sb
relationships/
bakery_relationships.sb
locations/
bakery_places.sb
institutions/
bakery_institutions.sb
schedules/
bakery_schedules.sb
```
## Schema Layer
### Enums
```storybook
// schema/core_enums.sb
enum SkillLevel {
novice,
beginner,
intermediate,
advanced,
expert,
master
}
enum Specialty {
sourdough,
pastries,
cakes,
general,
bread
}
enum Confidence {
timid,
uncertain,
growing,
steady,
confident,
commanding
}
enum DayPart {
early_morning,
morning,
midday,
afternoon,
evening,
night
}
```
### Species
```storybook
// schema/beings.sb
species Human {
lifespan: 80
---description
Bipedal mammals with complex language and tool use.
---
}
species Cat {
lifespan: 15
---description
Domestic cats often found in bakeries for pest control
and companionship.
---
}
```
### Templates
```storybook
// schema/templates.sb
template SkilledWorker {
skill_level: SkillLevel
confidence: Confidence
years_experience: 0..50
can_work_independently: false
}
template Baker {
include SkilledWorker
specialty: Specialty
recipes_mastered: 0..200
sourdough_starter_health: 0.0..1.0
}
template BusinessOwner {
include SkilledWorker
revenue_monthly: 0..100000
employees: 0..20
years_in_business: 0..50
}
template Apprentice {
include SkilledWorker
skill_level: novice
confidence: timid
mentor: string
dedication: 0.0..1.0
}
```
## Characters
### Martha
```storybook
// world/characters/martha.sb
use schema::core_enums::{SkillLevel, Specialty, Confidence};
use schema::templates::{Baker, BusinessOwner};
use schema::beings::Human;
character Martha: Human from Baker, BusinessOwner {
uses behaviors: [
{ tree: BakerMorningRoutine },
{ tree: HandleEmergency, when: emergency_detected, priority: critical }
]
age: 34
specialty: sourdough
skill_level: master
confidence: commanding
recipes_mastered: 85
years_experience: 22
sourdough_starter_health: 0.95
revenue_monthly: 12000
employees: 3
years_in_business: 8
---backstory
Martha learned to bake from her grandmother, starting at age twelve.
By twenty she had won regional competitions. At twenty-six she opened
her own bakery, which quickly became the most popular in town. Her
sourdough is legendary -- she maintains a starter that is fifteen
years old.
---
}
life_arc MarthaCareerArc {
---description
Tracks Martha's evolution from established baker to community leader.
---
state running_bakery {
on enter {
Martha.confidence: commanding
Martha.skill_level: master
}
on employees > 5 -> expanding
}
state expanding {
on enter {
Martha.revenue_monthly: 20000
}
on second_location_opened -> community_leader
}
state community_leader {
on enter {
Martha.can_teach: true
Martha.mentors_count: 3
}
---narrative
Martha's bakery has become a training ground for the next
generation of bakers. She sits on the guild board and her
sourdough recipe is studied at culinary schools.
---
}
}
```
### Jane
```storybook
// world/characters/jane.sb
use schema::core_enums::{SkillLevel, Specialty, Confidence};
use schema::templates::Baker;
use schema::beings::Human;
character Jane: Human from Baker {
age: 36
specialty: pastries
skill_level: expert
confidence: confident
recipes_mastered: 120
years_experience: 18
can_work_independently: true
---backstory
Jane trained at a prestigious culinary school before joining
Martha's bakery as co-owner. Where Martha excels at bread, Jane
is a pastry artist. Her croissants draw customers from three
towns over.
---
---appearance
A focused woman with flour-dusted apron and steady hands.
Known for her intricate pastry decorations and precise
temperature control.
---
}
```
### Elena
```storybook
// world/characters/elena.sb
use schema::core_enums::{SkillLevel, Confidence};
use schema::templates::Apprentice;
use schema::beings::Human;
character Elena: Human from Apprentice {
age: 16
skill_level: novice
confidence: timid
mentor: "Martha"
dedication: 0.9
natural_talent: 0.8
recipes_mastered: 2
---backstory
Elena comes from a family of farmers who could never afford to
buy bread from the bakery. When Martha offered her an apprenticeship,
she jumped at the chance to learn a trade.
---
}
life_arc ElenaCareer {
---description
Tracks Elena's progression from nervous apprentice to confident
master baker. Each state represents a key phase of her career.
---
state early_apprentice {
on enter {
Elena.skill_level: novice
Elena.confidence: timid
}
on recipes_mastered > 5 -> growing_apprentice
---narrative
Elena's hands shake as she measures flour. She checks the
recipe three times before adding each ingredient. Martha
patiently corrects her technique.
---
}
state growing_apprentice {
on enter {
Elena.skill_level: beginner
Elena.confidence: uncertain
}
on recipes_mastered > 15 -> journeyman
---narrative
The shaking stops. Elena can make basic breads without
looking at the recipe. She still doubts herself but
Martha's encouragement is taking root.
---
}
state journeyman {
on enter {
Elena.skill_level: intermediate
Elena.confidence: growing
Elena.can_work_independently: true
}
on recipes_mastered > 30 -> senior_journeyman
---narrative
Elena runs the morning shift alone while Martha handles
special orders. Customers start asking for "Elena's rolls."
She begins experimenting with her own recipes.
---
}
state senior_journeyman {
on enter {
Elena.skill_level: advanced
Elena.confidence: steady
}
on recipes_mastered > 50 -> master
---narrative
Elena develops her signature recipe: rosemary olive bread
that becomes the bakery's bestseller. She handles difficult
customers with grace and trains new helpers.
---
}
state master {
on enter {
Elena.skill_level: master
Elena.confidence: commanding
Elena.can_teach: true
}
---narrative
Master Baker Elena. She has earned it. The guild acknowledges
her mastery, and Martha beams with pride. Elena begins
mentoring her own apprentice.
---
}
}
```
### Gregory
```storybook
// world/characters/gregory.sb
use schema::beings::Human;
character Gregory: Human {
age: 68
occupation: "retired_teacher"
always_orders: "sourdough_loaf"
visits_daily: true
years_as_customer: 15
knows_everyone: true
---backstory
Gregory has been buying Martha's bread every morning for
fifteen years. Their brief daily exchanges about the weather
and local gossip are a comforting routine for both of them.
---
}
```
## Behaviors
```storybook
// world/behaviors/bakery_behaviors.sb
behavior BakerMorningRoutine {
---description
Martha's morning routine: prepare dough step by step,
from mixing to shaping to baking.
---
then morning_baking {
// Start with sourdough
then prepare_starter {
CheckStarter
FeedStarter
WaitForActivity
}
// Mix the dough
then mix_dough {
MeasureFlour
AddWater
IncorporateStarter
}
// Knead and shape
then shape_loaves {
KneadDough
FirstRise
ShapeLoaves
}
// Bake
then bake {
PreHeatOven
LoadLoaves
MonitorBaking
}
}
}
behavior CustomerServiceLoop {
---description
The bakery's continuous customer service loop. Uses infinite
repeat decorator to serve customers throughout the day.
---
repeat {
then service_cycle {
// Check for customers
choose service_mode {
then serve_waiting {
if(customer_waiting)
GreetCustomer
TakeOrder
}
then restock_display {
if(display_low)
FetchFromKitchen
ArrangeOnShelves
}
}
// Process payment
CollectPayment
ThankCustomer
// Brief pause between customers
timeout(5s) {
CleanCounter
}
PrepareForNextCustomer
}
}
}
```
## Relationships
```storybook
// world/relationships/bakery_relationships.sb
relationship MarthaAndGregory {
Martha {
role: shopkeeper
values_loyalty: 0.9
---perspective
Martha appreciates Gregory's unwavering loyalty. He has
been buying her sourdough loaf every morning for fifteen
years. Their brief daily exchanges about the weather and
local gossip are a comforting routine.
---
}
Gregory {
role: regular_customer
always_orders: "sourdough_loaf"
---perspective
Gregory considers Martha's bakery a cornerstone of his
daily routine. The bread is excellent, but it is the brief
human connection that keeps him coming back.
---
}
}
relationship MentorApprentice {
Martha {
role: mentor
teaching_style: "patient"
investment: 0.9
---perspective
Martha sees Elena as the daughter she might have had in
the trade. She recognizes the same passion she felt at
that age and pushes Elena harder because she knows the
talent is there. Every correction comes from love.
---
}
Elena {
role: apprentice
dedication: 0.9
anxiety: 0.4
---perspective
Elena idolizes Martha's skill but fears disappointing
her. Every morning she arrives thirty minutes early to
practice techniques before Martha gets in. She keeps a
notebook of every correction, reviewing them each night.
---
}
bond: 0.85
}
relationship BakeryPartnership {
Martha {
role: co_owner
specialty: "bread"
handles_finances: true
---perspective
Martha and Jane complement each other perfectly. Martha
handles the bread and business side while Jane creates
the pastries that draw customers in. Together they have
built something neither could alone.
---
}
Jane {
role: co_owner
specialty: "pastries"
handles_creativity: true
---perspective
Jane considers Martha the steady foundation of their
partnership. While Jane experiments and creates, Martha
ensures the bakery runs like clockwork. Their different
strengths make the bakery stronger.
---
}
bond: 0.9
}
```
## Locations
```storybook
// world/locations/bakery_places.sb
location MarthasBakery {
type: "commercial"
established: "2018"
square_feet: 1200
has_kitchen: true
has_storefront: true
seating_capacity: 12
---description
A warm, inviting bakery on Main Street. The aroma of fresh
bread wafts out the door every morning at 4 AM. Exposed brick
walls, a glass display case, and a view into the kitchen where
customers can watch the bakers at work.
---
}
location FarmersMarket {
type: "outdoor_market"
operates_on: "saturday"
stalls: 30
foot_traffic: "high"
---description
The weekly Saturday market where Martha sells her bread directly
to the community. Her stall is always the first to sell out.
---
}
location BakeryKitchen {
type: "commercial_kitchen"
ovens: 3
prep_stations: 4
walk_in_cooler: true
---description
The heart of the bakery. Three professional ovens line the back
wall, each at a different temperature for different breads. The
sourdough starter sits on a shelf near the warmest oven, bubbling
contentedly in its ceramic crock.
---
}
```
## Institutions
```storybook
// world/institutions/bakery_institutions.sb
institution BakersGuild {
type: professional_guild
members: 45
founded: "1952"
meets_monthly: true
---description
The local bakers' guild that sets quality standards, organizes
competitions, and mentors apprentices. Martha has been a board
member for three years.
---
}
```
## Key Takeaways
This example demonstrates:
1. **Layered architecture**: Schema (types) separated from world (instances)
2. **Species + Templates**: `Human` species combined with `Baker` and `BusinessOwner` templates
3. **Rich behavior trees**: Morning routine and customer service with choose, then, and repeat
4. **Asymmetric relationships**: Martha and Elena see their mentorship differently
5. **Life arcs**: Elena's career journey modeled as a state machine
6. **Prose everywhere**: Every declaration includes narrative context
## Cross-References
- [Tutorial](../tutorial/01-welcome.md) - Step-by-step learning
- [Characters Reference](../reference/10-characters.md) - Character syntax
- [Behavior Trees Reference](../reference/11-behavior-trees.md) - Behavior syntax

339
docs/examples/25-day-in-life.md Normal file
View File

@@ -0,0 +1,339 @@
# Day in the Life
This example models a complete day for a baker character, showing how schedules, behaviors, and life arcs work together to create a rich daily simulation.
## The Baker
```storybook
use schema::core_enums::{Season, DayOfWeek};
use schema::beings::Human;
use schema::templates::SkilledWorker;
character Martha: Human from SkilledWorker {
age: 42
occupation: "Master Baker"
skill_level: 0.95
energy: 1.0
mood: 0.8
uses schedule: MarthaDailySchedule
uses behaviors: [
{ tree: BakerRoutine, priority: normal },
{ tree: HandleEmergency, when: emergency_detected, priority: critical }
]
---backstory
Martha has been baking since she was twelve, learning from her
grandmother. She now runs the most popular bakery in town and
is known for her sourdough bread and apple pastries.
---
}
```
## The Schedule
```storybook
schedule MarthaDailySchedule {
block wake_up {
04:00 - 04:30
action: routines::morning_wake
}
block early_baking {
04:30 - 07:00
action: baking::prepare_morning_goods
}
block open_shop {
07:00 - 07:15
action: shop::open_for_business
}
block morning_rush {
07:15 - 10:00
action: shop::serve_morning_customers
}
block midday_baking {
10:00 - 12:00
action: baking::prepare_afternoon_goods
}
block lunch_break {
12:00 - 13:00
action: social::lunch_with_family
}
block afternoon_sales {
13:00 - 16:00
action: shop::serve_afternoon_customers
}
block close_shop {
16:00 - 16:30
action: shop::close_for_day
}
block evening_prep {
16:30 - 17:30
action: baking::prepare_dough_for_tomorrow
}
block family_time {
18:00 - 21:00
action: social::family_evening
}
block sleep {
21:00 - 04:00
action: routines::sleep
}
// Saturday: Market day
recurs MarketDay on day saturday {
block market_prep {
03:00 - 05:00
action: baking::market_batch
}
block market_sales {
06:00 - 14:00
action: market::sell_at_stall
}
block market_cleanup {
14:00 - 15:00
action: market::pack_up
}
}
// Summer: Extended hours
block summer_afternoon {
13:00 - 18:00
action: shop::extended_summer_hours
on season summer
}
}
```
## Behaviors
### Morning Routine
```storybook
behavior BakerMorningRoutine {
then morning_sequence {
WakeUp
WashFace
DressInWorkClothes
// Check the sourdough starter
then check_starter {
ExamineStarter
if(starter_healthy) {
FeedStarter
}
}
WalkToKitchen
LightOven
}
}
```
### Baking Behavior
```storybook
behavior BakerRoutine {
choose baking_priority {
// Handle special orders first
then special_orders {
if(has_special_orders)
then fill_order {
ReviewOrderDetails
GatherSpecialIngredients
PrepareSpecialItem
PackageForCustomer
}
}
// Regular daily baking
then daily_bread {
then sourdough {
MixDough(recipe: "sourdough", quantity: 10)
KneadDough(duration: 15m)
FirstRise(duration: 2h)
ShapLoaves
SecondRise(duration: 1h)
BakeLoaves(temperature: 230, duration: 35m)
}
}
// Pastries if time permits
then pastries {
succeed_always {
then apple_pastries {
PrepareFillingApple
RollPastryDough
AssemblePastries
BakePastries(temperature: 200, duration: 25m)
}
}
}
}
}
```
### Customer Service
```storybook
behavior ServeCustomer {
then service_sequence {
GreetCustomer
if(customer_is_regular) {
RecallPreferences
}
choose service_type {
then take_order {
if(customer_knows_what_they_want)
AcceptOrder
PackageItem
}
then help_decide {
if(not customer_knows_what_they_want)
OfferRecommendation
ProvidesSample
AcceptOrder
PackageItem
}
}
CollectPayment
ThankCustomer
}
}
```
### Emergency Handling
```storybook
behavior HandleEmergency {
choose emergency_type {
then oven_fire {
if(oven_overheating)
TurnOffOven
GrabFireExtinguisher
ExtinguishFire
AssessDamage
}
then ingredient_shortage {
if(critical_ingredient_missing)
CheckBackupSupply
choose procurement {
SendApprenticeToMarket
SubstituteIngredient
AdjustMenu
}
}
then equipment_failure {
if(equipment_broken)
StopProduction
AttemptQuickFix
choose fallback {
UseBackupEquipment
CallRepairPerson
}
}
}
}
```
## Life Arc: Career and Energy
```storybook
life_arc MarthaEnergyLevel {
state rested {
on enter {
Martha.energy: 1.0
Martha.mood: 0.8
}
on energy < 0.5 -> tired
}
state tired {
on enter {
Martha.mood: 0.6
}
on energy < 0.2 -> exhausted
on energy > 0.7 -> rested
}
state exhausted {
on enter {
Martha.mood: 0.3
Martha.quality_output: 0.7
}
on energy > 0.5 -> tired
}
}
```
## Relationships
```storybook
relationship MarthaAndApprentice {
Martha as mentor self {
patience: 0.8
investment: 0.9
} other {
sees_potential: 0.85
}
Elena as apprentice self {
dedication: 0.9
learning_rate: 0.7
} other {
respect: 0.95
admiration: 0.8
}
bond: 0.85
years_together: 2
}
relationship MarthaAndRegularCustomer {
Martha as shopkeeper
OldManGregory as regular_customer
bond: 0.7
years_known: 15
always_orders: "sourdough_loaf"
---dynamics
Gregory has been buying Martha's bread every morning for
fifteen years. They exchange brief pleasantries about the
weather and local gossip. He is her most reliable customer.
---
}
```
## Key Takeaways
This example demonstrates:
1. **Schedule-driven daily flow**: Precise time blocks govern Martha's entire day
2. **Seasonal and weekly variations**: Summer hours and Saturday market
3. **Layered behaviors**: Emergency behavior preempts normal routine via priority
4. **Realistic action sequences**: Baking modeled step by step with parameters
5. **Energy management**: Life arc tracks fatigue affecting mood and output quality
6. **Social connections**: Relationships with apprentice and customers add depth
## Cross-References
- [Schedules Reference](../reference/14-schedules.md) - Schedule syntax
- [Behavior Trees Reference](../reference/11-behavior-trees.md) - Behavior syntax
- [Life Arcs Reference](../reference/13-life-arcs.md) - Life arc syntax

352
docs/examples/26-character-evolution.md Normal file
View File

@@ -0,0 +1,352 @@
# Character Evolution
This example models a character who evolves through multiple life stages, demonstrating how life arcs, behavior trees, and templates work together to represent growth over time.
## The Apprentice's Journey
Elena starts as a nervous apprentice and grows into a confident master baker. Her evolution touches every aspect of her character: skills, personality, relationships, and daily routine.
### Schema
```storybook
enum SkillLevel { novice, beginner, intermediate, advanced, expert, master }
enum Confidence { timid, uncertain, growing, steady, confident, commanding }
template Apprentice {
skill_level: novice
confidence: timid
can_work_independently: false
recipes_mastered: 0..5
}
template Journeyman {
skill_level: intermediate
confidence: growing
can_work_independently: true
recipes_mastered: 10..30
}
template MasterBaker {
skill_level: master
confidence: commanding
can_work_independently: true
can_teach: true
recipes_mastered: 50..200
}
```
### The Character at Different Stages
```storybook
// Elena starts as an apprentice
character Elena: Human from Apprentice {
age: 16
natural_talent: 0.8
dedication: 0.9
recipes_mastered: 2
confidence: timid
mentor: Martha
---backstory
Elena comes from a family of farmers who could never afford to
buy bread from the bakery. When Martha offered her an apprenticeship,
she jumped at the chance to learn a trade.
---
}
```
### The Evolution Life Arc
```storybook
life_arc ElenaCareer {
---description
Tracks Elena's progression from nervous apprentice to
confident master baker over several years.
---
state apprentice_early {
on enter {
Elena.skill_level: novice
Elena.confidence: timid
Elena.can_work_independently: false
}
on recipes_mastered > 5 -> apprentice_growing
---narrative
Elena's hands shake as she measures flour. She checks the
recipe three times before adding each ingredient. Martha
patiently corrects her technique.
---
}
state apprentice_growing {
on enter {
Elena.skill_level: beginner
Elena.confidence: uncertain
}
on recipes_mastered > 15 -> journeyman
---narrative
The shaking stops. Elena can make basic breads without
looking at the recipe. She still doubts herself but
Martha's encouragement is taking root.
---
}
state journeyman {
on enter {
Elena.skill_level: intermediate
Elena.confidence: growing
Elena.can_work_independently: true
}
on recipes_mastered > 30 and confidence is steady -> senior_journeyman
---narrative
Elena runs the morning shift alone while Martha handles
special orders. Customers start asking for "Elena's rolls."
She begins experimenting with her own recipes.
---
}
state senior_journeyman {
on enter {
Elena.skill_level: advanced
Elena.confidence: steady
}
on recipes_mastered > 50 and passed_master_trial -> master
---narrative
Elena develops her signature recipe: rosemary olive bread
that becomes the bakery's bestseller. She handles difficult
customers with grace and trains new helpers.
---
}
state master {
on enter {
Elena.skill_level: master
Elena.confidence: commanding
Elena.can_teach: true
}
---narrative
Master Baker Elena. She has earned it. The guild acknowledges
her mastery, and Martha beams with pride. Elena begins
mentoring her own apprentice.
---
}
}
```
### Evolving Behaviors
Elena's behavior changes as she progresses:
```storybook
// Early apprentice: hesitant, checks everything
behavior Elena_ApprenticeEarly {
then cautious_baking {
CheckRecipeThreeTimes
MeasureCarefully
AskMarthaForConfirmation
ProceedSlowly
CheckResultAnxiously
}
}
// Growing apprentice: more confident
behavior Elena_ApprenticeGrowing {
then competent_baking {
ReviewRecipe
MeasureIngredients
MixWithConfidence
choose problem_handling {
then handle_alone {
if(confidence > 0.4)
AssessSituation
ApplyLearning
}
AskMarthaForHelp
}
}
}
// Journeyman: independent and creative
behavior Elena_Journeyman {
choose work_mode {
then creative_mode {
if(inspiration_high)
ExperimentWithRecipe
TasteTest
if(result_good) {
RecordNewRecipe
}
}
then production_mode {
ExecuteRecipeFromMemory
MonitorOvenTimings
ManageMultipleBatches
}
then teaching_mode {
if(helper_present)
DemonstrateTeechnique
ObserveHelper
ProvideGentleFeedback
}
}
}
// Master: leadership and mentoring
behavior Elena_Master {
choose master_activity {
then mentor_apprentice {
if(apprentice_needs_guidance)
AssessApprenticeProgress
DesignLearningChallenge
ObserveAndFeedback
}
then innovate {
if(creative_energy_high)
ResearchNewTechniques
ExperimentWithIngredients
DocumentFindings
}
then lead_production {
PlanDailyProduction
DelegateToTeam
QualityCheckResults
}
}
}
```
### Evolving Relationships
The mentor relationship changes as Elena grows:
```storybook
// Early apprenticeship
relationship EarlyMentorship {
Martha as mentor self {
patience: 0.9
teaching_intensity: 0.8
} other {
sees_potential: 0.8
reminds_her_of_herself: true
}
Elena as apprentice self {
gratitude: 1.0
anxiety: 0.7
} other {
admiration: 0.95
intimidated: 0.5
}
bond: 0.6
}
// Later: colleagues and friends
relationship MaturePartnership {
Martha as senior_partner self {
pride_in_elena: 0.95
ready_to_step_back: 0.6
} other {
sees_equal: 0.8
trusts_judgment: 0.9
}
Elena as junior_partner self {
confidence: 0.85
gratitude: 0.9
} other {
respect: 0.95
sees_as_mother_figure: 0.7
}
bond: 0.95
}
```
### Evolving Schedules
Elena's schedule changes as she takes on more responsibility:
```storybook
// Apprentice schedule: supervised hours
schedule ElenaApprentice {
block arrive {
06:00 - 06:15
action: routines::arrive_early
}
block learn_and_assist {
06:15 - 14:00
action: baking::assist_martha
}
block cleanup_duty {
14:00 - 15:00
action: shop::cleanup
}
block study {
15:00 - 16:00
action: learning::study_recipes
}
}
// Master schedule: leadership hours
schedule ElenaMaster extends ElenaApprentice {
block arrive {
04:00 - 04:15
action: routines::open_bakery
}
block learn_and_assist {
04:15 - 12:00
action: baking::lead_production
}
block cleanup_duty {
12:00 - 13:00
action: social::lunch_with_team
}
block study {
13:00 - 15:00
action: baking::mentor_apprentice
}
block business {
15:00 - 17:00
action: management::business_planning
}
}
```
## Key Takeaways
This example demonstrates:
1. **Life arcs as character development**: Elena's career progression modeled as states
2. **Evolving behaviors**: Different behavior trees for each stage of growth
3. **Changing relationships**: The mentor dynamic shifts from dependency to partnership
4. **Schedule evolution**: Responsibilities grow with skill level
5. **Narrative prose**: Each life arc state tells a story about who Elena is becoming
6. **Template progression**: Templates define the capability profile at each stage
## Cross-References
- [Life Arcs Reference](../reference/13-life-arcs.md) - State machine syntax
- [Design Patterns](../advanced/20-patterns.md) - Progressive development pattern
- [Best Practices](../advanced/23-best-practices.md) - Character design guidelines

548
docs/examples/27-multi-character.md Normal file
View File

@@ -0,0 +1,548 @@
# Multi-Character Interactions
This example models a complex social scene: a busy Saturday morning at Martha's bakery. Multiple characters interact simultaneously with interlocking behaviors, relationships, and a shared location buzzing with activity.
## The Setting
```storybook
enum RushLevel { calm, busy, hectic, overwhelming }
enum ServiceMode { normal, rush, emergency }
location BakeryStorefront {
rush_level: busy
current_time: 07:30
customers_waiting: 8
display_items_remaining: 45
oven_batches_in_progress: 3
coffee_machine_running: true
---description
Saturday morning at Martha's bakery. The line stretches out
the door. The display case gleams with fresh bread, pastries,
and Elena's famous rosemary olive rolls. The air is warm with
the smell of baking and the hum of conversation.
---
---atmosphere
This is the bakery at its best and most stressful. Every
Saturday brings the regulars, the farmers' market overflow,
and tourists who heard about Martha's sourdough. The whole
team works in concert to keep up.
---
}
institution SaturdayMorningCrew {
type: work_team
purpose: serve_customers_and_bake
members: 4
coordination_level: 0.9
---description
The Saturday crew operates like a well-oiled machine. Martha
runs the kitchen, Jane handles pastries, Elena manages the
front counter, and Gregory -- the loyal regular -- unofficially
helps direct the line.
---
}
```
## The Characters
```storybook
use schema::core_enums::{SkillLevel, Confidence, Specialty};
use schema::templates::{Baker, BusinessOwner, Apprentice};
use schema::beings::Human;
character Martha: Human from Baker, BusinessOwner {
age: 34
specialty: sourdough
skill_level: master
confidence: commanding
energy: 0.8
stress_level: 0.4
loaves_baked_today: 24
orders_pending: 6
---personality
Calm under pressure. Martha thrives on Saturday mornings --
the rush brings out her best. She coordinates the team with
quiet efficiency, stepping in wherever needed while keeping
the ovens running on schedule.
---
}
character Jane: Human from Baker {
age: 36
specialty: pastries
skill_level: expert
confidence: confident
energy: 0.9
creative_mode: true
pastries_decorated_today: 18
---personality
Jane works in focused silence during the rush. Her hands
move with precision, piping decorations and assembling
layered pastries. She communicates with Martha through
glances and nods -- years of partnership have made words
unnecessary.
---
}
character Elena: Human from Apprentice {
age: 17
skill_level: intermediate
confidence: growing
energy: 1.0
customers_served_today: 32
mistakes_today: 1
---personality
Elena has grown into the front-counter role. She remembers
regulars' names and orders, handles complaints with grace,
and only calls Martha when truly stuck. The nervous girl
who started a year ago is barely recognizable.
---
}
character Gregory: Human {
age: 68
role: "regular_customer"
visits_today: 1
helping_with_line: true
knows_everyone: true
---personality
Gregory arrives at exactly 7:15 every Saturday. He buys
his sourdough loaf, then lingers near the door, chatting
with other customers and unofficially managing the line.
He considers this his contribution to the bakery.
---
}
```
## Interlocking Behaviors
### Martha's Behavior
```storybook
behavior Martha_SaturdayMorning {
---description
Martha's Saturday morning routine: managing the kitchen,
coordinating the team, and keeping the ovens running.
---
repeat {
choose saturday_priority {
// Check ovens first (highest priority)
then oven_management {
if(oven_timer_near_done)
CheckOvenTemperature
RemoveFinishedBatch
LoadNextBatch
SetTimer
}
// Handle special orders
then special_orders {
if(has_special_orders)
choose order_type {
PrepareWeddingCake
BoxCustomOrder
DecorateSpecialLoaf
}
}
// Support Elena at counter
then help_counter {
if(elena_needs_help)
choose counter_support {
AnswerCustomerQuestion
HandleComplaint
ProcessLargeOrder
}
}
// Coordinate with Jane
then coordinate_pastries {
if(display_items_remaining < 10)
SignalJaneToRestockPastries
RearrangeDisplay
}
// Default: knead next batch
then prep_dough {
MixNextBatch
KneadDough
ShapeLoaves
}
}
}
}
```
### Jane's Behavior
```storybook
behavior Jane_SaturdayMorning {
repeat {
choose jane_priority {
// Restock display when signaled
then restock_pastries {
if(martha_signaled_restock)
PlateFinishedPastries
CarryToDisplay
ArrangeAttractively
}
// Decorate current batch
then decorating {
if(has_undecorated_pastries)
PipeIcing
AddGarnish
InspectQuality
}
// Start new pastry batch
then new_batch {
if(pastry_dough_ready)
RollPastryDough
CutShapes
AddFilling
PlaceOnBakingSheet
}
// Prepare specialty items
then specialty_items {
if(specialty_order_pending)
ReviewOrderNotes
SelectPremiumIngredients
CraftSpecialtyItem
}
}
}
}
```
### Elena's Behavior
```storybook
behavior Elena_SaturdayCounter {
choose counter_state {
// Serve waiting customers
then serve_customer {
if(customer_waiting)
then service_sequence {
GreetCustomer
if(customer_is_regular) {
RecallPreferences
}
choose order_handling {
then quick_order {
if(customer_knows_what_they_want)
AcceptOrder
PackageItem
}
then help_decide {
if(not customer_knows_what_they_want)
OfferRecommendation
OfferSample
AcceptOrder
PackageItem
}
}
CollectPayment
ThankCustomer
}
}
// Handle problems
then handle_issue {
if(customer_has_complaint)
choose resolution {
then resolve_alone {
if(confidence > 0.5)
ListenCarefully
OfferSolution
ApplyResolution
}
then escalate {
if(confidence <= 0.5)
AcknowledgeProblem
CallMarthaForHelp
}
}
}
// Manage the line
then manage_queue {
if(line_length > 5)
AnnounceWaitTime
SuggestPopularItems
}
}
}
```
### Gregory's Behavior
```storybook
behavior Gregory_SaturdayVisit {
then saturday_routine {
// Arrive and order
then arrival {
EnterBakery
GreetElena
OrderSourdoughLoaf
PayExactChange
}
// Linger and help
choose lingering_activity {
then manage_line {
if(line_is_long)
DirectNewCustomersToEndOfLine
ChatWithWaitingCustomers
RecommendPopularItems
}
then catch_up {
if(sees_familiar_face)
GreetNeighbor
ExchangeLocalNews
DiscussWeather
}
then observe_elena {
if(elena_handling_difficult_customer)
StandNearbyForMoralSupport
NodEncouragingly
}
}
// Eventually leave
then departure {
WaveToMartha
SayGoodbyeToElena
ExitWithBread
}
}
}
```
## Relationships
```storybook
relationship BakeryPartnership {
Martha {
role: co_owner
coordination: 1.0
handles_bread: true
---perspective
Martha and Jane communicate without words during the rush.
A glance toward the display case means "we're running low."
A nod means "I'll handle it." Years of working side by side
have created an effortless rhythm.
---
}
Jane {
role: co_owner
coordination: 1.0
handles_pastries: true
---perspective
Jane trusts Martha's judgment completely during the Saturday
rush. If Martha signals, Jane reprioritizes. If Jane needs
oven time, Martha adjusts. They are two halves of a single
well-run kitchen.
---
}
bond: 0.95
}
relationship TeamAndApprentice {
Martha as mentor
Jane as senior_colleague
Elena as apprentice
bond: 0.8
---dynamics
Elena looks up to both Martha and Jane, but in different ways.
Martha teaches her the fundamentals -- technique, discipline,
consistency. Jane shows her the creative side -- decoration,
presentation, flavor combinations. Together they are shaping
Elena into a complete baker.
---
}
relationship GregoryAtTheBakery {
Gregory {
role: loyal_customer
attachment: 0.9
unofficial_helper: true
---perspective
The bakery is Gregory's third place -- not home, not the
library where he used to teach, but the warm space where
he belongs. He has watched Elena grow from a nervous girl
to a confident young woman. He is proud, though he would
never say so directly.
---
}
Elena {
role: counter_staff
fondness: 0.8
sees_as: "grandfather_figure"
---perspective
Elena looks forward to Gregory's arrival every morning.
His exact-change payment and dry humor are a reliable
anchor in the chaos of the morning rush.
---
}
bond: 0.7
}
```
## The Saturday Schedule
```storybook
schedule SaturdayRush {
block early_prep {
03:00 - 06:00
action: baking::saturday_batch
}
block opening {
06:00 - 06:15
action: shop::open_doors
}
block morning_rush {
06:15 - 11:00
action: shop::saturday_rush_service
}
block midday_restock {
11:00 - 12:00
action: baking::midday_supplemental
}
block afternoon_wind_down {
12:00 - 14:00
action: shop::afternoon_sales
}
block close_and_clean {
14:00 - 15:00
action: shop::saturday_cleanup
}
}
```
## Life Arc: Elena's Saturday Confidence
```storybook
life_arc ElenaSaturdayGrowth {
state nervous_start {
on enter {
Elena.confidence: uncertain
Elena.energy: 1.0
}
on customers_served_today > 5 -> finding_rhythm
---narrative
The first few customers are always the hardest. Elena
fumbles with the register, second-guesses prices, and
looks to Martha for confirmation. But each successful
transaction builds her up.
---
}
state finding_rhythm {
on enter {
Elena.confidence: growing
}
on customers_served_today > 15 -> in_the_zone
---narrative
Something clicks. Elena stops thinking about each step
and starts flowing. She remembers Mrs. Patterson's usual
order before she says it. She bags the croissants without
looking.
---
}
state in_the_zone {
on enter {
Elena.confidence: confident
}
on handled_complaint_alone -> proud_moment
on energy < 0.3 -> running_on_fumes
---narrative
Elena is running the counter like she was born to it.
Gregory gives her a quiet nod of approval from his spot
by the door. She barely notices -- she is too busy being
competent.
---
}
state proud_moment {
on enter {
Elena.confidence: confident
Elena.self_respect: 0.9
}
---narrative
A customer complained about a stale roll. Elena apologized,
replaced it with a fresh one, and offered a free cookie.
The customer left smiling. Elena handled it alone, without
calling Martha. She stands a little taller afterward.
---
}
state running_on_fumes {
on enter {
Elena.energy: 0.2
Elena.confidence: uncertain
}
on break_taken -> finding_rhythm
---narrative
The rush has been going for four hours. Elena's smile
is getting harder to maintain. Martha notices and sends
her to the back for a five-minute break and a pastry.
---
}
}
```
## Key Takeaways
This example demonstrates:
1. **Multiple characters with interlocking behaviors**: Martha, Jane, Elena, and Gregory react to each other
2. **Character coordination**: Martha and Jane operate as a seamless team
3. **Asymmetric group dynamics**: Gregory is an unofficial helper, Elena is growing into her role
4. **Location as context**: The busy bakery storefront defines the scene
5. **Institution modeling**: The Saturday crew as a coordinated work team
6. **Visitor arc**: Elena's confidence through the Saturday rush modeled as a life arc
7. **Rich prose**: Every character and relationship includes narrative perspective
## Cross-References
- [Relationships Reference](../reference/15-relationships.md) - Multi-party relationships
- [Behavior Trees Reference](../reference/11-behavior-trees.md) - Coordinated behaviors
- [Life Arcs Reference](../reference/13-life-arcs.md) - Scene-based state machines
- [Baker Family Complete](./24-baker-family-complete.md) - Full project context