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

222
docs/tutorial/05-advanced-behaviors.md Normal file
View File

@@ -0,0 +1,222 @@
# Advanced Behaviors
You have learned the fundamentals of behavior trees. This chapter covers advanced patterns: complex decision hierarchies, modular design with subtrees, and state-driven behavior.
## Deep Decision Trees
Real characters need layered decision-making. Nest selectors and sequences to create rich AI:
```storybook
behavior Baker_DailyAI {
choose daily_activity {
// Morning: Prepare the bakery
then morning_prep {
if(time_is_morning)
then prep_sequence {
LightOven
PrepareDough
StartFirstBatch
}
}
// Day: Serve customers
then day_service {
if(time_is_daytime)
choose service_mode {
then serve_customer {
if(customer_waiting)
GreetCustomer
TakeOrder
PackageItems
CollectPayment
}
then restock {
if(display_low)
FetchFromKitchen
}
CleanCounter
}
}
// Evening: Close up
then evening_close {
if(time_is_evening)
then close_sequence {
TurnOffOvens
CleanKitchen
CountRegister
LockUp
}
}
}
}
```
Each level of nesting refines the decision. The outer `choose` selects the time of day; inner nodes handle the specifics.
## Modular Subtrees
Large behavior trees become unwieldy. Break them into focused subtrees and compose with `include`:
```storybook
// Focused subtree: just baking
behavior Baking_Sourdough {
then sourdough_sequence {
MixDough
KneadDough
FirstRise
ShapeLoaves
}
}
// Focused subtree: just customer service
behavior Service_ServeCustomer {
then service_sequence {
GreetCustomer
TakeOrder
PackageItems
CollectPayment
}
}
// Composition: combine subtrees
behavior Martha_FullDay {
choose activity {
then morning_baking {
if(time_is_morning)
include Baking_Sourdough
include Baking_Pastries
}
then afternoon_sales {
if(time_is_afternoon)
include Service_ServeCustomer
}
CleanWorkstation
}
}
```
Benefits of modular subtrees:
- Each subtree is testable in isolation
- Multiple characters can share subtrees
- Changes propagate automatically
## Conditional Behavior Selection
Use conditions to switch between behavioral modes:
```storybook
behavior SmartBaker {
choose strategy {
// Busy mode when there are many customers
then busy_mode {
if(customer_count > 5 and inventory_sufficient)
choose rush_tactics {
ServeFastOrder
QuickRestock
ExpressBake
}
}
// Careful mode when supplies are low
then careful_mode {
if(inventory_low or special_ingredients_missing)
choose conservation_tactics {
ReducePortions
SubstituteIngredients
OrderEmergencySupply
}
}
// Normal mode otherwise
then normal_mode {
if(customer_count <= 5 and inventory_sufficient)
StandardRoutine
}
}
}
```
## Decorator Combinations
Combine decorators to build sophisticated control patterns:
```storybook
behavior Baker_SpecialRecipe {
// Only when inventory is sufficient
if(has_special_ingredients) {
// Limited to once per hour
cooldown(1h) {
// Must complete within 30 minutes
timeout(30m) {
// Try up to 3 times
retry(3) {
then bake_special {
PrepareSpecialDough
BakeAtPreciseTemperature
}
}
}
}
}
}
```
## Prose Documentation
Add narrative context to complex behaviors with prose blocks:
```storybook
behavior Elena_TrainingSession {
---description
Elena practicing a new recipe under Martha's guidance.
Uses retry decorator for persistence and if for
checking readiness.
---
choose training_strategy {
then practice_supervised {
if(martha_available)
retry(3) {
then attempt_recipe {
ReviewRecipeSteps
MeasureIngredients
MixAndKnead
CheckWithMartha
}
}
}
then practice_solo {
if(not martha_available)
then solo_attempt {
ReviewRecipeNotes
AttemptRecipeFromMemory
TasteTestResult
}
}
}
}
```
## Design Tips
**Prefer shallow trees**: Break deep nesting into subtrees with `include`.
**Name every composite node**: Labels make trees self-documenting.
**Use decorators for control flow**: Timing, repetition, and gating belong in decorators, not in action logic.
**Keep actions atomic**: Each action should do one thing. Complex operations are sequences of simple actions.
## Next Steps
Characters do not exist in isolation. In [Character Relationships](./06-relationships.md), you will model how characters connect to each other -- friendships, rivalries, parent-child bonds, and more.
---
**Reference**: See [Behavior Trees Reference](../reference/11-behavior-trees.md) and [Decorators Reference](../reference/12-decorators.md) for complete syntax.