After months of careful development and community feedback, Grid Building 5.0.0 is here with a complete dependency injection system, thoroughly validated collision mapping, and significant reliability improvements. This release focuses on making integration easier, more reliable, and more maintainable.
🔗 New Documentation Hub
Visit our comprehensive new documentation site: gridbuilding.pages.dev
Built with Astro and Starlight, featuring:
- Interactive API documentation with live examples
- Step-by-step integration guides for all major use cases
- Migration guides to help transition from 4.3.1
- Enhanced search and cross-referencing
- Version-specific documentation to maintain compatibility
🚀 Complete Dependency Injection System
The cornerstone of Grid Building 5.0.0 is a complete dependency injection architecture that eliminates configuration complexity and ensures reliable component initialization.
Key Components
GBCompositionContainer:
- Centralized dependency container for all Grid Building systems
- Provides unified access to settings, states, and systems
- Eliminates scattered export variables across components
GBInjectorSystem:
- Automatically injects dependencies into all scene nodes
- Calls
resolve_gb_dependencies() on components during initialization
- Provides centralized logging via
GBLogger
- Validates dependencies immediately after injection
What Changed:
- ❌ Before: Manual export variables in every component
- ✅ After: Automatic dependency injection through
GBCompositionContainer
- ❌ Before: Resources assigned in inspector
- ✅ After: Runtime objects managed by dependency injection
- ❌ Before: Scattered
print() statements
- ✅ After: Centralized
GBLogger for consistent diagnostics
📖 Learn more: Dependency Injection Guide
Automatic Validation System (NEW)
Grid Building 5.0.0 now automatically validates all runtime dependencies immediately after injection through GBInjectorSystem.
Key Changes:
- Removed manual validation methods:
validate_runtime_deferred(), _validate_after_injection(), validate_runtime_configuration()
- Automatic validation: GBInjectorSystem validates all components after dependency injection
- Cleaner code: No validation boilerplate needed in
_ready() methods
Benefits:
- Zero-configuration validation - No manual validation calls needed
- Immediate error detection - Issues caught right after injection
- Consistent validation patterns - All systems validated the same way
- Better error messages - Validation happens with full context
📖 Learn more: Dependency Injection Lifecycle
🎯 Enhanced Collision Mapping Logic
Grid Building 5.0.0 introduces thoroughly validated collision detection that handles edge cases and complex scenarios:
Robust Collision Detection
Advanced Shape Handling:
- Multi-shape collision support for complex building footprints
- Precise edge case handling for overlapping geometries
- Optimized physics queries with intelligent caching
- Validated collision mathematics backed by comprehensive tests
Separation of Concerns Architecture
Grid Building 5.0.0 introduces clear architectural boundaries between positioning, collision detection, and visual feedback systems:
- GridPositioner2D - Pure input handling and positioning
- TargetingShapeCast2D - Dedicated collision detection
- IndicatorManager - Visual feedback and validation
Benefits:
- Unit testable components - Each system tested in isolation
- Composable collision strategies - Swap targeting implementations
- Eliminated race conditions - No hidden coupling between systems
- Reliable testing - Comprehensive automated test coverage
📖 Learn more: Collision Mapping Guide
📦 Getting Started with Grid Building 5.0.0
Quick Setup Overview:
1. Install the Plugin
Download Grid Building 5.0.0 from the Godot Asset Library or itch.io and enable it in your project settings.
2. Set Up Template Scenes
The plugin includes pre-configured template scenes with dependency injection already wired:
- Use the Placeable Selection UI template from
res://addons/grid_building/templates/
- Add GBLevelContext to your game level (contains TileMapLayer reference)
- Add GBOwnerContext as a child of your player/character node
- Configure your TileMapLayer with proper collision layers
Template scenes include:
- Complete system setup with dependency injection
- Pre-configured UI with two professional themes (Cool Blue, Warm Earth)
- Ready-to-use building, targeting, and manipulation systems
3. Configure Placeables
Create Placeable resources for each object you want to build:
- Set the packed_scene property to your building’s scene
- Assign CategoricalTag resources to the
tags array to organize placeables into UI tabs
- Configure placement_rules as needed for object-specific validation
- Reference the placeables path in your Placeable Selection UI
📖 Complete setup guide: Getting Started Guide
The dependency injection system handles component wiring automatically, but you’ll need to configure your buildable objects and UI organization.
🎯 BuildType Enum (NEW)
Grid Building 5.0.0 replaces the boolean dragging flag with a type-safe BuildType enum:
BuildType Values:
SINGLE - Single-tile placementDRAG - Multi-tile drag-to-buildAREA - Area selection (reserved for future use)
Benefits: Type safety, better IDE support, extensible for new build modes (FILL, CLEAR, PAINT)
📖 Learn more: Breaking Changes - BuildType Enum
Note: This is a breaking change requiring code updates. See the migration section below.
🔧 Enhanced Validation & Reporting
IndicatorSetupReport System
Placement validation now returns structured IndicatorSetupReport objects providing detailed diagnostics, performance metrics, and enhanced error reporting.
📖 Learn more: IndicatorSetupReport Guide
ValidationResults Improvements
The validation system now provides structured ValidationResults objects with rich diagnostic feedback.
📖 Learn more: Placement Rules Guide
🧪 Quality & Reliability
Grid Building 5.0.0 is backed by comprehensive quality assurance:
- 1540 test scenarios at 100% pass rate (1410 core plugin tests + 130 demo/misc tests)
- Complete validation across collision, positioning, rules, and building systems
- Regression prevention for known edge cases
- Continuous quality monitoring to maintain plugin stability
These improvements ensure the plugin works reliably in your projects, with edge cases handled gracefully.
📋 Migration Guide from 4.3.1
Quick Migration Summary
What Stayed the Same:
- Placeables work essentially the same way as before
- Building system entry points mostly unchanged - UI integration patterns work as before
- Core building workflow remains familiar to existing users
What Changed:
- New project templates need to be brought into existing projects
- GBInjectorSystem must exist in scenes for dependency injection
- BuildType enum system replaces boolean
dragging flag
- Automatic validation removes manual validation method calls
- GridPositioner2D architecture uses clearly defined child components
For Complete Details:
Key Benefits of Upgrading
-
Type-Safe Build Modes:
- Clear, self-documenting
BuildType enum (SINGLE, DRAG, AREA)
- Compile-time type checking prevents invalid build modes
-
Automatic Validation:
- No manual validation calls needed in
_ready() methods
- GBInjectorSystem handles validation automatically after dependency injection
-
Enhanced Error Reporting:
- Structured
IndicatorSetupReport with diagnostic information
- Better debugging support with detailed context
-
Improved Collision Accuracy:
- Automatic collision validation and edge case handling
- Better performance with intelligent caching
- Comprehensive testing ensures reliability (1540 tests at 100% pass rate)
-
Better Debugging Support:
- Runtime validation warns about configuration issues
- Enhanced diagnostic output for troubleshooting
- Stack trace formatting for easier debugging
- Comprehensive docstring coverage across all systems
-
Ready-to-Use UI Themes:
- Cool Blue Theme - Professional blue/cyan color scheme
- Warm Earth Theme - Warm brown/orange palette
- Pre-configured themes for quick UI prototyping
- Try UI elements immediately without custom styling
🔧 Reliability Improvements
Grid Building 5.0.0 includes significant reliability enhancements based on extensive testing and real-world usage:
Enhanced Error Handling
Runtime Validation:
- Automatic dependency verification prevents silent failures
- Graceful degradation when optional components are missing
- Clear error messages with actionable troubleshooting steps
- Stack trace integration for rapid debugging in production
Architectural Improvements
Clean Separation of Concerns:
- Independent positioning system - No hidden dependencies on collision detection
- Composable targeting strategies - Easy to swap or extend collision methods
- Isolated validation logic - Each rule validates independently
- Modular UI components - Mix and match UI elements as needed
Stability Enhancements
Eliminated Race Conditions:
- Predictable initialization order via dependency injection
- No timing-dependent behavior in core systems
- Atomic state updates for manipulation operations
- Consistent frame-perfect input handling
Better Memory Management:
- Automatic cleanup of temporary objects
- No circular references between components
- Proper signal disconnection on component removal
- Resource pooling for frequent allocations
Edge Case Protection (NEW)
Automatic Cancellation on Source Deletion:
Grid Building 5.0.0 now gracefully handles edge cases where objects are deleted during active manipulations. When moving an object, if the source gets deleted unexpectedly (by game logic, AI systems, or user actions), the manipulation system automatically:
- Cancels the manipulation - No manual intervention required
- Cleans up preview copies - Prevents orphaned nodes in the scene tree
- Frees placement indicators - Visual feedback elements are properly removed
- Maintains consistent state - System returns to idle without artifacts or memory leaks
This signal-based architecture ensures robust behavior even when game logic or external systems delete objects unexpectedly during manipulation operations.
📖 Learn more: Manipulation System - Automatic Cancellation