Migration Guide v5.0.0

Overview

This page contains a concise, practical migration checklist and rationale for upgrading to v5.0.0 from 4.x (tested from 4.4.x and compatible with 4.5.x). For full API changes and details, see the Breaking Changes page.

Summary:

Save existing settings/resources to disk (.tres/.res) so they can be reused in the new GBConfig.
Placeable resources (placeable items, meshes, visuals) do not require modification — they continue to work as placeables.
Add a GBInjectorSystem node to the gameplay scene that needs grid-building features and assign a GBCompositionContainer to it (use provided templates where possible).
Create a GBCompositionContainer resource, nest a GBConfig, and reassign your saved resource files into the new config.

Prerequisites

Godot 4.4.x or later (4.5 compatible). v5.0.0 depends on APIs introduced in Godot 4.4+.
A copy of your current project where you can export/save settings resources.

Step 1 — Export & save your existing settings resources

Before upgrading your project files or replacing plugin code, save any configuration, template, or exported resources you currently use into .tres / .res files in your project. Typical resources to save:

Visual templates, indicator materials, and scene fragments used by placement systems.
Any exported configuration objects that were previously stored as exported properties on nodes (e.g., action sets, placement templates, visual presets).

Why: v5 centralizes configuration in GBConfig and removes many per-node exported properties. Saving to .tres/.res ensures you can reassign these resources to the new config instead of losing them.

Example (editor)

Select the node/resource that holds the configuration in the editor.
Convert or Save As the resource to res://data/gb_saved_my_settings.tres.

Note: You do not need to change your placeable resources (the objects you place/move). These remain compatible.

Step 2 — Upgrade plugin and runtime (install v5.0.0)

Update the plugin to v5.0.0 and restart the editor. Follow your usual plugin update workflow.
Confirm Godot version compatibility (see Prerequisites above).

Step 3 — Add `GBInjectorSystem` to your gameplay scene

Recommended approach:

Pick the gameplay or player-root scene where grid-building will run (the scene that is active when players build/place objects).
Add a GBInjectorSystem node to that scene.
Create or use a GBCompositionContainer resource and assign it to the GBInjectorSystem’s exported composition_container property.

Tip: the plugin ships with composition container templates under the plugin templates folder. Use the supplied template if you want a tested starting stack of systems and resources.

Why: This keeps injection local to gameplay runtime contexts and prevents embedding injector state inside level resource files.

See: ../api/GBInjectorSystem/ and ../api/GBCompositionContainer/ for properties and usage.

Step 4 — Create `GBCompositionContainer` + nested `GBConfig` and reassign saved resources

Create a GBCompositionContainer resource in your project (e.g., res://data/gb_container.tres).
Inside the container, create a GBConfig resource and assign it to the container’s config property.
Reapply the .tres/.res resources you saved in Step 1 into the new GBConfig fields (templates, visuals, action sets, etc.).

Notes and caveats:

Some resource names or field names may have changed between v4 and v5. If a saved resource does not map directly into a field, you may need to create a new nested resource and copy settings over manually.
The DI composition will distribute these settings to systems, nodes, and subcomponents at runtime, reducing the need to wire many exported fields across the scene.

See: ../api/GBConfig/ for the config structure.

Step 5 — Ensure `GBOwnerContext` and a `GBOwner` are available at runtime

The GBOwnerContext API changed: you must set a GBOwner instance via GBOwnerContext.set_owner(...) so systems know who is controlling system operations. Typically this will be the player node or a dedicated owner object created for simulation.
Ensure you create and register a GBOwner resource/object and assign it into the container or the level context so systems can acquire the owner from the GBOwnerContext or via injector wiring.

See: ../api/GBOwnerContext/ and ../api/GBOwner/.

Step 6 — Smoke test and validation

Launch your gameplay scene with the new injector and composition container instantiated.
Run the plugin’s validation: call validate() on major systems and inspect get_runtime_issues() / get_editor_issues() to find migration problems.
Inspect logs via the container-provided logger (composition_container.get_logger() / ../api/GBLogger/).

Example: call validation from a world script (on ready)

extends Node

@export var injector: GBInjectorSystem

func _ready():
  if injector:
    # run_validation() will log any issues via the container's logger
    var ok := injector.run_validation()
    if not ok:
      push_warning("GB validation returned issues — check logs")
  else:
    push_warning("No GBInjectorSystem assigned to world script; skipping validation")

Concrete validation examples

Here are a few short, real-world examples (taken from test helpers and demos) showing how host projects and tests inspect validation issues. These are intentionally small — adapt them into your game or test harness.

Inspect and log issues directly from the injector:

var issues: Array[String] = injector.get_runtime_issues()
if issues.size() > 0:
    for issue in issues:
        push_warning(issue)

Aggregate issues from multiple systems (useful in test harnesses or smoke tests):

var issues: Array[String] = []
issues.append_array(injector.get_runtime_issues())
issues.append_array(grid_targeting_system.get_runtime_issues())
issues.append_array(building_system.get_runtime_issues())
if issues.size() > 0:
    for issue in issues:
        push_warning(issue)

Inspect specific container-scoped state (example: targeting state from the composition container):

var targeting_issues := composition_container.get_targeting_state().get_runtime_issues()
if targeting_issues.size():
    for t in targeting_issues:
        push_warning(t)

If you find missing configurations, re-open your GBConfig resource and add or rewire any nested resources. Some names may have changed — check the Breaking Changes page for common signature/rename notes.

FAQ / common pitfalls

Q: Do I need to change placeable objects (items I place in levels)?
- A: No — placeable resources remain compatible. The migration focuses on configuration + wiring.
Q: What if a resource I saved doesn’t fit the new config fields?
- A: Some fields were renamed or moved; create a new nested resource in the GBConfig and copy values across. The DI system will then distribute them to the necessary systems.
Q: Where should I add the injector node — level scene or gameplay scene?
- A: Add the GBInjectorSystem to your gameplay/active scene (where runtime player actions occur). Avoid embedding injector state in static level resource files.

References

Breaking changes: ../guides/breaking-changes/
API pages (v5.0.0): ../api/

If you want, I can:

Create a project_docs/migration_v5_upgrade.md with copy/paste checklist and editor actions.
Add a small compatibility note page for renamed classes (e.g., DragBuildManager → DragManager) under migration/.