Fighting Game · Guides & deep dives

V2 NPC Schedule Authoring Guide

NPCScheduleDataFormat_V2_Contract.json

9sections5 minread1table
Markdown source
On this page

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#

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