# V2 NPC Schedule Execution Engine

`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
```