Fighting Game · Guides & deep dives

V2 NPC Schedule Data Format

minutes from midnight.

4sections2 minread
Markdown source
On this page

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