Sienna Meridian Satterwhite
16deb5d237
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
328 lines
16 KiB
HTML
328 lines
16 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Welcome to Storybook - 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="welcome-to-storybook"><a class="header" href="#welcome-to-storybook">Welcome to Storybook</a></h1>
|
||
<blockquote>
|
||
<p><strong>Bring characters to life with code that reads like stories.</strong></p>
|
||
</blockquote>
|
||
<p>Welcome! This tutorial will guide you through the Storybook language step by step. By the end, you will be able to create rich characters, define complex behaviors, build relationships, and model entire narrative worlds.</p>
|
||
<h2 id="what-you-will-learn"><a class="header" href="#what-you-will-learn">What You Will Learn</a></h2>
|
||
<p>In this tutorial, we follow Martha and her bakery family, using their daily lives to learn each concept:</p>
|
||
<ol>
|
||
<li><strong>Creating Characters</strong> - Define Martha with traits and descriptions</li>
|
||
<li><strong>Your First Behavior Tree</strong> - Give characters decision-making abilities</li>
|
||
<li><strong>Making Characters Act</strong> - Actions, conditions, and decorators</li>
|
||
<li><strong>Advanced Behaviors</strong> - Subtrees, parameters, and complex patterns</li>
|
||
<li><strong>Character Relationships</strong> - Model how characters interact</li>
|
||
<li><strong>Schedules and Time</strong> - Give characters daily routines</li>
|
||
<li><strong>Life Arcs</strong> - Track character development over time</li>
|
||
</ol>
|
||
<h2 id="what-is-storybook"><a class="header" href="#what-is-storybook">What is Storybook?</a></h2>
|
||
<p>Storybook is a domain-specific language (DSL) for narrative simulation. It lets you describe:</p>
|
||
<ul>
|
||
<li><strong>Who</strong> characters are (traits, backstory, species)</li>
|
||
<li><strong>What</strong> they do (behavior trees with decision logic)</li>
|
||
<li><strong>How</strong> they relate to others (relationships with perspectives)</li>
|
||
<li><strong>When</strong> they act (schedules and time-based routines)</li>
|
||
<li><strong>How they change</strong> (life arcs and state machines)</li>
|
||
</ul>
|
||
<p>All of this in syntax designed to be readable and expressive.</p>
|
||
<h2 id="your-first-storybook-file"><a class="header" href="#your-first-storybook-file">Your First Storybook File</a></h2>
|
||
<p>Create a file called <code>hello.sb</code> and add this:</p>
|
||
<pre><code class="language-storybook">character Martha {
|
||
age: 34
|
||
skill_level: 0.95
|
||
|
||
---description
|
||
A master baker who runs the most popular bakery in town,
|
||
known for her sourdough bread and apple pastries.
|
||
---
|
||
}
|
||
</code></pre>
|
||
<p>That is it. You have defined a character with two numeric fields and a prose description block. Let us break it down:</p>
|
||
<ul>
|
||
<li><code>character Martha</code> declares a new character named Martha</li>
|
||
<li><code>{ ... }</code> contains her attributes</li>
|
||
<li><code>age: 34</code> is an integer field</li>
|
||
<li><code>skill_level: 0.95</code> is a floating-point field (0.0 to 1.0)</li>
|
||
<li><code>---description ... ---</code> is a prose block for narrative text</li>
|
||
</ul>
|
||
<h2 id="key-concepts"><a class="header" href="#key-concepts">Key Concepts</a></h2>
|
||
<h3 id="everything-is-a-declaration"><a class="header" href="#everything-is-a-declaration">Everything is a Declaration</a></h3>
|
||
<p>Storybook files contain <strong>declarations</strong> – named definitions of things in your world:</p>
|
||
<pre><code class="language-storybook">character Martha { ... } // A person or creature
|
||
behavior BakeRoutine { ... } // Decision-making logic
|
||
relationship Family { ... } // A connection between entities
|
||
schedule DailyRoutine { ... } // Time-based activities
|
||
life_arc Career { ... } // How someone changes over time
|
||
</code></pre>
|
||
<h3 id="fields-hold-data"><a class="header" href="#fields-hold-data">Fields Hold Data</a></h3>
|
||
<p>Fields use a simple <code>name: value</code> format:</p>
|
||
<pre><code class="language-storybook">age: 34 // Integer
|
||
skill_level: 0.95 // Float
|
||
name: "Martha Baker" // String
|
||
is_open: true // Boolean
|
||
wake_time: 04:30 // Time
|
||
bake_duration: 45m // Duration
|
||
</code></pre>
|
||
<h3 id="prose-blocks-tell-stories"><a class="header" href="#prose-blocks-tell-stories">Prose Blocks Tell Stories</a></h3>
|
||
<p>Prose blocks embed narrative text directly in your definitions:</p>
|
||
<pre><code class="language-storybook">---backstory
|
||
Martha learned to bake from her grandmother, starting at age
|
||
twelve with simple bread recipes. Over the years she mastered
|
||
sourdough, pastries, and specialty cakes, eventually opening
|
||
her own bakery.
|
||
---
|
||
</code></pre>
|
||
<p>You can have multiple prose blocks with different tags (<code>backstory</code>, <code>appearance</code>, <code>personality</code>, etc.) in a single declaration.</p>
|
||
<h2 id="project-structure"><a class="header" href="#project-structure">Project Structure</a></h2>
|
||
<p>A typical Storybook project organizes files into directories:</p>
|
||
<pre><code>my-world/
|
||
schema/
|
||
core_enums.sb // Enum definitions (skill levels, moods, etc.)
|
||
templates.sb // Reusable trait sets
|
||
beings.sb // Species definitions
|
||
world/
|
||
characters/
|
||
martha.sb // Character definitions
|
||
jane.sb
|
||
behaviors/
|
||
baking.sb // Behavior trees
|
||
relationships/
|
||
family.sb // Relationship definitions
|
||
</code></pre>
|
||
<p>Files reference each other using <code>use</code> statements:</p>
|
||
<pre><code class="language-storybook">use schema::core_enums::SkillLevel;
|
||
use schema::beings::Human;
|
||
|
||
character Martha: Human {
|
||
skill_level: expert
|
||
}
|
||
</code></pre>
|
||
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
|
||
<p>Ready to create your first character? Head to <a href="./02-creating-characters.html">Creating Characters</a> to start building Martha in detail.</p>
|
||
<hr />
|
||
<p><strong>Tip</strong>: You do not need to memorize everything now. This tutorial builds concepts gradually, and you can always refer back to the <a href="../reference/09-overview.html">Reference Guide</a> for precise syntax details.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="../index.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="../tutorial/02-creating-characters.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="../index.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="../tutorial/02-creating-characters.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>
|