# Godot 4.6 Migration

This project targets Godot 4.6 as the active editor baseline.

## Current Risk Profile

- The project is a simple Godot 4 `Node2D` application with data-driven JSON content.
- There are no addons, shaders, TileMaps, 3D physics scenes, or export presets yet. The first generated portrait PNGs are plain project files and can be loaded by the dialogue UI before editor import metadata exists.
- The current renderer is explicitly set to `gl_compatibility`, so new-project rendering defaults in Godot 4.6 should not silently change the existing project renderer.
- `project.godot` advertises `config/features=PackedStringArray("4.6")`.
- Godot 4.6 script UID sidecar files (`*.gd.uid`) are part of the migrated project metadata and should stay versioned.

## Before Opening In 4.6 From An Older Checkout

1. Create a backup or initialize version control before the editor writes migration changes.
2. Run the data/readiness check:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools\check_godot46_readiness.ps1
```

3. If the Godot executable is not on `PATH`, set `GODOT_BIN` for command-line checks:

```powershell
$env:GODOT_BIN = "C:\Path\To\Godot_v4.6-stable_win64.exe"
```

## Editor Migration Steps From An Older Checkout

1. Open the project folder in Godot 4.6.
2. Let the editor import the project and accept any project-file migration prompt.
3. Run `Project > Tools > Upgrade Project Files...`.
4. Save, close, and reopen the project once.
5. Run the readiness check again. If `GODOT_BIN` is set, include the optional headless editor import:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools\check_godot46_readiness.ps1 -RunGodotImport
```

## Manual Smoke Test

- Main scene starts without script errors.
- Current campaign save loads or a new campaign starts cleanly.
- Briefing opens and can enter battle.
- Chapters, Shop, Armory, Roster, Formation, and Save open and close; completed or current Chapter entries can open a battle briefing.
- Finite-stock Shop entries show remaining counts and disable once sold out.
- Manual checkpoint save/load restores the expected current briefing without script errors.
- A player unit can move, attack, wait, use a tactic, use an item, and equip compatible gear; weapon effectiveness appears in forecasts and equipment/shop text when applicable, and equipment options show stat/range change hints.
- Named equipment rewards such as Yitian Sword and Dragon Spear validate, appear with compact rarity tags in reward/inventory/equipment text, and remain ordinary stackable inventory stock until unique item instances are implemented.
- Hovering an occupied tile shows the unit's class, movement type, AGI, movement, range, equipped weapon/armor/accessory, and a HUD portrait thumbnail when no unit is selected, with empty gear slots shown as `-`.
- The battle HUD and briefing objective panels split objective, progress, and risk details, including pending unlocks, single-tile or multi-cell destination reach status, defeated enemy counts, named protected-unit or commander safety, and turns remaining.
- Scenario event `when.after_event` prerequisites keep follow-up events from firing before their one-shot setup event.
- `unit_defeated` scenario events fire named-unit reactions before final battle status checks, including Yan Liang and Wen Chou defeat dialogue.
- `set_objective` scenario events show concrete objective-update logs, play a UI confirmation sound, refresh the HUD immediately, and briefly show the objective notice panel.
- `withdraw_unit` and `withdraw_units` scenario events remove living targets from the battlefield without marking them defeated.
- `set_ai_target_priority` scenario events retune enemy focus during battle and show target-focus feedback unless marked silent.
- Movement-triggered supply cache events grant battle inventory items with pickup feedback, and the items persist only after victory.
- The Threat toggle or `Y` key shows enemy physical and hostile tactic reach, hovered threatened tiles name the threatening units, and occupied player tiles show physical damage/hit estimates plus hostile tactic damage or status hints.
- Area tactics such as Blaze, Great Mend, and Poison Mist highlight affected cells, apply only to valid targets in the area, and spend MP once per cast.
- March Order and Hamper Order adjust movement range while active and expire with the normal support/debuff timing.
- Focus Order and Feint Order adjust physical hit chance through AGI bonuses or penalties and update attack forecasts while active.
- Poison Mist applies poison, poison ticks at the target team's phase start, and poison defeat immediately ends the battle when it satisfies a victory or defeat condition.
- Seal Tactic applies seal, prevents the affected unit from using tactics during its next action phase, and disables the tactic button with a sealed forecast/badge.
- Snare Tactic applies snare, prevents the affected unit from moving during its next action phase, and still leaves attacks, tactics, items, and wait available.
- Disarm Tactic applies disarm, prevents physical attacks and counterattacks, and still leaves movement, tactics, items, and wait available.
- Support, debuff, poison, seal, snare, and disarm status pips appear on affected board units, HUD summaries show remaining phases, and both disappear when those effects expire or are cured.
- Antidote can cure poison, Panacea can cure poison, seal, snare, or disarm, and neither consumes stock when used on a target without a matching status.
- Enemy turn advances and AI acts, including damage-aware physical target selection.
- Victory and defeat panels still appear.
- Victory result panels split rewards, roster changes, saved growth, campaign status, and pending choices; failed saves do not present rewards as applied.
- Briefings show victory/defeat text plus first-clear reward previews, while post-battle dialogue and post-battle choices still block progression until a choice is saved.
- Opening and post-battle dialogue can show generated officer portraits from `art/portraits` in the expanded dialogue panel, the side HUD can show selected or hovered unit portrait thumbnails, dialogue shows sequence progress, stepping back to the previous line works, and speaker initials are used only when no portrait is available.
- Next battle loads with saved roster, inventory, joined officers, and campaign flags.
- New Campaign clears the save and returns to the opening scenario.

## Watch Items

- If the editor updates `config/features`, review the diff before making content changes.
- If UI colors or canvas rendering look different, compare the battle board, overlays, and panels before changing art direction.
- If a save file behaves oddly after migration, test both a fresh campaign and existing `user://campaign_save.json` / `user://campaign_manual_save.json` files.
