heros/docs/GODOT_4_6_MIGRATION.md

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

$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 -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, and equipped weapon/armor/accessory, with empty slots shown as -.
• 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 and 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.
• 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, with speaker initials only used 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.