storybook/docs/tutorial/01-welcome.md

# Welcome to Storybook

> **Bring characters to life with code that reads like stories.**

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.

## What You Will Learn

In this tutorial, we follow Martha and her bakery family, using their daily lives to learn each concept:

1. **Creating Characters** - Define Martha with traits and descriptions
2. **Your First Behavior Tree** - Give characters decision-making abilities
3. **Making Characters Act** - Actions, conditions, and decorators
4. **Advanced Behaviors** - Subtrees, parameters, and complex patterns
5. **Character Relationships** - Model how characters interact
6. **Schedules and Time** - Give characters daily routines
7. **Life Arcs** - Track character development over time

## What is Storybook?

Storybook is a domain-specific language (DSL) for narrative simulation. It lets you describe:

- **Who** characters are (traits, backstory, species)
- **What** they do (behavior trees with decision logic)
- **How** they relate to others (relationships with perspectives)
- **When** they act (schedules and time-based routines)
- **How they change** (life arcs and state machines)

All of this in syntax designed to be readable and expressive.

## Your First Storybook File

Create a file called `hello.sb` and add this:

```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.
    ---
}
```

That is it. You have defined a character with two numeric fields and a prose description block. Let us break it down:

- `character Martha` declares a new character named Martha
- `{ ... }` contains her attributes
- `age: 34` is an integer field
- `skill_level: 0.95` is a floating-point field (0.0 to 1.0)
- `---description ... ---` is a prose block for narrative text

## Key Concepts

### Everything is a Declaration

Storybook files contain **declarations** -- named definitions of things in your world:

```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
```

### Fields Hold Data

Fields use a simple `name: value` format:

```storybook
age: 34                  // Number
skill_level: 0.95        // Decimal
name: "Martha Baker"     // Text
is_open: true            // Boolean
wake_time: 04:30         // Time
bake_duration: 45m       // Duration
```

### Prose Blocks Tell Stories

Prose blocks embed narrative text directly in your definitions:

```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.
---
```

You can have multiple prose blocks with different tags (`backstory`, `appearance`, `personality`, etc.) in a single declaration.

## Project Structure

A typical Storybook project organizes files into directories:

```
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
```

Files reference each other using `use` statements:

```storybook
use schema::core_enums::SkillLevel;
use schema::beings::Human;

character Martha: Human {
    skill_level: expert
}
```

## Next Steps

Ready to create your first character? Head to [Creating Characters](./02-creating-characters.md) to start building Martha in detail.

---

**Tip**: You do not need to memorize everything now. This tutorial builds concepts gradually, and you can always refer back to the [Reference Guide](../reference/09-overview.md) for precise syntax details.