Fighting Game · Guides & deep dives

V2 NPC Schedule Execution Engine

issuing flag, idle fallback flag, and default idle tags.

4sections1 minread
Markdown source
On this page

NPCScheduleExecutionEngine.V2 evaluates authored NPC schedule definitions at a specific local time of day. It validates the schedule data format, selects the active block, computes transition timing, and emits a behavior command payload that the AI system can consume without coupling this layer to behavior tree runtime objects.

Runtime Surface#

  • FV2NPCScheduleExecutionRequest carries the schedule, current time, command issuing flag, idle fallback flag, and default idle tags.
  • FV2NPCScheduleBehaviorCommand is the data-driven behavior handoff to AI. It carries NPC id, schedule id, block id, activity, location, behavior, interaction, priority, interruption policy, reservation policy, and tags.
  • FV2NPCScheduleExecutionResult reports the selected active block, current minute, block start/end minutes, elapsed time in the block, minutes until the next transition, emitted command, fallback use, and validation issues.
  • EV2NPCScheduleExecutionIssueType distinguishes invalid input, no active block, active block selection, command issuance, command suppression, idle fallback, and invalid command payloads.

Execution Rules#

  1. The engine validates FV2NPCScheduleDefinition before issuing behavior.
  2. Current time is converted to minutes from midnight and must be valid.
  3. Active blocks use the data format's half-open range rules.
  4. Midnight-wrapping blocks are active when the current minute is after the start or before the end.
  5. A selected block emits an FV2NPCScheduleBehaviorCommand when bIssueBehaviorCommand is true.
  6. MinutesElapsedInBlock and MinutesUntilTransition are computed from the active block's start and end times, including overnight blocks.
  7. Schedules with allowed coverage gaps can emit an idle fallback command when bAllowIdleFallback is true.

AI Handoff#

The execution engine does not start behavior trees directly. Instead it emits a stable command id and concrete tags:

  • ActivityTag names the authored routine, such as Schedule.Activity.WorkShop.
  • LocationId points at the scheduled destination.
  • BehaviorTag identifies the behavior the AI layer should activate.
  • InteractionTag identifies optional seats, beds, counters, or workstations.
  • bAllowInterruption and bRequiresReservation preserve author intent for later interruption and location-reservation systems.

Validation Commands#

Run these targeted checks when touching NPC schedule execution:

bash
python3 V2/ue/Tools/check-v2-npc-schedule-execution-engine.py
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/NPCScheduleExecutionEngine_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-npc-schedule-execution-engine.py