# V2 NPC Schedule Pathfinding

`NPCSchedulePathfinding.V2` turns schedule execution results into deterministic
navigation intent. It does not invoke Unreal navigation directly; instead it
selects a schedule destination and emits a navigation command payload that
runtime AI, pathfinding, or crowd systems can consume.

## Runtime Surface

- `FV2NPCSchedulePathfindingRequest` carries the authored schedule, current
  time, NPC current location id, travel estimate, early-arrival buffer, next
  transition planning flag, and command issuing flag.
- `FV2NPCScheduleNavigationCommand` carries the route source, destination,
  target schedule block, activity tag, behavior tag, planned departure and
  arrival minutes, wait minutes, and issue state.
- `FV2NPCSchedulePathfindingResult` reports whether the NPC is already at the
  scheduled location, needs navigation, targets the next transition, should wait
  after early arrival, and issued a navigation command.
- `EV2NPCSchedulePathfindingIssueType` distinguishes invalid inputs, active
  location routing, transition routing, early wait, command issuance,
  suppression, and invalid command payloads.

## Routing Rules

1. Pathfinding first evaluates `FV2NPCScheduleExecutionResult`.
2. If the NPC is already at the target block's `LocationId`, no navigation is
   emitted.
3. Otherwise, the result emits a move command from `CurrentLocationId` to the
   schedule destination.
4. When the next block starts within
   `EstimatedTravelMinutes + EarlyArrivalBufferMinutes`, the pathfinder targets
   that next transition destination instead of the current block.
5. Planned arrival wraps across midnight using authored schedule minutes.
6. If arrival is before the target block start, `WaitMinutes` is set and the
   command asks the NPC to wait at the destination.
7. `bIssueNavigationCommand` can suppress command issue while keeping the
   deterministic route plan available for debug and prediction.

## Navigation Command

The command is data-only and stable:

- `CommandId` is derived from schedule id and target block id.
- `SourceLocationId` is the NPC's current known schedule location.
- `DestinationLocationId` is the target block's location id.
- `TargetBlockId`, `ActivityTag`, and `BehaviorTag` preserve the selected
  schedule intent.
- `PlannedDepartureMinute`, `PlannedArrivalMinute`, and `WaitMinutes` make
  transition timing auditable.

## Validation Commands

Run these targeted checks when touching schedule pathfinding:

```bash
python3 V2/ue/Tools/check-v2-npc-schedule-pathfinding.py
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/NPCSchedulePathfinding_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-npc-schedule-pathfinding.py
```