# V2 Timing Adjustment System

This runbook covers `TODOS.phase-72.72.13.2.6` and `TODOS.phase-72.72.13.2.12`:
extending timed puzzle limits, slowing story QTE windows, adding opt-in dodge
input grace, and resolving global game speed from 0.5x to 1.0x.

## Runtime Surface

Timing adjustments extend the V2Input accessibility profile model and connect to
story, quest, settings, and persistence surfaces:

- profile: `FV2TimingAdjustmentProfile`
- resolved state: `FV2ResolvedTimingAdjustment`
- puzzle enum: `EV2TimedPuzzleLimitMode`
- QTE enum: `EV2QTEWindowTimingMode`
- dodge enum: `EV2DodgeTimingAssistMode`
- source library: `UV2InputBlueprintLibrary`
- config asset: `UV2InputConfigAsset`
- timed puzzle row: `Settings.Accessibility.TimedPuzzleLimit`
- QTE window row: `Settings.Accessibility.QTEWindowTiming`
- dodge timing row: `Settings.Accessibility.DodgeTiming`
- global game speed row: `Settings.Accessibility.GlobalGameSpeed`
- persistence snapshot: `FV2PlayerSettingsSnapshot`
- save game: `UV2SaveGame`
- persistence subsystem: `UV2PersistenceSubsystem`
- contract:
  `V2/ue/Content/V2/Input/Accessibility/TimingAdjustmentSystem_V2_Contract.json`
- focused checker: `V2/ue/Tools/check-v2-timing-adjustment-system.py`

## Behavior

Profiles default to authored timing. Players can opt into:

- `Timing.Puzzle.Extended25`, `Timing.Puzzle.Extended50`, or
  `Timing.Puzzle.Double` for single-player timed puzzle limits.
- `Timing.QTE.Slow150`, `Timing.QTE.Slow200`, or `Timing.QTE.Slow300` for story
  QTE window slowdown.
- `Timing.Dodge.Plus2Frames`, `Timing.Dodge.Plus4Frames`, or
  `Timing.Dodge.Plus6Frames` for dodge input grace.
- `Settings.Accessibility.GlobalGameSpeed` for a 50-100 percent slider that
  resolves to `GlobalGameSpeedScalar` values from 0.5x through 1.0x in 0.05x
  steps.

The dodge assist extends input grace only. It does not add invulnerability,
change competitive frame data, or apply to ranked behavior. All non-authored
timing modes are single-player, opt-in, saved per player, restored before
gameplay, and ranked-disabled when enabled. Global game speed resolves through
`ResolveGlobalGameSpeedScalar` and `ResolveGlobalGameSpeedDeltaSeconds` so
single-player modes can apply the scalar as world time dilation without changing
frame-data authoring.

## Gameplay Hooks

Timed puzzle quest rules opt into adjustment with `bTimedPuzzleTimingAdjustment`
and the canonical timing profile/row ids.
`ResolveTimingAdjustedTimeLimitSeconds` clamps authored puzzle limits to the
rule's maximum scalar, while the legacy matcher still preserves authored timing
for rules that do not call the timing-aware helper.

Story QTE prompt specs carry `TimingAdjustmentSettingRowId`,
`TimingAdjustmentProfileId`, and `MaxTimingAdjustedWindowFrames`. Story prompts
remain frame-perfect by default, but the timing-aware path can slow QTE windows
after player opt-in.

## Persistence

`FV2PlayerSettingsSnapshot` stores the timing adjustment profile with startup
restore flags. `SaveTimingAdjustmentProfile` persists a validated per-player
profile, `GetStartupTimingAdjustmentProfile` resolves it on startup, and
`MarkTimingAdjustmentAppliedOnStartup` records the before-gameplay apply time.
`ValidateSave` rejects timing profiles whose account id does not match the save
header. The same profile stores the global game speed scalar, so 0.5x-1.0x
slowdown is restored through the existing timing startup path.

## Verification

Run these checks after changing timing adjustments:

```bash
python3 V2/ue/Tools/check-v2-timing-adjustment-system.py
python3 V2/ue/Tools/check-v2-input-module.py
python3 V2/ue/Tools/check-v2-quest-failure-conditions.py
python3 V2/ue/Tools/check-v2-story-mode.py
python3 V2/ue/Tools/check-v2-modes-module.py
python3 V2/ue/Tools/check-v2-profile-save-game.py
python3 V2/ue/Tools/check-v2-persistence-module.py
python3 V2/ue/Tools/check-v2-accessibility-feature-set.py
python3 V2/ue/Tools/check-v2-settings-ui.py
python3 V2/ue/Tools/check-v2-ui-module.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-timing-adjustment-system.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Input/Accessibility/TimingAdjustmentSystem_V2_Contract.json
```

Automation coverage:

- `V2.Input.Module`
- `V2.Gameplay.Quest.FailureConditions`
- `V2.Modes.Module`
- `V2.Persistence.Module`
- `V2.Persistence.ProfileSave.AssetContract`
- `V2.UI.Module`
- `V2.UI.SettingsScreen.AssetContract`

## Horde Gates

- `timing-adjustment-source`
- `timing-adjustment-gameplay-hooks`
- `timing-adjustment-settings-rows`
- `timing-adjustment-per-player-persistence`
- `timing-adjustment-startup-apply`
- `timing-adjustment-ci-wired`