Godot Version Migration

Full-history Godot version migration hub. Use when upgrading any Godot project toward the library target (currently 4.7)—from 1.x/2.x legacy eras through 3→4 and hop-by-hop 4.x minors—or finding Domain Skill-scoped migration notes. Trigger keywords: upgrade Godot, migrate Godot version, Godot 3 to 4, Godot 2 to 3, upgrading_to_godot, version migration, breaking changes, convert-3to4, TileMapLayer, AnimationMixer, engine.cfg, project.godot.

gabrielmoreira Updated Sep 9, 2026 17 repo stars

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add gabrielmoreira/godot-version-migration

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/gabrielmoreira/godot-version-migration.svg)](https://skillmd.com/skills/gabrielmoreira/godot-version-migration)

Trust & safety

Audits pending

Not yet audited · commit d80c064

Permissions this skill uses

Makes network calls
The instructions fetch remote URLs or call external services.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Godot Version Migration

Orchestrator for engine version upgrades from early Godot through the library target. Domain Skills document current APIs; this hub owns the upgrade path.

Library target: Godot 4.7+

Corpus: docs changelog · interactive changelog · download archive · GitHub releases · migrating index

NEVER Do

NEVER skip majors — route 1.x → 2.x → latest 3.x → 4.0 before any 4.x minor ladder.
NEVER skip 4.x hops — upgrade 4.0 → 4.1 → … → 4.7 one minor at a time; stabilize after each hop.
NEVER claim automatic 1.x→4.x conversion or bit-exact autopilot.
NEVER treat Domain Skill bodies as migration changelogs — load references/<topic>.md (mirrored from each skill’s references/migration-notes.md).
NEVER load all module notes at once — only subsystems present in the project.
NEVER mix server/client Godot minors for high-level multiplayer (especially across 4.2→4.3 SceneMultiplayer protocol changes).
NEVER choose Mesh “Restart & Upgrade” without VCS backup (4.1→4.2 mesh format).
NEVER run the 3→4 converter without a full backup (tool does not backup).

Version detect

Read project.godot (config_version, config/features) or legacy engine.cfg.
Ask the user if files are ambiguous.
Map to an era in references/era-index.md.

Workflow router (MANDATORY)

Detected era	Load	Do NOT
1.x / early 2	legacy/pre-2-context.md	Invent a 1→4 converter
2.x	legacy/2-to-3.md then stabilize on latest 3.x	Jump straight to 4.7 notes
3.x	bridges/3-to-4.md + official 3→4 guide	Skip latest-3.x stabilize gate
4.x `< 4.7`	Official hop guide + hop-index.md module notes for touched systems	Skip minors
Already 4.7+	godot-master / Domain Skills	Treat this hub as a coding tutorial

Steps (4.x minors)

While current < 4.7, perform exactly one hop to current + 0.1.
Open the official upgrading page for the destination version.
From hop-index.md, open only module notes for subsystems present in the project.
Apply fixes; open in the new editor; playtest; repeat.

Hop table

Majors / bridges

Era	Resource
1.x archaeology	legacy/pre-2-context.md
2.x → 3.x	legacy/2-to-3.md
3.x → 4.0	bridges/3-to-4.md · official guide
Ladder overview	era-index.md

4.x minors

Hop	Official guide
4.0 → 4.1	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.1.html
4.1 → 4.2	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.2.html
4.2 → 4.3	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.3.html
4.3 → 4.4	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.4.html
4.4 → 4.5	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html
4.5 → 4.6	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html
4.6 → 4.7	https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html

Cross-skill checklist: references/hop-index.md

Module directory

Mirrored Domain Skill migration notes live at references/<topic>.md (e.g. references/2d-physics.md). Hub-native legacy/, bridges/, and era-index.md are not Domain Skill mirrors.

sync_godot_version_migration.py --all

Reference

Official docs

Related Skills

Master

godot-master — Library router for current Domain Skill modules after migration is complete.

Downstream / consumers

godot-analyst — Score architecture on the target APIs after hops land.
godot-auditor — Never-list / legacy-syntax verification after upgrades.
godot-builder — CI / headless bake against the new engine target after each hop.

Complements

godot-project-foundations — Project settings / structure once on the target version.
godot-gdscript-mastery — Typed GDScript 2.0 idioms after 3→4 / 4.x language hops.
godot-export-builds — Re-validate exports after each hop that touches platforms.

---name: godot-version-migrationdescription: Full-history Godot version migration hub. Use when upgrading any Godot project toward the library target (currently 4.7)—from 1.x/2.x legacy eras through 3→4 and hop-by-hop 4.x minors—or finding Domain Skill-scoped migration notes. Trigger keywords: upgrade Godot, migrate Godot version, Godot 3 to 4, Godot 2 to 3, upgrading_to_godot, version migration, breaking changes, convert-3to4, TileMapLayer, AnimationMixer, engine.cfg, project.godot.--- # Godot Version Migration Orchestrator for **engine version upgrades** from early Godot through the library target. Domain Skills document **current** APIs; this hub owns the upgrade path. **Library target:** Godot **4.7+** Corpus: [docs changelog](https://docs.godotengine.org/en/stable/about/docs_changelog.html) · [interactive changelog](https://godotengine.github.io/godot-interactive-changelog/) · [download archive](https://godotengine.org/download/archive/) · [GitHub releases](https://github.com/godotengine/godot/releases) · [migrating index](https://docs.godotengine.org/en/stable/tutorials/migrating/index.html) ## NEVER Do - **NEVER skip majors** — route 1.x → 2.x → latest 3.x → 4.0 before any 4.x minor ladder. - **NEVER skip 4.x hops** — upgrade `4.0 → 4.1 → … → 4.7` one minor at a time; stabilize after each hop. - **NEVER** claim automatic 1.x→4.x conversion or bit-exact autopilot. - **NEVER** treat Domain Skill bodies as migration changelogs — load `references/<topic>.md` (mirrored from each skill’s `references/migration-notes.md`). - **NEVER** load all module notes at once — only subsystems present in the project. - **NEVER** mix server/client Godot minors for high-level multiplayer (especially across 4.2→4.3 SceneMultiplayer protocol changes). - **NEVER** choose Mesh “Restart & Upgrade” without VCS backup (4.1→4.2 mesh format). - **NEVER** run the 3→4 converter without a full backup (tool does not backup). ## Version detect 1. Read `project.godot` (`config_version`, `config/features`) or legacy `engine.cfg`. 2. Ask the user if files are ambiguous. 3. Map to an era in [references/era-index.md](references/era-index.md). ## Workflow router (MANDATORY) | Detected era | Load | Do NOT | |--------------|------|--------| | 1.x / early 2 | [legacy/pre-2-context.md](references/legacy/pre-2-context.md) | Invent a 1→4 converter | | 2.x | [legacy/2-to-3.md](references/legacy/2-to-3.md) then stabilize on **latest 3.x** | Jump straight to 4.7 notes | | 3.x | [bridges/3-to-4.md](references/bridges/3-to-4.md) + official 3→4 guide | Skip latest-3.x stabilize gate | | 4.x `< 4.7` | Official hop guide + [hop-index.md](references/hop-index.md) module notes for touched systems | Skip minors | | Already 4.7+ | [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) / Domain Skills | Treat this hub as a coding tutorial | ### Steps (4.x minors) 1. While `current < 4.7`, perform **exactly one** hop to `current + 0.1`. 2. Open the official upgrading page for the destination version. 3. From [hop-index.md](references/hop-index.md), open only module notes for subsystems present in the project. 4. Apply fixes; open in the new editor; playtest; repeat. ## Hop table ### Majors / bridges | Era | Resource | |-----|----------| | 1.x archaeology | [legacy/pre-2-context.md](references/legacy/pre-2-context.md) | | 2.x → 3.x | [legacy/2-to-3.md](references/legacy/2-to-3.md) | | 3.x → 4.0 | [bridges/3-to-4.md](references/bridges/3-to-4.md) · [official guide](https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.html) | | Ladder overview | [era-index.md](references/era-index.md) | ### 4.x minors | Hop | Official guide | |-----|----------------| | 4.0 → 4.1 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.1.html | | 4.1 → 4.2 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.2.html | | 4.2 → 4.3 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.3.html | | 4.3 → 4.4 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.4.html | | 4.4 → 4.5 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html | | 4.5 → 4.6 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html | | 4.6 → 4.7 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html | Cross-skill checklist: [references/hop-index.md](references/hop-index.md) ## Module directory Mirrored Domain Skill migration notes live at `references/<topic>.md` (e.g. `references/2d-physics.md`). Hub-native `legacy/`, `bridges/`, and `era-index.md` are **not** Domain Skill mirrors. ```text sync_godot_version_migration.py --all ``` ## Reference ### Official docs - [Migrating to a new version](https://docs.godotengine.org/en/stable/tutorials/migrating/index.html) - [Upgrading from Godot 3 to Godot 4](https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.html) - [Docs changelog](https://docs.godotengine.org/en/stable/about/docs_changelog.html) ### Related Skills #### Master - [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router for current Domain Skill modules after migration is complete. #### Downstream / consumers - [godot-analyst](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-analyst/SKILL.md) — Score architecture on the **target** APIs after hops land. - [godot-auditor](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-auditor/SKILL.md) — Never-list / legacy-syntax verification after upgrades. - [godot-builder](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-builder/SKILL.md) — CI / headless bake against the new engine target after each hop. #### Complements - [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Project settings / structure once on the target version. - [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — Typed GDScript 2.0 idioms after 3→4 / 4.x language hops. - [godot-export-builds](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-export-builds/SKILL.md) — Re-validate exports after each hop that touches platforms.

gabrielmoreira/agent-skills-mirror/tree/main/mirrors/repos/thedivergentai@GD-Agentic-Skills/skills/godot-version-migration commit d80c064701

Frequently asked questions

npx skillmds@latest add gabrielmoreira/godot-version-migration