v5.0 to v6.0 Migration Guide

Migrating to GridPlacement 6.0 (C#)

This guide helps you upgrade your project from the GridBuilding v5.0 (GDScript-based) plugin to the C#‑based GridPlacement 6.0 plugin. Under the hood, the C# assemblies and namespaces still live under GridBuilding.* (for example GridBuilding.Core), but the Godot-facing plugin and docs are branded GridPlacement 6.0. The new architecture provides significant performance and reliability improvements.

🎯 What’s Changing?

GridBuilding v6.0 introduces a Service-Based Architecture written in pure C#. This change affects how you interact with the plugin’s core systems, but the Godot-facing API (nodes, resources, signals) remains familiar.

🧭 Should I Migrate Now?

Short answer: Once GridPlacement 6.0 is marked production‑ready, you should plan to migrate as soon as practical. The C# architecture is vastly more maintainable and will be the canonical version going forward; the 5.x GDScript plugin will enter maintenance mode and be phased out over time.

We strongly recommend migrating to GridPlacement 6.0 when ALL of the following are true:

• ✅ 6.0 has been tagged as a stable release in the plugin docs/repository.
• ✅ Your target Godot version supports C# (Godot 4.x with .NET).
• ✅ You are willing to maintain a small C# project alongside your GDScript game code.
• ✅ You are not blocked by a missing integration guide or tool noted in the docs (for example, items still marked “draft” or “planned”).

You may choose to temporarily stay on GridBuilding 5.x (GDScript) if:

• You are shipping a product imminently on an existing 5.x codebase and cannot risk architectural changes right now.
• Team members are not yet comfortable maintaining any C# code.
• You rely on tutorials or tools that haven’t been updated for 6.0 yet.

However, the long‑term plan is:

• 🧱 GridPlacement 6.0 (C#) becomes the canonical plugin.
• 🧊 GridBuilding 5.x (GDScript) is frozen except for critical bug/security fixes.
• 📦 New features, performance work, and deep refactors will target C# first.

🧰 What You Need in Your Project

To use GridPlacement 6.0, your Godot project must be C#‑enabled and able to reference the core DLL:

1. Set up a C# Godot project

   • Follow the official Godot docs for creating a C# project (Godot 4 + .NET):
     • Godot C# Basics
   • Ensure a .csproj exists for your game, and that Godot recognizes C# scripts.

2. Add the core library (GridBuilding.Core.dll)

   • Place GridBuilding.Core.dll into a managed library folder inside your project (for example res://lib/ or res://libs/, depending on your project convention).
   • Reference that DLL from your C# project so your game code and adapters can use GridBuilding.Core types.

3. Install the Godot‑side plugin

   • Copy the GridPlacement 6.0 Godot plugin into:
     • res://addons/GridPlacement/ (PascalCase folder name).
   • Enable the plugin in Project → Project Settings → Plugins.
   • The plugin’s C# adapter nodes will then be available for scenes and UI.

🔄 Key Architectural Changes

State Management

State objects are no longer Godot Resources. They are now pure C# classes, which means:

• Faster Access: No Godot overhead for state operations
• Better Testing: States can be tested without Godot
• Type Safety: Compile-time error checking

Service Layer

Business logic is now handled by dedicated Service classes:

• BuildingService: Manages build operations
• ManipulationService: Handles object transformations
• InputService: Processes user input

Communication Pattern

The new architecture uses a strict unidirectional flow:

1. Godot Layer calls Service methods
2. Service updates State
3. Service fires Events
4. Godot Layer listens to Events and updates visuals

📋 Migration Checklist

Before You Start

• Backup your project
• Note any custom modifications to GridBuilding scripts
• Disable GridBuilding plugin temporarily

Migration Steps

1. Update Plugin

1. Remove the old GridBuilding plugin folder
2. Install the new GridBuilding v6.0 plugin
3. Re-enable the plugin in Godot settings

2. Update Your Code

Most of your code will work without changes, but check these areas:

State Access (If Directly Accessed)

1
2
3
4
5
6

# Old v5.0 way (if you accessed state directly)
var state = $GridBuilding.get_state()
state.set_current_placeable(my_placeable)

# New v6.0 way (use the service API)
$GridBuilding.enter_build_mode(my_placeable)

Custom Signals

1
2
3
4
5

# Old v5.0 way
$GridBuilding.connect("building_placed", self, "_on_building_placed")

# New v6.0 way (signals remain the same)
$GridBuilding.building_placed.connect(_on_building_placed)

3. Verify Functionality

• Test basic building placement
• Test manipulation (move/rotate/delete)
• Check custom UI integration
• Verify save/load functionality

🚀 Performance Benefits You’ll See

• Faster Build Mode: Entering build mode is significantly faster [internal testing]
• Smoother UI: State updates no longer block the main thread
• Better Error Messages: Compile-time errors catch issues early
• Improved Stability: Strong typing prevents many runtime errors

🛠️ Common Migration Issues

Issue: “Can’t find state property”

Cause: Direct state access is no longer supported. Solution: Use the service API methods instead.

Issue: Custom scripts don’t compile

Cause: API changes in core systems. Solution: Check the API Reference for updated method signatures.

Issue: Performance seems slower

Cause: First-time C# compilation overhead. Solution: This is normal. Performance improves after the initial run.

📞 Getting Help

If you encounter issues during migration:

1. Check the API Reference for updated methods
2. Review the Service Architecture guide
3. Ask in the community for help from other developers

🔧 5.0 → 6.0 Migration Tool (Planned)

To make upgrades easier, a dedicated 5.0 → 6.0 migration tool is planned. The goal of this tool is to:

• Scan your project for GridBuilding 5.x GDScript dependencies (scripts, resources, scenes).
• Help convert or re‑wire those usages to the new C# GridPlacement 6.0 APIs and resources where possible.
• Produce a report of anything it cannot safely convert automatically, so you can review those spots manually.

The exact capabilities and UX of this tool are still in design; this guide will be updated with concrete usage instructions once the tool is ready.

🎉 You’re Done!

After migration, you’ll have a more robust, faster, and maintainable GridBuilding system. The new C# foundation enables future features and better performance.

Status Note: This migration guide is a working draft. It will be expanded with more examples, screenshots, and step‑by‑step checklists before the GridPlacement 6.0 release.

For detailed technical changes, see the Class Mapping Documentation in the plugin repository.