storybook/docs/tutorial/07-schedules.md

# Schedules and Time

Characters live in time. A baker wakes before dawn to prepare dough; a guard patrols during the day shift; an innkeeper serves customers until late. Schedules define these time-based routines.

## Basic Schedules

A schedule contains time blocks, each with a time range and an action:

```storybook
schedule SimpleBaker {
    block morning_prep {
        05:00 - 08:00
        action: baking::prepare_dough
    }

    block sales {
        08:00 - 14:00
        action: baking::serve_customers
    }

    block cleanup {
        14:00 - 15:00
        action: baking::close_shop
    }
}
```

Time ranges use 24-hour clock format (`HH:MM`). The `action` field links to a behavior tree that drives the character's activity during that block.

## Named Blocks

Blocks can have names (like `morning_prep` above). Named blocks are important for schedule composition -- they allow child schedules to override specific blocks by name.

## Linking Schedules to Characters

Characters use the `uses schedule` clause:

```storybook
character Baker: Human {
    uses schedule: SimpleBaker
}
```

For multiple schedules:

```storybook
character Innkeeper: Human {
    uses schedules: [WeekdaySchedule, WeekendSchedule]
}
```

## Temporal Constraints

Blocks can be restricted to specific times using temporal constraints:

### Season Constraints

```storybook
schedule SeasonalBaker {
    block summer_hours {
        06:00 - 20:00
        action: baking::long_shift
        on season summer
    }

    block winter_hours {
        07:00 - 18:00
        action: baking::short_shift
        on season winter
    }
}
```

### Day of Week Constraints

```storybook
schedule WeeklyPattern {
    block weekday_work {
        09:00 - 17:00
        action: work::standard
        on day monday
    }

    block weekend_rest {
        10:00 - 16:00
        action: leisure::relax
        on day saturday
    }
}
```

Temporal constraint values (like `summer` or `monday`) reference enums defined in your storybook:

```storybook
enum Season { spring, summer, fall, winter }
enum DayOfWeek { monday, tuesday, wednesday, thursday, friday, saturday, sunday }
```

## Recurring Events

Use `recurs` to define events that repeat on a schedule:

```storybook
schedule MarketSchedule {
    // Regular daily hours
    block work {
        08:00 - 17:00
        action: shop::regular_sales
    }

    // Market day every Saturday
    recurs MarketDay on day saturday {
        block setup {
            06:00 - 08:00
            action: market::setup_stall
        }

        block busy_market {
            08:00 - 18:00
            action: market::busy_sales
        }

        block teardown {
            18:00 - 20:00
            action: market::pack_up
        }
    }
}
```

Recurrences take priority over regular blocks. On Saturdays, the `MarketDay` blocks replace the regular `work` block.

## Schedule Composition with modifies

Schedules can extend other schedules, inheriting and overriding blocks:

```storybook
schedule BaseShopkeeper {
    block open {
        09:00 - 17:00
        action: shop::standard_hours
    }
}

schedule EarlyBaker modifies BaseShopkeeper {
    block open {
        05:00 - 13:00
        action: baking::early_shift
    }
}
```

The `EarlyBaker` schedule overrides the `open` block by name -- same block name, different hours. Any blocks not overridden are inherited unchanged.

You can chain extensions:

```storybook
schedule MasterBaker modifies EarlyBaker {
    block open {
        03:00 - 11:00
        action: baking::master_work
    }

    block teaching {
        14:00 - 16:00
        action: baking::teach_apprentice
    }
}
```

`MasterBaker` overrides `open` again and adds a new `teaching` block.

## Overnight Blocks

Time ranges can span midnight:

```storybook
schedule NightGuard {
    block night_patrol {
        22:00 - 06:00
        action: security::patrol
    }
}
```

The system interprets this as 22:00 to midnight on day one, then midnight to 06:00 on day two.

## A Complete Schedule Example

```storybook
schedule MasterBaker_FullYear {
    // Daily base
    block prep {
        04:00 - 06:00
        action: baking::prepare
    }

    block baking {
        06:00 - 10:00
        action: baking::bake
    }

    block sales {
        10:00 - 16:00
        action: baking::serve
    }

    block cleanup {
        16:00 - 17:00
        action: baking::clean
    }

    // Summer extended hours
    block summer_sales {
        10:00 - 20:00
        action: baking::busy_summer
        on season summer
    }

    // Weekly market
    recurs MarketDay on day saturday {
        block market_prep {
            02:00 - 04:00
            action: baking::market_prep
        }

        block market_sales {
            08:00 - 18:00
            action: baking::market_rush
        }
    }

    // Annual harvest festival
    recurs HarvestFestival on dates "Sep 20" .. "Sep 25" {
        block festival {
            06:00 - 23:00
            action: baking::festival_mode
        }
    }
}
```

## Next Steps

Characters now have traits, behaviors, relationships, and schedules. In [Life Arcs](./08-life-arcs.md), you will learn how to model character development over time -- how they grow, change, and evolve through different phases of life.

---

**Reference**: For complete schedule syntax, see the [Schedules Reference](../reference/14-schedules.md).