# Schedules and Time - Storybook Language Guide
Comprehensive documentation for the Storybook narrative simulation language

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