This guide provides a comprehensive approach for migrating your Grid Building projects from the legacy GDScript-based 5.x line (5.0/5.1) to the C#-first 6.0.0 API, including the major architectural change from the 5.x Placeable resource model to the 6.0 IPlaceable + Placeable Core model.

🎯 Overview

What’s Changing in 6.0.0

• Architecture Migration: 5.x Godot resources are no longer the canonical “placeable” type for Core logic
• Interface Introduction: IPlaceable is now used in Core for engine-agnostic placeables
• Property Changes: Some properties moved to Properties dictionary for flexibility
• Enhanced Performance: Significant performance improvements with C#
• Better Type Safety: Compile-time type checking and better IDE support
• API Improvements: Cleaner, more consistent API design
• Enhanced Tooling: Better debugging and profiling capabilities

Migration Benefits

• Runtime Performance: C# executes 25-150% faster for most operations (based on official Godot benchmarks)
• Better IDE Support: Full IntelliSense, refactoring, and debugging
• Type Safety: Catch errors at compile-time, not runtime
• Easier Maintenance: Cleaner codebase with better tooling
• Future-Proof: Alignment with Godot’s C# direction
• Godot vs Core Separation: Better testing through clear architectural boundaries
  • Core Layer: Engine-agnostic business logic, easily unit tested without Godot dependencies
  • Godot Layer: Engine-specific implementation, integration tested with Godot mocks
  • Improved Test Coverage: Core logic can be tested independently, increasing overall test reliability
  • Better Separation of Concerns: Clear distinction between game logic and engine integration
  • Faster Test Execution: Core tests run faster without Godot initialization overhead

📋 Prerequisites

Before You Begin

1. Backup Your Project

   1 2 3

   # Create a complete project backup cp -r your_project your_project_v5.0.0_backup git add -A && git commit -m "Pre-6.0.0 migration backup"

2. Verify Current Version

   • Ensure you’re running Grid Building 5.x
   • Check addons/grid_building/plugin.gd for version information
   • Document any custom modifications you’ve made

3. Install Required Tools

   1 2 3 4 5

   # Install .NET SDK ( Godot 4.x requires .NET 6.0 or later) dotnet --version # Should be 6.0.0 or later # Install the enhanced migration tool # ( included in this repository )

4. Close Godot Editor

   • CRITICAL: Close Godot completely before migration
   • This prevents file locking and corruption

5. Understand Tooling Safety Constraints

   • The official migration tool is the GodotToolkit CLI (godot-toolkit).
   • The tool runs in dry-run mode by default; no files are changed unless you explicitly opt in.
   • Real execution requires the long flag --execute-migration so it is clear when you are applying changes.
   • Execution is only supported when your project is using the legacy GDScript-based Grid Building 5.x plugin.
   • The tool will refuse to execute if:
     • It cannot determine the GridBuilding plugin version under your godot/addons folder.
     • The detected plugin version is not approved (currently only 5.0.0).
     • The GridBuilding plugin is already using C# scripts instead of GDScript.
   • You can always run godot-toolkit in --dry-run mode on any project to inspect what it would change.

🔄 Migration Approaches

Approach 1: Automated Migration ( the recommended approach )

Best for: Most projects, standard Grid Building usage

Pros:

• Fully automated
• Preserves all functionality
• Handles edge cases
• Includes validation

Cons:

• Requires tool setup
• May need manual tweaks for custom code

Steps:

1. Prepare Your Project

   1 2	cd your_project git add -A && git commit -m "Before 6.0.0 migration"

2. Run Automated Migration

   1 2 3 4 5 6 7 8 9 10 11 12 13

   # Using the enhanced migration tool ./enhanced_migration \ --source ./addons/grid_building \ --target ./addons/grid_building_cs \ --config migration_config.toml \ --dry-run # Review the changes, then run for real ./enhanced_migration \ --source ./addons/grid_building \ --target ./addons/grid_building_cs \ --config migration_config.toml \ --execute

3. Update Project Settings

   1 2 3 4 5

   # Remove old GDScript addon rm -rf addons/grid_building # Rename C# addon to standard location mv addons/grid_building_cs addons/grid_building

4. Update Scene References

   1 2	# The migration tool handles this automatically # But verify all references are updated

Approach 2: Manual Migration

Best for: Highly customized projects, complex custom integrations

Pros:

• Full control over process
• Can handle complex customizations
• Better understanding of changes

Cons:

• Time-consuming
• Higher risk of errors
• Requires deep knowledge

Steps:

1. Install C# Grid Building 6.0.0

   • Download the C# version
   • Extract to addons/grid_building_cs/

2. Manually Port Custom Scripts

   • Review each GDScript file
   • Convert to C# equivalents
   • Update API calls

3. Update Scene Files

   • Change script references from .gd to .cs
   • Update property paths if needed

4. Test Incrementally

   • Test each component individually
   • Fix issues as they arise

Approach 3: Hybrid Migration

Best for: Projects with some customizations

Pros:

• Automated for standard parts
• Manual control for custom parts
• Balanced approach

Cons:

• More complex process
• Requires careful coordination

🛠️ Detailed Migration Process

Phase 1: Preparation

1.1 Project Analysis

1
2
3

# Analyze your current Grid Building usage
find . -name "*.gd" -path "*/grid_building/*" | wc -l
find . -name "*.tscn" -exec grep -l "grid_building" {} \; | wc -l

1.2 Dependency Check

• List all custom scripts that extend Grid Building classes
• Document custom property usages
• Note any API modifications you’ve made

1.3 Environment Setup

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Ensure .NET is available
dotnet --version

# Create migration configuration
cat > migration_config.toml << EOF
[migration]
enable_code_analysis = true
update_scene_references = true
preserve_uids = true

[output]
namespace_prefix = "YourProject"
target_language = "csharp"

[backups]
create_backups = true
backup_directory = "../migration_backups"

[validation]
enable_syntax_validation = true
check_godot_compatibility = true
EOF

Phase 2: Migration Execution

2.1 Backup Creation

1
2
3
4
5

# Create timestamped backup
BACKUP_DIR="../backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r addons/grid_building "$BACKUP_DIR/"
cp -r .git "$BACKUP_DIR/"  # if using git

2.2 Run Migration Tool

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Dry run to see what will change
./enhanced_migration \
  --source ./addons/grid_building \
  --target ./addons/grid_building_cs \
  --config migration_config.toml \
  --dry-run \
  --verbose

# Execute migration
./enhanced_migration \
  --source ./addons/grid_building \
  --target ./addons/grid_building_cs \
  --config migration_config.toml \
  --execute \
  --verbose

2.3 Post-Migration Steps

1
2
3
4
5
6
7
8

# Remove old addon
mv addons/grid_building addons/grid_building_old

# Move new addon to standard location
mv addons/grid_building_cs addons/grid_building

# Update project.godot if needed
# ( usually handled automatically )

Phase 3: Validation and Testing

3.1 Syntax Validation

1
2
3

# Build C# project to check for errors
cd addons/grid_building
dotnet build

3.2 Runtime Testing

1. Open Godot Editor
2. Wait for C# compilation (may take a few minutes)
3. Check for compilation errors
4. Test core functionality:
   • Grid placement
   • Item manipulation
   • Save/load systems
   • UI interactions

3.3 Performance Validation

• Test grid performance with large grids
• Compare memory usage
• Verify frame rates are maintained or improved

Expected Performance Improvements (based on official Godot benchmarks):

• Operations: 25-50% faster for arithmetic and logic [official benchmarks]
• Function calls: 30-150% faster (depending on argument validation) [official benchmarks]
• Built-in function calls: 25-50% faster [official benchmarks]
• Iteration: 10-50% faster for loops [official benchmarks]
• Property access: 5-7% faster [official benchmarks]

Note: Actual performance gains vary by use case. Much game logic leverages Godot’s C++ engine internals, which are already optimized.

🔧 Common Migration Issues

Issue 1: Missing References

Symptoms: “Can’t find class” errors Solution:

1
2
3

# Update scene references manually if needed
grep -r "res:/addons/grid_building/" scenes/ | \
  sed 's/grid_building\.gd/grid_building.cs/g'

Issue 2: API Changes

Symptoms: Method not found errors Solution: Check the API migration guide below

Issue 3: Property Type Changes

Symptoms: Type conversion errors Solution: Update property types in custom scripts

Issue 4: Namespace Issues

Symptoms: Using directive errors Solution: Add proper using statements:

1
2

using Godot;
using YourProject.GridBuilding;

📚 API Migration Reference

Class Name Changes

Important Note: in 6.0, placeables are Core-first:

• Core Layer: use GridPlacement.Core.Interfaces.IPlaceable for engine-agnostic logic
• Core Concrete Type: GridPlacement.Core.Types.Placeable is the standard implementation
• Godot Layer: may wrap / adapt Core placeables for instantiation, icons, and editor-facing resources

Method Signature Changes

Property Changes

Placeable Architecture Migration

The biggest architectural change in 6.0.0 is the separation of Placeable into distinct layers:

5.x (GDScript)

1
2
3
4

# 5.x uses a Godot Resource-style placeable
var placeable = Placeable.new()
placeable.id = "house_01"
placeable.scene_path = "res:/scenes/house.tscn"

6.0.0 (C# - Core-first Architecture)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

/ Core Layer - Engine-agnostic logic and UI
using GridPlacement.Core.Types;
using GridPlacement.Core.Interfaces;
 
IPlaceable placeable = new Placeable()
{
    Id = "house_01",
    Name = "Small House",
    FilePath = "scenes/house.tscn"  / Engine-agnostic path
};

/ UI Components work directly with Core Placeable
public void DisplayPlaceable(IPlaceable placeable)
{
    NameLabel.Text = placeable.Name;
    DescriptionLabel.Text = placeable.Description;
    / No engine dependencies in UI
}

Migration Steps for Placeable

1. Core Logic Migration

   1 2 3 4 5 6 7 8 9 10 11 12

   / Old (5.0.0) public void ProcessPlaceable(Placeable placeable) { / Engine-specific logic } / New (6.0.0) public void ProcessPlaceable(IPlaceable placeable) { / Engine-agnostic logic / Use placeable.Name, placeable.Size, etc. }

2. UI Migration

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   / Old (5.0.0) public void SetupUI(Placeable placeable) { / Direct access to engine properties } / New (6.0.0) public void SetupUI(IPlaceable placeable) { / Clean separation - UI uses Core interface NameText = placeable.Name; DescriptionText = placeable.Description; SizeDisplay = placeable.Size; }

3. Godot-Specific Operations

   1 2 3

   / Use PlaceableResourceHandler for engine operations var handler = new PlaceableResourceHandler(); var sceneInstance = handler.InstantiateScene(placeable.FilePath);

Benefits of This Change

• Clean Separation: UI doesn’t depend on Godot types
• Engine Agnostic: Core logic works with any engine
• Better Testing: Mock IPlaceable for unit tests
• Future-Proof: Easy to add new engine support

🧪 Testing Your Migration

Basic Functionality Test

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

/ Test script to verify basic migration
using Godot;

public class MigrationTest : Node
{
    public override void _Ready()
    {
        / Test grid building manager
        var manager = GetNode<GridBuildingManager>("/root/GridBuildingManager");
        GD.Print($"Grid size: {manager.GetGridSize()}");
        
        / Test placement
        var testItem = new Node();
        manager.PlaceItem(testItem, new Vector2(100, 100));
        
        GD.Print("✓ Basic migration test passed");
    }
}

Performance Benchmark

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

/ Performance comparison test
using Godot;
using System.Diagnostics;

public class PerformanceTest : Node
{
    public async void TestPerformance()
    {
        var stopwatch = Stopwatch.StartNew();
        
        / Test large grid operations
        for (int i = 0; i < 1000; i++)
        {
            / Perform grid operations
        }
        
        stopwatch.Stop();
        GD.Print($"1000 operations took: {stopwatch.ElapsedMilliseconds}ms");
    }
}

🔄 Rollback Plan

If migration fails, you can rollback:

Quick Rollback

1
2
3

# Restore from backup
cp -r ../backups/20231201_143000/grid_building addons/
git checkout HEAD~1 -- addons/grid_building

Complete Rollback

1
2
3

# Full project restore
git reset --hard HEAD~1
# or restore from complete backup

📞 Getting Help

Resources

• GitHub Issues: Report migration problems
• Discord Community: Get real-time help
• Documentation: Check API docs for specific issues
• Migration Tool Logs: Review detailed migration logs

Debug Information

1
2
3
4
5

# Enable verbose logging
./enhanced_migration --verbose --log-level debug > migration.log 2>&1

# Check migration report
cat migration_report.json

✅ Migration Checklist

Pre-Migration

• Project backed up
• Current version verified ( 5.0.0 )
• .NET SDK installed
• Godot Editor closed
• Migration tool ready
• Configuration file created

Migration

• Dry run completed successfully
• Migration executed without errors
• Old addon backed up
• New addon in place
• Scene references updated
• Project settings updated

Post-Migration

• C# project builds successfully
• Godot Editor opens without errors
• Basic functionality tested
• Performance verified
• Custom code ported
• Full integration tested
• Documentation updated

Final Steps

• Commit changes to version control
• Update project documentation
• Test on target platforms
• Deploy to staging environment
• Monitor for issues

🎉 Success!

Your project is now running Grid Building 6.0.0 with C#! Enjoy the improved performance and better development experience.

Next Steps

1. Explore new C# features: Take advantage of the new capabilities
2. Optimize performance: Use C# profiling tools
3. Enhance debugging: Use Visual Studio or Rider for debugging
4. Contribute back: Share improvements with the community

Need help? Check the troubleshooting section or create an issue on GitHub.

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. In 6.0, GridPlacement / GP is canonical across docs, assemblies, and C# namespaces, but the legacy 5.x GDScript addon folder path remains res:/addons/grid_building/ for compatibility.

🎯 What’s Changing?

GridPlacement 6.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 (GridPlacement.Core.dll)

   • Place GridPlacement.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 GridPlacement.Core types.

3. Install the Godot‑side plugin

   • Copy the GridPlacement 6.0 Godot plugin into:
     • res:/addons/grid_building/ (folder name retained for 5.x compatibility).
   • 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.