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

723
docs/reference/15-relationships.md Normal file
View File

@@ -0,0 +1,723 @@
# Relationships
Relationships define connections between characters, institutions, and other entities. They capture social bonds, power dynamics, emotional ties, and interactive patterns. Relationships can be symmetric (friendship) or asymmetric (parent-child), and support bidirectional perspectives where each participant has different fields.
## What is a Relationship?
A relationship connects two or more participants and describes:
- **Participants**: The entities involved (characters, institutions)
- **Roles**: Optional labels (parent, employer, spouse)
- **Shared fields**: Properties of the relationship itself (bond strength, duration)
- **Perspective fields**: How each participant views the relationship (`self`/`other` blocks)
```
Relationship: ParentChild
├─ Participant: Martha (as parent)
│ ├─ self: { responsibility: 1.0, protective: 0.9 }
│ └─ other: { dependent: 0.8 }
├─ Participant: Tommy (as child)
└─ Shared: { bond: 0.9, years_together: 8 }
```
## Syntax
```bnf
<relationship-decl> ::= "relationship" <identifier> <body>
<body> ::= "{" <participant>+ <field>* "}"
<participant> ::= <qualified-path> <role-clause>? <perspective-blocks>?
<role-clause> ::= "as" <identifier>
<perspective-blocks> ::= "self" "{" <field>* "}" "other" "{" <field>* "}"
| "self" "{" <field>* "}"
| "other" "{" <field>* "}"
<field> ::= <identifier> ":" <value>
```
## Basic Relationships
### Simple Two-Party Relationship
```storybook
relationship Friendship {
Martha
Gregory
bond: 0.8
years_known: 15
}
```
**Semantics:**
- Two participants: Martha and Gregory
- Shared field: `bond` (strength of friendship)
- Shared field: `years_known` (duration)
### Multi-Party Relationship
```storybook
relationship Family {
Martha
David
Tommy
Elena
household: "Baker Residence"
family_bond: 0.95
}
```
Relationships can have any number of participants.
## Roles
Roles label a participant's function in the relationship.
### Syntax
```storybook
ParticipantName as role_name
```
### Examples
```storybook
relationship Marriage {
Martha as spouse
David as spouse
bond: 0.9
anniversary: "2015-06-20"
}
```
```storybook
relationship ParentChild {
Martha as parent
Tommy as child
bond: 0.95
guardianship: true
}
```
```storybook
relationship EmployerEmployee {
Martha as employer
Elena as employee
workplace: "Martha's Bakery"
salary: 45000
}
```
### Role Semantics
- **Labels**: Roles are descriptive labels, not types
- **Multiple roles**: Same person can have different roles in different relationships
- **Optional**: Roles are optional—participants can be unnamed
- **Flexibility**: No predefined role vocabulary—use what makes sense
## Perspective Fields (Self/Other Blocks)
Perspective fields specify how each participant views the relationship. They enable asymmetric, bidirectional relationships.
### Syntax
```storybook
ParticipantName as role self {
// Fields describing this participant's perspective
} other {
// Fields describing how this participant views others
}
```
### Self Block
The `self` block contains fields about how the participant experiences the relationship:
```storybook
relationship ParentChild {
Martha as parent self {
responsibility: 1.0
protective: 0.9
anxiety_level: 0.6
}
Tommy as child
}
```
**Martha's perspective:**
- `responsibility`: She feels 100% responsible
- `protective`: She's highly protective (90%)
- `anxiety_level`: Moderate anxiety about parenting
### Other Block
The `other` block contains fields about how the participant views the other participants:
```storybook
relationship ParentChild {
Martha as parent self {
responsibility: 1.0
} other {
dependent: 0.8 // She sees Tommy as 80% dependent
mature_for_age: 0.7 // She thinks he's fairly mature
}
Tommy as child
}
```
### Both Blocks
```storybook
relationship EmployerEmployee {
Martha as employer self {
authority: 0.9
stress: 0.6
} other {
respect: 0.8
trust: 0.85
}
Elena as employee
}
```
**Martha's perspective:**
- **Self**: She has high authority (90%), moderate stress (60%)
- **Other**: She respects Elena (80%), trusts her (85%)
### Asymmetric Relationships
Different participants can have different perspective fields:
```storybook
relationship TeacherStudent {
Gandalf as teacher self {
patience: 0.8
wisdom_to_impart: 1.0
} other {
potential: 0.9
ready_to_learn: 0.6
}
Frodo as student self {
eager_to_learn: 0.7
overwhelmed: 0.5
} other {
admiration: 0.95
intimidated: 0.4
}
bond: 0.85
}
```
**Gandalf's view:**
- He's patient (80%), has much wisdom to share
- Sees Frodo as having high potential but only moderately ready
**Frodo's view:**
- He's eager but overwhelmed
- Deeply admires Gandalf, slightly intimidated
## Shared Fields
Fields declared at the relationship level (not in `self`/`other` blocks) are **shared** among all participants.
```storybook
relationship Friendship {
Martha
Gregory
bond: 0.8 // Shared: mutual bond strength
years_known: 15 // Shared: how long they've known each other
shared_routines: 3 // Shared: number of daily routines
}
```
**Common shared fields:**
- `bond`: Relationship strength (0.0 to 1.0)
- `years_known`: Duration of relationship
- `trust`: Mutual trust level
- `commitment`: Commitment to the relationship
- `compatibility`: How well they get along
## Prose Blocks
Relationships can include prose blocks for narrative context.
```storybook
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.
---
}
}
```
**Common prose tags:**
- `---perspective`: How a participant views the relationship
- `---history`: Background of the relationship
- `---dynamics`: How the relationship functions
- `---notes`: Design or development notes
Note: In this syntax, perspective fields are inside participant blocks (not separate `self`/`other` blocks).
## Complete Examples
### Simple Friendship
```storybook
relationship Friendship {
Martha
NeighborBaker
bond: 0.6
years_known: 10
}
```
### Marriage with Roles
```storybook
relationship Marriage {
Martha as spouse
David as spouse
bond: 0.9
anniversary: "2015-06-20"
children: 2
}
```
### Parent-Child with Perspectives
```storybook
relationship ParentChild {
Martha as parent self {
responsibility: 1.0
protective: 0.9
anxiety_level: 0.6
} other {
dependent: 0.8
mature_for_age: 0.7
}
Tommy as child self {
seeks_independence: 0.7
appreciates_parent: 0.9
} other {
feels_understood: 0.6
wants_more_freedom: 0.8
}
bond: 0.95
years_together: 8
}
```
### Employer-Employee
```storybook
relationship EmployerEmployee {
Martha as employer self {
authority: 0.9
satisfaction_with_employee: 0.85
} other {
respect: 0.8
trust: 0.85
}
Elena as employee self {
job_satisfaction: 0.8
career_growth: 0.7
} other {
respects_boss: 0.9
appreciates_flexibility: 0.95
}
workplace: "Martha's Bakery"
salary: 45000
employment_start: "2023-01-15"
}
```
### Complex Multi-Perspective
```storybook
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.
"I want to be half as good as her someday" -- this quiet
ambition drives everything Elena does.
---
}
bond: 0.85
}
```
### Business Rivalry
```storybook
relationship BakeryRivalry {
Martha {
role: established_baker
aware_of_competition: true
respects_rival: 0.6
---perspective
Martha views the new bakery across town as healthy
competition. She respects their pastry work but knows
her sourdough is unmatched. The rivalry pushes her to
keep innovating.
---
}
RivalBaker {
role: newcomer
wants_to_surpass: true
studies_martha: 0.8
---perspective
The rival baker moved to town specifically because of
Martha's reputation. They study her techniques, buy her
bread to analyze it, and dream of the day a customer
chooses their loaf over Martha's sourdough.
---
}
bond: 0.3
}
```
### Multi-Party Family
```storybook
relationship BakerFamily {
Martha as parent
David as parent
Tommy as child
Elena as child
household: "Baker Residence"
family_bond: 0.95
dinner_time: 18:00
---dynamics
A loving queer family running a bakery together. Martha and
David met at culinary school, married, and adopted Tommy and
Elena. The whole family works at the bakery on weekends.
---
}
```
### Co-Owners Partnership
```storybook
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
}
```
## Participant Types
Participants can be:
1. **Characters**: Most common
2. **Institutions**: Organizations in relationships
3. **Locations**: Less common, but valid (e.g., "GuardianOfPlace")
```storybook
relationship GuildMembership {
Elena as member
BakersGuild as organization
membership_since: "2023-01-01"
standing: "good"
dues_paid: true
}
```
## Field Resolution
When a relationship is resolved, fields are merged:
1. **Relationship shared fields** apply to all participants
2. **Participant `self` blocks** apply to that participant
3. **Participant `other` blocks** describe how that participant views others
**Example:**
```storybook
relationship Example {
Martha as friend self {
loyalty: 0.9
} other {
trust: 0.8
}
Gregory as friend
bond: 0.85
}
```
**Resolution:**
- Martha gets: `loyalty: 0.9` (from self), `trust: 0.8` (towards Gregory, from other), `bond: 0.85` (shared)
- Gregory gets: `bond: 0.85` (shared)
- Relationship gets: `bond: 0.85`
## Validation Rules
1. **At least two participants**: Relationships require ≥2 participants
2. **Participants exist**: All participant names must reference defined entities
3. **Unique participant names**: Each participant appears at most once
4. **Field type consistency**: Fields must have valid value types
5. **No circular relationships**: Avoid infinite relationship chains (warning)
6. **Self/other completeness**: If using `self`/`other`, both blocks should be present (best practice)
## Use Cases
### Social Networks
```storybook
relationship BakerFriendship {
Martha
Gregory
bond: 0.8
}
relationship SupplierPartnership {
Martha
Farmer_Jenkins
bond: 0.7
}
relationship BakeryRivalry {
Martha
RivalBaker
bond: 0.2
competitive: true
}
```
### Family Structures
```storybook
relationship ParentChild {
Martha as parent
Tommy as child
bond: 0.95
}
relationship Siblings {
Tommy as older_sibling
Elena as younger_sibling
bond: 0.85
rivalry: 0.3
}
```
### Power Dynamics
```storybook
relationship Vassalage {
King as lord self {
grants: "protection"
expects: "loyalty"
} other {
trusts: 0.6
}
Knight as vassal self {
swears: "fealty"
expects: "land"
} other {
respects: 0.9
}
oath_date: "1205-03-15"
}
```
### Asymmetric Awareness
```storybook
relationship StalkingVictim {
Stalker as pursuer self {
obsession: 0.95
distance_maintained: 50 // meters
} other {
believes_unnoticed: true
}
Victim as unaware_target self {
awareness: 0.0
}
danger_level: 0.8
}
```
## Best Practices
### 1. Use Descriptive Relationship Names
**Avoid:**
```storybook
relationship R1 { ... }
relationship MarthaGregory { ... }
```
**Prefer:**
```storybook
relationship Friendship { ... }
relationship ParentChild { ... }
relationship MentorApprentice { ... }
```
### 2. Use Roles for Clarity
```storybook
relationship Marriage {
Martha as spouse
David as spouse
}
```
Better than:
```storybook
relationship Marriage {
Martha
David
}
```
### 3. Shared Fields for Mutual Properties
```storybook
relationship Partnership {
Martha
Jane
bond: 0.9 // Mutual bond
years_together: 5 // Shared history
}
```
### 4. Self/Other for Perspectives
```storybook
relationship TeacherStudent {
Teacher as mentor self {
patience: 0.8
} other {
potential: 0.9
}
Student as learner self {
motivation: 0.7
} other {
admiration: 0.95
}
}
```
### 5. Prose Blocks for Rich Context
```storybook
relationship ComplexDynamic {
Martha { ... }
Jane { ... }
---dynamics
Their relationship is characterized by mutual respect but
divergent goals. Martha focuses on traditional bread while Jane
pushes for experimental pastries, creating creative tension.
---
}
```
## Cross-References
- [Characters](./10-characters.md) - Participants are typically characters
- [Institutions](./16-other-declarations.md#institutions) - Institutions can participate
- [Value Types](./18-value-types.md) - Field value types
- [Expression Language](./17-expressions.md) - Querying relationships
## Related Concepts
- **Bidirectional modeling**: `self`/`other` blocks enable asymmetric perspectives
- **Social simulation**: Relationships drive character interactions
- **Narrative depth**: Prose blocks embed storytelling in relationship data
- **Power dynamics**: Roles and perspective fields model hierarchies
- **Emotional bonds**: Bond strength and trust metrics quantify connections