Files
storybook/docs/book/advanced/20-patterns.html
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

580 lines
22 KiB
HTML

<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Design Patterns - Storybook Language Guide</title>
<!-- Custom HTML head -->
<meta name="description" content="Comprehensive documentation for the Storybook narrative simulation language">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../highlight.css">
<link rel="stylesheet" href="../tomorrow-night.css">
<link rel="stylesheet" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root to javascript -->
<script>
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Storybook Language Guide</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/r3t-studios/storybook" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="design-patterns"><a class="header" href="#design-patterns">Design Patterns</a></h1>
<p>This chapter presents proven patterns for structuring Storybook projects. These patterns have emerged from building complex narrative simulations and represent best practices for maintainability, reuse, and clarity.</p>
<h2 id="behavior-tree-patterns"><a class="header" href="#behavior-tree-patterns">Behavior Tree Patterns</a></h2>
<h3 id="priority-fallback-chain"><a class="header" href="#priority-fallback-chain">Priority Fallback Chain</a></h3>
<p>Use a selector to try increasingly desperate options:</p>
<pre><code class="language-storybook">behavior Survival {
choose survival_priority {
then optimal {
if(health &gt; 70 and has_supplies)
ProceedNormally
}
then cautious {
if(health &gt; 30)
ProceedCarefully
}
then desperate {
if(health &gt; 10)
SeekHelp
}
LastResortPanic
}
}
</code></pre>
<p>The tree naturally degrades: first tries the best option, then falls back through progressively worse alternatives.</p>
<h3 id="conditional-behavior-switching"><a class="header" href="#conditional-behavior-switching">Conditional Behavior Switching</a></h3>
<p>Use guards at the top level to switch between behavioral modes:</p>
<pre><code class="language-storybook">behavior ModeSwitcher {
choose mode {
if(is_combat_mode) {
include CombatBehavior
}
if(is_exploration_mode) {
include ExplorationBehavior
}
if(is_social_mode) {
include SocialBehavior
}
include IdleBehavior
}
}
</code></pre>
<h3 id="composite-subtree-pattern"><a class="header" href="#composite-subtree-pattern">Composite Subtree Pattern</a></h3>
<p>Break complex behaviors into focused, reusable subtrees:</p>
<pre><code class="language-storybook">// Atomic subtrees
behavior Navigate { then nav { PlanPath, FollowPath } }
behavior Interact { then talk { Approach, Greet, Converse } }
behavior Trade { then exchange { ShowGoods, Negotiate, Exchange } }
// Composed behavior
behavior Merchant_AI {
choose activity {
then serve_customer {
if(customer_present)
include Interact
include Trade
}
then travel_to_market {
if(is_market_day)
include Navigate
}
Idle
}
}
</code></pre>
<h3 id="repeating-patrol-with-interrupts"><a class="header" href="#repeating-patrol-with-interrupts">Repeating Patrol with Interrupts</a></h3>
<p>Use a repeating patrol that can be interrupted by higher-priority events:</p>
<pre><code class="language-storybook">character Guard {
uses behaviors: [
{
tree: GuardCombat
when: threat_detected
priority: high
},
{
tree: GuardPatrol
priority: normal
}
]
}
behavior GuardPatrol {
repeat {
then patrol_loop {
MoveTo(destination: "Waypoint1")
WaitAndScan(duration: 5s)
MoveTo(destination: "Waypoint2")
WaitAndScan(duration: 5s)
}
}
}
</code></pre>
<p>The combat behavior preempts patrol when threats appear, then patrol resumes.</p>
<h2 id="character-architecture-patterns"><a class="header" href="#character-architecture-patterns">Character Architecture Patterns</a></h2>
<h3 id="species--templates-composition"><a class="header" href="#species--templates-composition">Species + Templates Composition</a></h3>
<p>Use species for identity and templates for capabilities:</p>
<pre><code class="language-storybook">// Species: What they ARE
species Human { lifespan: 70 }
species Elf { lifespan: 1000 }
// Templates: What they HAVE
template Warrior { strength: 10..20, weapon_skill: 0.5..1.0 }
template Scholar { intelligence: 15..20, books_read: 50..500 }
template Leader { charisma: 12..18, followers: 5..50 }
// Characters: Combine both
character Aragorn: Human from Warrior, Leader {
strength: 18
charisma: 17
}
character Elrond: Elf from Scholar, Leader {
intelligence: 20
charisma: 18
}
</code></pre>
<h3 id="strict-templates-for-schema-enforcement"><a class="header" href="#strict-templates-for-schema-enforcement">Strict Templates for Schema Enforcement</a></h3>
<p>Use strict templates when you need controlled, uniform entities:</p>
<pre><code class="language-storybook">template RecipeCard strict {
recipe_name: string
difficulty: Difficulty
prep_time_minutes: 10..180
}
// This works:
character SourdoughRecipe from RecipeCard {
recipe_name: "Classic Sourdough"
difficulty: intermediate
prep_time_minutes: 120
}
// This would error (extra field not allowed):
// character BadRecipe from RecipeCard {
// recipe_name: "Mystery Bread"
// difficulty: easy
// favorite_color: "blue" // Error!
// }
</code></pre>
<h3 id="template-inheritance-chains"><a class="header" href="#template-inheritance-chains">Template Inheritance Chains</a></h3>
<p>Build template hierarchies for progressive specialization:</p>
<pre><code class="language-storybook">template Worker {
skill_level: 0.0..1.0
wage: 10..50
}
template SkilledWorker {
include Worker
specialization: "general"
tool_proficiency: 0.5..1.0
}
template MasterCraftsman {
include SkilledWorker
can_teach: true
reputation: 0.7..1.0
}
</code></pre>
<h2 id="relationship-patterns"><a class="header" href="#relationship-patterns">Relationship Patterns</a></h2>
<h3 id="bidirectional-perspective"><a class="header" href="#bidirectional-perspective">Bidirectional Perspective</a></h3>
<p>Model relationships where each side sees things differently:</p>
<pre><code class="language-storybook">relationship MentorApprentice {
Master as mentor self {
patience: 0.7
investment_in_student: 0.9
} other {
sees_potential: 0.8
frustration_level: 0.3
}
Student as apprentice self {
dedication: 0.8
overwhelmed: 0.4
} other {
respect: 0.95
desire_to_impress: 0.9
}
bond: 0.75
years_together: 3
}
</code></pre>
<h3 id="power-dynamic-pattern"><a class="header" href="#power-dynamic-pattern">Power Dynamic Pattern</a></h3>
<p>Model unequal power relationships explicitly:</p>
<pre><code class="language-storybook">relationship Vassalage {
King as lord self {
authority: 1.0
grants: "protection"
} other {
trusts_vassal: 0.6
}
Knight as vassal self {
loyalty: 0.9
ambition: 0.4
} other {
respects_lord: 0.8
fears_lord: 0.3
}
bond: 0.7
}
</code></pre>
<h3 id="relationship-network"><a class="header" href="#relationship-network">Relationship Network</a></h3>
<p>Build social graphs with multiple overlapping relationships:</p>
<pre><code class="language-storybook">// Family
relationship BakerMarriage { Martha as spouse, David as spouse, bond: 0.9 }
relationship BakerParenting { Martha as parent, Tommy as child, bond: 0.95 }
// Professional
relationship BakerEmployment { Martha as employer, Elena as employee, bond: 0.8 }
relationship GuildMembership { Martha as member, BakersGuild as org }
// Social
relationship BakerFriendship { Martha, Neighbor, bond: 0.6 }
</code></pre>
<h2 id="schedule-patterns"><a class="header" href="#schedule-patterns">Schedule Patterns</a></h2>
<h3 id="base-schedule-with-specializations"><a class="header" href="#base-schedule-with-specializations">Base Schedule with Specializations</a></h3>
<pre><code class="language-storybook">schedule BaseWorker {
block work { 09:00 - 17:00, action: work::standard }
block lunch { 12:00 - 13:00, action: social::lunch }
}
schedule EarlyBird extends BaseWorker {
block work { 05:00 - 13:00, action: work::early_shift }
block lunch { 11:00 - 12:00, action: social::lunch }
}
schedule NightOwl extends BaseWorker {
block work { 14:00 - 22:00, action: work::late_shift }
block lunch { 18:00 - 19:00, action: social::dinner }
}
</code></pre>
<h3 id="seasonal-variation"><a class="header" href="#seasonal-variation">Seasonal Variation</a></h3>
<pre><code class="language-storybook">schedule FarmSchedule {
block spring_work {
06:00 - 18:00
action: farming::plant
on season spring
}
block summer_work {
05:00 - 20:00
action: farming::tend
on season summer
}
block fall_work {
06:00 - 20:00
action: farming::harvest
on season fall
}
block winter_work {
08:00 - 16:00
action: farming::maintain
on season winter
}
}
</code></pre>
<h2 id="life-arc-patterns"><a class="header" href="#life-arc-patterns">Life Arc Patterns</a></h2>
<h3 id="progressive-development"><a class="header" href="#progressive-development">Progressive Development</a></h3>
<pre><code class="language-storybook">life_arc CareerProgression {
state novice {
on enter { Character.title: "Apprentice" }
on experience &gt; 100 -&gt; intermediate
}
state intermediate {
on enter { Character.title: "Journeyman" }
on experience &gt; 500 -&gt; expert
}
state expert {
on enter { Character.title: "Master", Character.can_teach: true }
}
}
</code></pre>
<h3 id="emotional-state-machine"><a class="header" href="#emotional-state-machine">Emotional State Machine</a></h3>
<pre><code class="language-storybook">life_arc MoodSystem {
state neutral {
on provoked -&gt; angry
on complimented -&gt; happy
on tired -&gt; sleepy
}
state angry {
on enter { Character.aggression: 0.9 }
on calmed_down -&gt; neutral
on escalated -&gt; furious
}
state furious {
on enter { Character.aggression: 1.0 }
on timeout_elapsed -&gt; angry
}
state happy {
on enter { Character.gives_discounts: true }
on insulted -&gt; neutral
}
state sleepy {
on enter { Character.responsiveness: 0.2 }
on woke_up -&gt; neutral
}
}
</code></pre>
<h2 id="project-organization-patterns"><a class="header" href="#project-organization-patterns">Project Organization Patterns</a></h2>
<h3 id="schema--world-separation"><a class="header" href="#schema--world-separation">Schema / World Separation</a></h3>
<p>Keep type definitions separate from instance data:</p>
<pre><code>my-project/
schema/ # Types and templates (reusable)
core_enums.sb
templates.sb
beings.sb
world/ # Instances (specific to this story)
characters/
behaviors/
relationships/
locations/
</code></pre>
<h3 id="module-per-domain"><a class="header" href="#module-per-domain">Module per Domain</a></h3>
<p>Group related declarations together:</p>
<pre><code>world/
characters/
heroes.sb # All hero characters
villains.sb # All villain characters
npcs.sb # Background characters
behaviors/
combat.sb # Combat behaviors
social.sb # Social behaviors
exploration.sb # Exploration behaviors
</code></pre>
<h2 id="anti-patterns-to-avoid"><a class="header" href="#anti-patterns-to-avoid">Anti-Patterns to Avoid</a></h2>
<p><strong>Deep nesting</strong>: More than 4-5 levels of behavior tree nesting is hard to read. Use <code>include</code> to flatten.</p>
<p><strong>God behaviors</strong>: One massive behavior tree doing everything. Break it into focused subtrees.</p>
<p><strong>Deep species hierarchies</strong>: More than 2-3 levels of species <code>includes</code> is rarely needed. Use templates for variation.</p>
<p><strong>Duplicated logic</strong>: If two behaviors share logic, extract it into a shared subtree.</p>
<p><strong>Unnamed nodes</strong>: Always label composite nodes in behavior trees for readability.</p>
<h2 id="cross-references"><a class="header" href="#cross-references">Cross-References</a></h2>
<ul>
<li><a href="../reference/11-behavior-trees.html">Behavior Trees</a> - Complete behavior syntax</li>
<li><a href="../reference/10-characters.html">Characters</a> - Character architecture</li>
<li><a href="../reference/15-relationships.html">Relationships</a> - Relationship modeling</li>
<li><a href="../reference/14-schedules.html">Schedules</a> - Schedule composition</li>
<li><a href="../reference/13-life-arcs.html">Life Arcs</a> - State machine patterns</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../reference/19-validation.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../advanced/21-sbir-format.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../reference/19-validation.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../advanced/21-sbir-format.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<!-- Livereload script (if served using the cli tool) -->
<script>
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
const socket = new WebSocket(wsAddress);
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload();
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>