studio/storybook
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ea83433e939343e12594aef7f542bf4cd51af57b
storybook/docs/reference/15-relationships.md
Sienna Meridian Satterwhite 16deb5d237 release: Storybook v0.2.0 - Major syntax and features update 
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
2026-02-13 21:52:03 +00:00

16 KiB
Raw Blame History

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

<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

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

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

ParticipantName as role_name

Examples

relationship Marriage {
    Martha as spouse
    David as spouse

    bond: 0.9
    anniversary: "2015-06-20"
}

relationship ParentChild {
    Martha as parent
    Tommy as child

    bond: 0.95
    guardianship: true
}

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

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:

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:

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

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:

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.

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.

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

relationship Friendship {
    Martha
    NeighborBaker

    bond: 0.6
    years_known: 10
}

Marriage with Roles

relationship Marriage {
    Martha as spouse
    David as spouse

    bond: 0.9
    anniversary: "2015-06-20"
    children: 2
}

Parent-Child with Perspectives

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

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

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

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

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

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")
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:

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

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

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

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

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:

relationship R1 { ... }
relationship MarthaGregory { ... }

Prefer:

relationship Friendship { ... }
relationship ParentChild { ... }
relationship MentorApprentice { ... }

2. Use Roles for Clarity

relationship Marriage {
    Martha as spouse
    David as spouse
}

Better than:

relationship Marriage {
    Martha
    David
}

3. Shared Fields for Mutual Properties

relationship Partnership {
    Martha
    Jane

    bond: 0.9           // Mutual bond
    years_together: 5   // Shared history
}

4. Self/Other for Perspectives

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

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

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
Reference in New Issue View Git Blame Copy Permalink