Migration Guide: 5.0.0 to 6.0.0

This guide provides a comprehensive approach for migrating your Grid Building projects from version 5.0.0 to 6.0.0, including the major architectural change from PlaceableDefinition to IPlaceable interface.

🎯 Overview

What’s Changing in 6.0.0

• Architecture Migration: PlaceableDefinition moved from Core to Godot-specific layer
• Interface Introduction: IPlaceable interface 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.0.0
   • 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.0.0 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.

6. 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.0.0 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.

   • CRITICAL: Close Godot completely before migration

   • This prevents file locking and corruption

🔄 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: PlaceableDefinition has been split:

• Core Layer: Use IPlaceable interface for engine-agnostic logic
• Godot Layer: Use PlaceableDefinition for Godot-specific operations
• UI Components: Work directly with GridBuilding.Core.Types.Placeable class

Method Signature Changes

Property Changes

PlaceableDefinition Architecture Migration

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

5.0.0 (GDScript)

1
2
3
4

# Single class for all placeable operations
var placeable = PlaceableDefinition.new()
placeable.id = "house_01"
placeable.scene = "res://scenes/house.tscn"

6.0.0 (C# - Layered Architecture)

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

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

// Godot Layer - Engine-specific operations
using GridBuilding.Godot;
var godotPlaceable = new PlaceableDefinition()
{
    Id = "house_01",
    Scene = "res://scenes/house.tscn"  // Godot-specific 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 PlaceableDefinition

1. Core Logic Migration

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

   // Old (5.0.0) public void ProcessPlaceable(PlaceableDefinition def) { // 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(PlaceableDefinition def) { // 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.