# V2 NPC Schedule Authoring Guide

This guide is the author-facing workflow for Phase 72 NPC schedules. It ties the
daily schedule data format to execution, pathfinding, activity behavior,
location binding, interruptions, variations, calendar/weather/social rules,
persistence, debugging, editor tooling, and schedule LOD.

## Source Of Truth

- Data format contract:
  [NPCScheduleDataFormat_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleDataFormat_V2_Contract.json)
- Execution contract:
  [NPCScheduleExecutionEngine_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleExecutionEngine_V2_Contract.json)
- Pathfinding contract:
  [NPCSchedulePathfinding_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCSchedulePathfinding_V2_Contract.json)
- Activity behavior contract:
  [NPCScheduleActivityBehavior_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleActivityBehavior_V2_Contract.json)
- Location binding contract:
  [NPCScheduleLocationBinding_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleLocationBinding_V2_Contract.json)
- Interruption contract:
  [NPCScheduleInterruption_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleInterruption_V2_Contract.json)
- Variation contract:
  [NPCScheduleVariation_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleVariation_V2_Contract.json)
- Day-of-week contract:
  [NPCScheduleDayOfWeek_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleDayOfWeek_V2_Contract.json)
- Weather response contract:
  [NPCScheduleWeatherResponse_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleWeatherResponse_V2_Contract.json)
- Social interaction contract:
  [NPCScheduleSocialInteraction_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleSocialInteraction_V2_Contract.json)
- Persistence contract:
  [NPCSchedulePersistence_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCSchedulePersistence_V2_Contract.json)
- Debug visualization contract:
  [NPCScheduleDebugVisualization_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleDebugVisualization_V2_Contract.json)
- Editor contract:
  [NPCScheduleEditor_V2_Contract.json](../../ue/Content/V2/Editor/NPCScheduleEditor/NPCScheduleEditor_V2_Contract.json)
- LOD contract:
  [NPCScheduleLOD_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleLOD_V2_Contract.json)
- Authoring guide contract:
  [NPCScheduleAuthoringGuide_V2_Contract.json](../../ue/Content/V2/Gameplay/NPC/NPCScheduleAuthoringGuide_V2_Contract.json)

## Schedule Identity And Blocks

Every schedule is an `FV2NPCScheduleDefinition` with stable ids. Use predictable
stable id prefixes so saves, analytics, tests, and editor selections remain
durable:

| Artifact        | Prefix               | Example                          |
| --------------- | -------------------- | -------------------------------- |
| Schedule        | `schedule.`          | `schedule.npc.merchant.daily.v1` |
| NPC             | `npc.`               | `npc.merchant.asha`              |
| Block           | `block.`             | `block.work.shop`                |
| Location        | `location.`          | `location.shop.counter`          |
| Activity tag    | `Schedule.Activity.` | `Schedule.Activity.WorkShop`     |
| Behavior tag    | `Behavior.Schedule.` | `Behavior.Schedule.WorkCounter`  |
| Interaction tag | `Interaction.`       | `Interaction.Workstation`        |

Each `FV2NPCScheduleBlock` needs `BlockId`, `ActivityType`, `ActivityTag`,
`LocationId`, `BehaviorTag`, `InteractionTag`, `StartTime`, `EndTime`, and
priority. Do not reuse block ids across one schedule, and do not encode a
temporary ordering into ids.

## Time Coverage And Transitions

Schedules that set `bRequireFullDayCoverage` must cover all 1440 minutes without
gaps or overlaps. Use explicit overnight blocks for sleep or travel that wraps
midnight. `ValidateNPCScheduleDefinition` is the gate for missing ids, invalid
time ranges, duplicate blocks, coverage gaps, overlaps, and invalid priorities.

Execution uses `EvaluateNPCScheduleExecution` to select the active block,
minutes until transition, and optional idle fallback. Author transitions so the
next block has enough lead time for pathfinding and early-arrival waits.

## Locations Pathfinding And Activity Behavior

Every `LocationId` used by a schedule block must resolve through location
binding before runtime use. `EvaluateNPCScheduleLocationBinding` verifies
schedule location ids against the authored registry and rejects missing
locations.

`EvaluateNPCSchedulePathfinding` compares the NPC current location with the
active or next transition destination. It should emit movement for NPCs that are
not at the schedule location, wait when arriving early, and suppress navigation
only when the caller explicitly requests a dry run.

`EvaluateNPCScheduleActivityBehavior` is only valid after the NPC is at the
target location. Activity behavior maps schedule activities to concrete steps
such as reservation, station work, seating, sleep, socializing, idling, or
custom animation playback.

## Variations Day Weather And Social Rules

Use schedule variation for deterministic replacement blocks, not for ad hoc
runtime edits. Variation rules should keep stable block ids where save/load or
analytics need continuity.

Day-of-week patterns choose replacement schedules for weekdays, weekends, market
days, or authored holidays. Weather response rules replace or suppress blocks
when rain, storms, heat, cold, or other conditions make the base schedule
inappropriate.

Social interaction rules should name participants, friendship requirements,
shared locations, animation choices, and command suppression clearly. They must
not create phantom participants or move friends into locations that the schedule
system cannot bind.

## Interruptions Persistence Debugging Editor And LOD

Interruptions pause or replace the active block for high-priority events. Keep
interruption ids stable, record the interrupted block, and define whether the
NPC resumes afterward.

Persistence captures the active block, saved time, schedule-correct location,
interruption state, day seed, weather id, and command suppression flags. A
loaded NPC should resume the same schedule state and appear at the correct
location for the saved time.

Debug visualization should show timeline segments, current block, planned path,
and next transition markers. Use the schedule editor for visual timeline review,
drag-drop block moves, and location assignment; validate overlap and invalid
input before accepting edits.

Schedule LOD keeps distant NPCs deterministic by reusing the same pathfinding
target, teleporting distant NPCs to the schedule location instead of walking,
and skipping complex activity animations.

## Authoring Workflow

1. Start from an existing valid `FV2NPCScheduleDefinition` or create one with
   stable `schedule.`, `npc.`, `block.`, and `location.` ids.
2. Author full-day block coverage first, then add activity, behavior, and
   interaction tags.
3. Bind every location through the location registry before adding weather,
   day-of-week, social, or variation rules.
4. Run the data, execution, pathfinding, activity behavior, and location binding
   checks before layering interruptions or persistence.
5. Add variation, day, weather, and social rules only after the base daily
   schedule validates.
6. Review the schedule in debug visualization and the schedule editor.
7. Validate save/load and LOD behavior for representative near and distant NPC
   positions.
8. Include the relevant checker output in content review when changing schedule
   data, runtime rules, editor tooling, or authoring docs.

## Review Checklist

Before content review, confirm:

- Schedule, NPC, block, activity, behavior, interaction, and location ids use
  stable id prefixes.
- `FV2NPCScheduleDefinition` contains no duplicate block ids.
- Full-day schedules cover 1440 minutes with no overlaps.
- Every block has a location that passes location binding.
- Pathfinding reaches the active or transition destination with sensible travel
  and wait timing.
- Activity behavior is only expected to run at the target location.
- Variation, day-of-week, weather, and social rules preserve schedule validity.
- Interruption and persistence behavior restore the exact active block and
  correct location.
- Debug visualization and schedule editor output agree on current block, next
  transition, and edited block ranges.
- Schedule LOD teleports distant NPCs and skips complex animations while keeping
  the same schedule target.

## Validation Commands

Run these commands after changing NPC schedule docs, schedules, runtime rules,
editor tooling, or authoring guidance:

```bash
python3 V2/ue/Tools/check-v2-npc-schedule-authoring-guide.py
python3 V2/ue/Tools/check-v2-npc-schedule-data-format.py
python3 V2/ue/Tools/check-v2-npc-schedule-execution-engine.py
python3 V2/ue/Tools/check-v2-npc-schedule-pathfinding.py
python3 V2/ue/Tools/check-v2-npc-schedule-activity-behavior.py
python3 V2/ue/Tools/check-v2-npc-schedule-location-binding.py
python3 V2/ue/Tools/check-v2-npc-schedule-interruption.py
python3 V2/ue/Tools/check-v2-npc-schedule-variation.py
python3 V2/ue/Tools/check-v2-npc-schedule-day-of-week.py
python3 V2/ue/Tools/check-v2-npc-schedule-weather-response.py
python3 V2/ue/Tools/check-v2-npc-schedule-social-interaction.py
python3 V2/ue/Tools/check-v2-npc-schedule-persistence.py
python3 V2/ue/Tools/check-v2-npc-schedule-debug-visualization.py
python3 V2/ue/Tools/check-v2-npc-schedule-editor.py
python3 V2/ue/Tools/check-v2-npc-schedule-lod.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/NPC/NPCScheduleAuthoringGuide_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```