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:

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:

character Baker: Human {
    uses schedule: SimpleBaker
}

For multiple schedules:

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

Temporal Constraints

Blocks can be restricted to specific times using temporal constraints:

Season Constraints

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

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:

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:

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 extends

Schedules can extend other schedules, inheriting and overriding blocks:

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

schedule EarlyBaker extends 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:

schedule MasterBaker extends 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:

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

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