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, imported art assets, shaders, TileMaps, 3D physics scenes, or export presets yet.
• 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.
• 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.
• Support, debuff, and poison status pips appear on affected board units and disappear when those effects expire or are cured.
• Antidote can cure poison and does not consume stock when used on a target without a matching status.
• Enemy turn advances and AI acts.
• Victory and defeat panels still appear.
• Post-battle dialogue and post-battle choices still block progression until a choice is saved.
• 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.