# V2 NPC Schedule Data Format

`NPCScheduleDataFormat.V2` defines the authored daily routine data consumed by
later schedule execution, pathfinding, interruption, persistence, and debug
systems. It is intentionally data-only: this layer validates what an NPC should
do and where each block binds, while behavior dispatch belongs to later schedule
runtime tasks.

## Runtime Surface

- `FV2NPCScheduleTimeOfDay` stores hour/minute values and converts them to
  minutes from midnight.
- `FV2NPCScheduleBlock` stores a stable block id, activity type, concrete
  activity tag, location id, behavior tag, interaction tag, start/end times,
  priority, interruption policy, reservation policy, and authoring tags.
- `FV2NPCScheduleDefinition` stores schedule id, NPC id, day pattern id,
  full-day coverage policy, and ordered schedule blocks.
- `FV2NPCScheduleValidationIssue` reports field-level authoring issues with
  blocking/non-blocking severity.
- `FV2NPCScheduleValidationResult` reports block count, covered minutes, gap
  minutes, and all validation issues.

## Time Block Rules

1. Times are represented as local authored time of day from `00:00` through
   `23:59`.
2. Blocks use half-open ranges: start minute is included and end minute is
   excluded.
3. A block whose end time is earlier than its start time wraps midnight, such as
   `20:00` to `06:00` for sleep.
4. Equal start and end times are invalid because full-day coverage should be
   explicit.
5. Schedule definitions can require all `1440` minutes to be covered. The
   example daily schedule covers breakfast at home from `06:00` to `08:00`, work
   at the shop from `08:00` to `17:00`, tavern visiting from `17:00` to `20:00`,
   and sleep at home from `20:00` to `06:00`.

## Validation Rules

1. Schedules require `ScheduleId`, `NPCId`, and at least one block.
2. Blocks require unique `BlockId` values.
3. Blocks require a non-`Invalid` activity type and a concrete `ActivityTag`.
4. Blocks require a target `LocationId`; later location binding resolves that id
   into owned homes, workplaces, tavern seats, or other authored anchors.
5. Block priority cannot be negative.
6. Overlapping covered minutes are blocking validation issues.
7. Missing full-day coverage is blocking when `bRequireFullDayCoverage` is true
   and non-blocking when the schedule explicitly allows idle gaps.

## Validation Commands

Run these targeted checks when touching NPC schedule data:

```bash
python3 V2/ue/Tools/check-v2-npc-schedule-data-format.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/NPC/NPCScheduleDataFormat_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-npc-schedule-data-format.py
```