# V2 NPC Schedule Variation

`NPCScheduleVariation.V2` applies deterministic day-by-day variety to authored
NPC schedules. It keeps the base schedule as the source of truth, then emits a
varied schedule plus block-level metadata for market substitutions, random walk
paths, and arrival-time offsets.

## Runtime Surface

- `FV2NPCScheduleVariationRule` describes a variation rule with type, target
  block, chance percent, replacement market destination, path ids, max arrival
  offset, priority, enabled state, and tags.
- `FV2NPCScheduleVariationRequest` carries the base schedule, day seed, NPC
  seed, application toggle, and ordered rule set.
- `FV2NPCScheduleBlockVariation` records the applied rule, original and varied
  times, original and selected locations, selected path, deterministic roll, and
  variation flags.
- `FV2NPCScheduleVariationResult` returns the varied schedule, block variation
  records, seed values, variation flags, and validation issues.

## Variation Rules

1. The example market rule targets `block.visit.tavern` with a 30% deterministic
   chance to replace the tavern visit with `location.market.stall`,
   `Schedule.Activity.VisitMarket`, and `Behavior.Schedule.BrowseMarket`.
2. The random-walk rule deterministically selects one path id from the authored
   path pool for the target block.
3. The arrival-offset rule delays the target block start by a deterministic
   bounded amount and marks the varied schedule as allowing idle fallback gaps.
4. Rule rolls are derived from schedule id, NPC id, variation id, target block,
   day seed, and NPC seed; no global RNG is used.
5. Invalid ids, chance ranges, target blocks, replacement payloads, path pools,
   and arrival offsets produce blocking issues before mutation.

## Validation Commands

Run these targeted checks when touching schedule variation:

```bash
python3 V2/ue/Tools/check-v2-npc-schedule-variation.py
python3 V2/ue/Tools/check-v2-npc-schedule-interruption.py
python3 V2/ue/Tools/check-v2-npc-schedule-location-binding.py
python3 V2/ue/Tools/check-v2-npc-schedule-activity-behavior.py
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/NPCScheduleVariation_V2_Contract.json
python3 -m py_compile V2/ue/Tools/check-v2-npc-schedule-variation.py
```