Extending the Plugin

The Grid Building plugin provides foundational building mechanics - placement, validation, collision detection, and visual feedback. This guide explains how to extend the plugin with game-specific features while maintaining clear boundaries between core plugin functionality and custom game logic.

Plugin Scope vs Game-Specific Features

✅ What the Plugin Provides (Core Features)

Core Building Mechanics:

• Grid-based placement system
• Collision detection and validation
• Visual indicators (valid/invalid placement)
• Rule-based placement validation
• Mouse and keyboard input handling
• Scene tree management for building objects

Architecture Components:

• BuildingSystem - Core placement logic
• GridPositioner2D - Input handling and positioning
• PlacementValidator - Rule validation system
• CollisionMapper - Collision detection
• IndicatorManager - Visual feedback
• ManipulationSystem - Object selection and manipulation

UI Templates (Advanced):

• PlaceableSelectionUI - Unified selection interface supporting both individual placeables and sequences
• PlaceableSequence - Groups building variants for selection (Basic Tower → Heavy Tower → Rapid Tower)
• PlaceableList - Manages collections of placeables with variant cycling support

❌ What the Plugin Does NOT Provide (Game-Specific)

Visual Representation & Rendering:

• Sprite management and directional artwork
• 3D model rotation and orientation
• Animation systems (idle, building, destruction)
• Visual effects (particles, lighting, shaders)
• Sprite swapping for directional buildings (e.g., isometric 4/8-directional sprites)

Economy & Progression:

• Resource management and costs
• Building upgrade systems
• Tech trees and unlock progression
• Economy balancing (gold, wood, stone costs)

Game Systems:

• Combat stats and damage systems
• Unit production queues
• Defensive bonuses and area effects
• Building health and destruction

Persistence & State:

• Save/load system for game progress
• Cloud saves and data persistence
• Achievement tracking
• Statistics and analytics

UI Styling & Custom Layouts:

• Custom themed UI components
• Radial menus or non-grid selection
• HUD integration and minimap systems
• Game-specific input handling (RTS controls, mobile touch patterns)

Why?

• Scope Management: Keeps plugin focused and maintainable
• Game Flexibility: Each game needs different implementations
• Performance: Games optimize differently based on their needs
• Design Freedom: Doesn’t impose visual or gameplay constraints

🏧 Architectural Boundaries

Core Plugin Scope

The Grid Building plugin provides foundational systems and UI templates for building placement:

Always in Core:

• Grid positioning and movement
• Collision detection and validation
• Placement rules and constraints
• Basic visual feedback (indicators)
• Scene management and object manipulation

UI Templates (Use or Customize):

• Unified selection interface (PlaceableSelectionUI) - handles both individual placeables and sequences
• Building variant grouping (PlaceableSequence) - organize related building variants
• Collection management (PlaceableList) - manage available placeables with cycling support

Game-Specific Extensions (Always Custom):

• Building upgrade systems and progression trees
• Resource costs and economy mechanics
• Combat stats and game balance
• Save/load systems for game progress
• Themed UI styling and custom layouts

Template vs Custom Decision

Use Plugin Templates When:

• Standard building selection patterns fit your game
• You want rapid prototyping with working UI
• Your design aligns with template assumptions
• You need keyboard/controller navigation

Build Custom Implementation When:

• Your UI patterns differ significantly from templates
• You need integration with complex game systems
• Performance requirements demand specialized solutions
• Your artistic vision requires completely custom styling

🏷️ Distinguishing Temporary Preview Objects

The gb_preview Metadata Flag

The plugin automatically marks temporary preview and manipulation objects with metadata that allows you to distinguish them from permanent objects in your scene. This is especially important when implementing save/load systems or scene analysis tools.

What Gets Tagged:

• Building System Previews: Objects created during build mode preview (before placement confirmation)
• Manipulation Copies: Temporary objects created when moving existing buildings

How It Works: The plugin sets a metadata flag on the root node of temporary objects:

# Plugin automatically sets this on previews and manipulation copies
preview_node.set_meta("gb_preview", true)

Use Cases

1. Save/Load Systems

When saving your game state, filter out temporary previews so they don’t get persisted:

func save_level() -> Dictionary:
  var placeable_nodes : Array[Node] = get_tree().get_nodes_in_group("PlaceableInstance")
  var saved_objects : Array[Dictionary] = []

  for node in placeable_nodes:
    var parent_node : Node = node.get_parent()

    # Skip temporary preview objects - they shouldn't be saved
    if parent_node != null && parent_node.has_meta("gb_preview"):
      continue

    # Save permanent objects only
    saved_objects.append(node.save(true))

  return {"objects": saved_objects}

2. Scene Analysis Tools

When building editor tools or debug visualizers, exclude temporary objects:

func analyze_placed_buildings() -> Dictionary:
  var buildings : Array[Node] = get_tree().get_nodes_in_group("Building")
  var permanent_buildings : Array[Node] = []

  for building in buildings:
    # Skip temporary previews during analysis
    if building.has_meta("gb_preview"):
      continue

    permanent_buildings.append(building)

  return {
    "count": permanent_buildings.size(),
    "buildings": permanent_buildings
  }

3. Gameplay Systems

Ensure AI, pathfinding, or other gameplay systems ignore temporary previews:

func find_enemy_targets() -> Array[Node]:
  var all_buildings : Array[Node] = get_tree().get_nodes_in_group("Building")
  var valid_targets : Array[Node] = []

  for building in all_buildings:
    # Don't target temporary previews or manipulation copies
    if building.has_meta("gb_preview"):
      continue

    valid_targets.append(building)

  return valid_targets

Best Practices

✅ Always Check Preview Metadata When:

• Implementing save/load systems
• Building scene analysis or debug tools
• Creating AI targeting systems
• Counting permanent buildings for game logic
• Serializing scene state for any purpose

✅ No Manual Management Needed: The plugin automatically handles setting and clearing this metadata - you only need to check for its presence when filtering objects.

✅ Works Across Systems: The gb_preview flag works consistently for both:

• Building system previews (during placement)
• Manipulation system copies (during move operations)

Migration Note

If you’re upgrading from an older version that used string-based name checking (e.g., checking for “ManipulationCopy” in node names), migrate to the metadata approach for more robust filtering:

# ❌ Old approach (fragile, name-dependent)
if "ManipulationCopy" in building.name or "Preview" in building.name:
  continue

# ✅ New approach (robust, metadata-based)
if building.has_meta("gb_preview"):
  continue

UI Templates vs Game-Specific Implementation

🎨 What UI Templates Provide

The plugin includes advanced UI templates for common building game patterns:

Unified Selection System:

• PlaceableSelectionUI - Grid-based selection interface that automatically handles both individual placeables and sequences
• PlaceableSequence - Groups multiple building variants (Basic Tower → Heavy Tower → Rapid Tower)
• PlaceableList - Collection management with variant cycling through sequences

When to Use Templates:

• Your game has building variants that players select before placement
• You prefer list-based UI over grid-based selection
• You need keyboard navigation and variant cycling
• You want to group related buildings together

When to Build Custom:

• Your game uses fundamentally different UI patterns (radial menus, drag-drop, etc.)
• You need variant selection during placement rather than before
• Your upgrade system works differently than variant selection
• You prefer complete control over UI styling and behavior

🔄 Template vs Custom Decision Matrix

Feature	Use Template	Build Custom
Grid-based selection (individual or sequences)	✅	❌
Building variants with left/right cycling	✅	❌
Automatic handling of placeables vs sequences	✅	❌
Radial menus or drag-drop interfaces	❌	✅
In-placement variant switching	❌	✅
Heavily themed/styled UI	❌	✅
Complex upgrade trees	❌	✅

Implementation Guidelines

🎯 Core Principle: Composition Over Extension

✅ Recommended Approach: Create wrapper classes that compose with plugin systems rather than extending them. Build game-specific managers that delegate core functionality to plugin components while adding custom validation, resource checks, and game logic on top.

Pattern: Composition wrapper that:

• Maintains references to plugin systems
• Implements game-specific state (quantities, unlocks, resources)
• Validates game conditions before delegating to plugin
• Adds custom checks and business logic around plugin calls

❌ Avoid Direct Plugin Modification:

# Don't modify plugin classes directly
class_name CustomBuildingSystem extends BuildingSystem:
    # This creates maintenance burden and update conflicts

Game-Specific Feature Implementation

1. Building Variants

Problem: Single building type with multiple visual/functional variants

Example Use Case: Select ‘Cannon Tower’, then use left/right arrows to choose between ‘Basic’, ‘Heavy’, or ‘Rapid-Fire’ variants before placing it on the grid.

Template Solution: Use the plugin’s PlaceableSequence system with PlaceableSelectionUI for ready-made variant selection.

Custom Solution: Create a variant selection manager that tracks current selections and updates Placeable resources dynamically.

Implementation Pattern (Custom):

• Create a variant manager class that maintains dictionaries of available variants and current selections
• Store variant definitions with scene paths, stats, and display information
• Implement cycling functions that update the active variant for each building type
• Modify placeable resources at runtime to reflect the selected variant
• Add UI controls (arrows, dropdowns) that call variant cycling functions
• Connect UI signals to variant selection logic

Template Integration:

• Create PlaceableSequence resources with multiple Placeable variants
• Add sequences to a PlaceableList alongside individual placeables
• Pass the list to PlaceableSelectionUI - it automatically handles both types
• Configure category tags to organize sequences into tabs
• The template handles variant cycling and selection automatically for sequences

Integration Points:

• Modify Placeable resources dynamically based on selected variant
• Use plugin’s existing placement system with variant-specific scenes
• Handle variant persistence in save/load system

2. Quantity Limits

Problem: Restrict number of buildings that can be placed (resource management)

Example Use Case: Limit players to 3 defensive towers, forcing strategic placement decisions.

Template Solution: The plugin’s UI templates don’t include quantity management - this is considered game-specific logic.

Custom Solution: Create a building quota system that tracks placed objects and prevents placement when limits are reached.

Implementation Pattern:

• Create a quota manager that maintains building type counts and limits
• Store quota definitions with maximum allowed quantities
• Implement validation functions that check current counts against limits
• Modify placement validation to include quota checks
• Add UI indicators showing current/maximum quantities
• Update building counters when objects are placed or removed
• Provide feedback when placement is blocked by quotas

3. Building Upgrades

Problem: Upgrade existing buildings to more powerful variants

Example Use Case: Upgrade a ‘Small Barracks’ to a ‘Large Barracks’ that can spawn more units or has additional features.

Solution: Create an upgrade manager that uses the plugin’s manipulation and placement systems for seamless building replacement.

Implementation Pattern:

• Define upgrade paths and costs in dictionary structures
• Create validation functions that check upgrade availability and resource requirements
• Use ManipulationSystem to remove the current building
• Leverage BuildingSystem to place the upgraded version at the same position
• Transfer persistent data (health, experience, etc.) between old and new buildings
• Display upgrade UI panels when buildings are selected
• Handle resource deduction and failure rollback scenarios

Integration Points:

• Use plugin’s ManipulationSystem for building selection
• Leverage BuildingSystem for placement validation
• Integrate with existing placement rules and collision detection

4. Unlockable Recipes

Problem: Dynamic building availability based on game progression

Example Use Case: After wave 10, unlock the ‘Missile Silo’ building; or, after researching a tech, add ‘Shield Generator’ to the build list.

Solution: Create a progression-based unlock system that dynamically manages available buildings and integrates with existing UI components.

Implementation Pattern:

• Maintain arrays of unlocked buildings and dictionaries of unlock conditions
• Define complex conditions based on game progression (waves, research, resources spent)
• Implement condition checking that evaluates multiple criteria
• Filter available buildings before passing them to plugin systems
• Dynamically add UI elements when new buildings are unlocked
• Load placeable resources on-demand when unlocks occur
• Display unlock notifications and update UI availability in real-time

Integration Points:

• Filter available buildings before passing to plugin systems
• Use existing BuildingSystem placement logic
• Connect unlock events to game progression systems

Custom Integration Patterns

Resource Management Integration

Create resource-aware wrapper classes that check costs and availability before delegating to plugin placement systems. Implement cost validation, resource deduction, and failure rollback patterns.

Save/Load Integration

Implement save managers that serialize both plugin state and game-specific data. Use plugin-provided state export/import methods combined with custom game progression data.

Best Practices

1. Maintain Plugin Boundaries

• Never modify plugin source files directly
• Use composition and delegation patterns
• Extend functionality through events and signals

2. Use Plugin Extension Points

Connect to plugin signals for placement events, selection changes, and system state updates. This provides clean integration points without modifying plugin code.

3. Custom Validation Rules

Extend the PlacementRule base class to create game-specific validation logic that integrates seamlessly with the existing validation pipeline.

4. UI Integration Patterns

Wrap or enhance plugin UI components with additional controls for variants, resources, upgrades, and other game-specific features.

Conclusion

The Grid Building plugin provides a solid foundation for grid-based building mechanics. By following these patterns, you can implement sophisticated game-specific features while maintaining the plugin’s simplicity and your game’s flexibility.

Key Takeaways:

• Compose, don’t modify: Build around the plugin, not into it
• Use provided extension points: Signals, custom rules, and UI enhancement
• Separate concerns: Keep game logic separate from core building mechanics
• Maintain upgrade path: Avoid changes that prevent plugin updates

This approach ensures your game can leverage the plugin’s robust foundation while implementing unique gameplay features that match your vision.