This guide helps you migrate from 4.x/5.x to 6.0.0.
⚠️ Major Architectural Changes
Grid Building 6.0 introduces a complete architectural overhaul based on pure ECS (Entity Component System). This is not a minor update — your scenes will need to be restructured.
What’s Different in 6.0
| Aspect | v5.0 (Base) | v6.0 (ECS) |
|---|---|---|
| Architecture | RefCounted objects with loose structure | Pure ECS (Entity Component System) |
| Integration | Add nodes to your scene | ECS systems and components |
| State Management | RefCounted-based, loosely coupled | ECS component data, tightly structured |
| SRP Violation | States included logic + signals | ECS separates data from systems |
| Plugin Path | addons/grid_building/ | addons/grid_building_ecs/ |
Migration Approach
- Templates — We provide pre-configured scene templates that set up the new ECS architecture correctly
- Step-by-step — Each integration step is documented with before/after examples
- Validation — Built-in validation helps catch configuration issues
📖 Getting Started
🚀 New to v6.0? Start with the comprehensive 6.0 Guides section — it includes step-by-step setup, troubleshooting, and examples.
🔧 Need specific technical details?
- Architecture Overview — Updated architecture and integration patterns
Why the Big Change?
The v6.0 pure ECS architecture solves long-standing issues:
- Single Responsibility — ECS cleanly separates data (components) from logic (systems)
- Testability — ECS logic is data-driven and easy to test
- Performance — ECS pattern reduces overhead and improves frame times
- Maintainability — Clear separation between components and systems
- Flexibility — Data-oriented design makes complex building rules easier to express
While the migration requires restructuring, the resulting code is cleaner, faster, and more maintainable.