storybook/docs/tutorial/06-relationships.md

Character Relationships

Characters exist in a web of connections -- friendships, rivalries, parent-child bonds, and complex power dynamics. In Storybook, relationships are first-class declarations that capture these connections with nuance and perspective.

Basic Relationships

The simplest relationship connects two characters with shared fields:

relationship MarthaAndEmma {
    Martha as parent {}
    Emma as child {}

    bond: 0.95
    type: "parent_child"
}

This says Martha and Emma share a relationship with a bond strength of 0.95 (very close). The bond field is shared -- it applies equally to both participants.

Adding Roles

Roles label each participant's function in the relationship:

relationship ParentChild {
    Martha as parent
    Emma as child

    bond: 0.95
    guardianship: true
}

The as parent and as child labels clarify who plays which role. Roles are descriptive -- you can use any name that makes sense.

Perspectives: Self and Other

Real relationships are not symmetric. How one person sees the relationship may differ from how the other sees it. Storybook handles this with self and other blocks:

relationship MentorApprentice {
    Martha as mentor self {
        patience: 0.8
        investment_in_student: 0.9
    } other {
        sees_potential: 0.85
        frustration_level: 0.2
    }

    Elena as apprentice self {
        dedication: 0.9
        overwhelmed: 0.4
    } other {
        admiration: 0.95
        desire_to_impress: 0.9
    }

    bond: 0.85
}

Reading this:

• Martha's self view: She feels patient (80%), highly invested in her student
• Martha's view of Elena (other): Sees high potential (85%) with low frustration (20%)
• Elena's self view: Dedicated (90%) but sometimes overwhelmed (40%)
• Elena's view of Martha (other): Deep admiration (95%), strong desire to impress (90%)
• Shared: Their bond strength is 0.85

Prose in Relationships

Relationships can include narrative descriptions for each participant:

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. He worries
        about what would happen if she ever retired.
        ---
    }

    bond: 0.7
}

Multi-Party Relationships

Relationships can involve more than two participants:

relationship BakerFamily {
    Martha as parent
    Jane as parent
    Emma as child

    household: "Baker Residence"
    family_bond: 0.95
    dinner_time: 18:00

    ---dynamics
    A loving family running a bakery together. Martha handles
    the bread, Jane manages pastries, and Emma helps out on
    weekends while learning the craft.
    ---
}

Asymmetric Awareness

Relationships can model situations where one party does not know the relationship exists:

relationship BossAndNewHire {
    Martha {
        role: boss
        aware_of_struggles: false
        expects: high_quality_work

        ---perspective
        Martha sees the new hire as competent and expects them
        to learn the bakery routines quickly. She has no idea
        they are struggling with the early morning schedule.
        ---
    }

    NewHire {
        role: employee
        intimidated: 0.8
        hides_struggles: true

        ---perspective
        The new hire is in awe of Martha's skill but terrified
        of disappointing her. They arrive thirty minutes early
        every day to practice techniques before she gets in.
        ---
    }

    bond: 0.4
}

Institutional Relationships

Institutions can participate in relationships too:

relationship GuildMembership {
    Martha as member
    BakersGuild as organization

    membership_since: "2015-01-01"
    standing: "good"
    dues_paid: true
}

Building a Relationship Web

Multiple relationships create a rich social network:

relationship Marriage {
    Martha as spouse
    Jane as spouse
    bond: 0.9
}

relationship MentorApprentice {
    Martha as mentor
    Elena as apprentice
    bond: 0.85
}

relationship RegularCustomer {
    Martha as shopkeeper
    Gregory as customer
    bond: 0.7
}

relationship Colleagues {
    Martha as peer
    NeighborBaker as peer
    bond: 0.5
    competitive: true
}

Next Steps

Characters have traits, behaviors, and relationships. In Schedules and Time, you will give them daily routines and time-based activities.

---

Reference: For complete relationship syntax, see the Relationships Reference.