# NPC Schedule Authoring Guide

The NPC schedule module provides deterministic daily routines for open-world
characters. It is data-driven and can feed AI behavior, pathfinding, editor, and
debug tooling.

## Profiles and Blocks

Create a profile with `defineNpcScheduleProfile`. Profiles contain ordered
blocks with start and end minutes, activity, location, optional weekday or
holiday filters, and optional variation rules. Blocks may cross midnight by
using an end minute lower than the start minute.

Activities cover work, eat, sleep, leisure, travel, socializing, shelter, and
idle. Use `bindNpcScheduleLocations` to validate that each block references an
existing location and that the location allows the block activity.

## Locations

Use `createNpcScheduleLocationRegistry` to register homes, workplaces, taverns,
markets, shelters, and outdoor locations. Locations include world position,
capacity, ownership, allowed activities, and whether they are indoors.

## Evaluation

`evaluateNpcSchedule` selects the active block from current minute, day of week,
holiday id, weather, temperature, and interruption context. It returns the
resolved location, schedule path plan, behavior plan, interruption state, and
next transition minute.

The path plan includes waypoints, destination, arrival minute, and whether the
NPC should wait when arriving early. The behavior plan maps activities to
behavior ids and animation ids for AI integration.

## Variation, Days, and Weather

Variations let a block choose alternate activities or locations with a
deterministic chance. Weekday filters support weekday/weekend schedules, while
holiday ids override normal day rules for special routines.

Harsh weather and extreme cold can redirect NPCs to indoor shelters or home.
Combat and player interaction pause the schedule and record the block to resume.

## Social, Persistence, and LOD

`createScheduleSocialPlan` builds conversation groups when friends are present
at the same location. `serializeNpcScheduleState` and `restoreNpcScheduleState`
persist current block, location, day, minute, and interruption data for
save/load.

`applyNpcScheduleLod` simplifies distant NPCs by skipping complex animation and
teleports offscreen NPCs to their resolved schedule location.

## Tools

`createNpcScheduleDebugView` returns a timeline, current block, path, next
transition, and interruption data for debug overlays.
`createNpcScheduleEditorModel`, `moveNpcScheduleBlock`, and
`assignNpcScheduleBlockLocation` provide the core data operations needed by a
visual schedule editor.
