Skip to content
Grid Building Docs

v5.1.0 Placement Persistence Changes

Overview

Section titled “Overview”

Version 5.1 introduces improvements to placement persistence with a more robust metadata-based approach.

Placement Persistence: Component to Metadata Migration

Section titled “Placement Persistence: Component to Metadata Migration”

What Changed

Section titled “What Changed”

The placement tracking system has been completely rewritten to use metadata instead of a hidden component node (PlaceableInstance).

Previous Approach (v5.0.0 and earlier):

  • Added a hidden PlaceableInstance component node to placed objects
  • Required add_placeable_instance setting in BuildingSettings
  • Added extra nodes to the scene tree
  • Not visible or intuitive to developers

New Approach (v5.1+):

  • Uses lightweight metadata key "gb_placement" on placed objects
  • No extra nodes in scene tree
  • Fully transparent - visible in Godot’s inspector with metadata plugins
  • Simpler API through static utility class GBPlacementPersistence

Why This is a Minor Change

Section titled “Why This is a Minor Change”

This is considered a minor version change (not a breaking change) because:

  1. Hidden Feature: The PlaceableInstance component was poorly documented and not part of the main public API
  2. Side Feature: Placement persistence was an optional, secondary feature primarily used for save/load systems
  3. Automatic Migration: The building system automatically marks all placed objects - no code changes required for basic placement
  4. Improved Design: The new approach is objectively better (lighter weight, more transparent, easier to use)

Impact Assessment

Section titled “Impact Assessment”

Most Users: ✅ No impact - If you were just using the building system to place objects, everything works the same

Save/Load Users: ⚠️ Requires Update - If you implemented custom save/load systems using PlaceableInstance, you’ll need to migrate to GBPlacementPersistence

See the Placement Persistence Guide for complete migration instructions and examples.

Changes Summary

Section titled “Changes Summary”

Removed

Section titled “Removed”
  • ❌ BuildingSettings.add_placeable_instance property (removed completely)
  • ❌ PlaceableInstance component class (removed completely - no deprecation period)
    • Rationale: Internal, undocumented class not part of the public API

Added

Section titled “Added”
  • ✅ GBPlacementPersistence static utility class
  • ✅ Metadata key "gb_placement" for tracking placed objects
  • ✅ Automatic placement marking in BuildingSystem
  • ✅ Comprehensive placement persistence API

Migration Path

Section titled “Migration Path”

If you were using PlaceableInstance for save/load:

Old Code (v5.0.0):

# Save
var placeable_nodes = get_tree().get_nodes_in_group(PlaceableInstance.group_name)
for node in placeable_nodes:
    var save_data = node.save(true)
    # ... store save_data


# Load
var instance = PlaceableInstance.instance_from_save(save_data, parent)

New Code (v5.1+):

# Save
var save_data_array = GBPlacementPersistence.save_all_placements(root_node)
# ... store save_data_array


# Load
GBPlacementPersistence.load_all_placements(save_data_array, parent_node)

See the Placement Persistence Guide for complete examples.

Benefits of the New Approach

Section titled “Benefits of the New Approach”

Performance

Section titled “Performance”
  • No extra nodes: Metadata adds zero scene tree overhead
  • Faster queries: Direct metadata checks instead of node searches

Transparency

Section titled “Transparency”
  • Visible in inspector: Metadata visible with Godot’s metadata inspector plugins
  • Clear API: Static utility methods make the system obvious

Simplicity

Section titled “Simplicity”
  • No lifecycle management: No need to worry about node parenting or cleanup
  • Pure static API: No dependency injection or component initialization needed

Maintainability

Section titled “Maintainability”
  • Single source of truth: All placement logic in one utility class
  • Easier testing: Simple static methods are trivial to test
  • Better documentation: Clear, focused API surface

Documentation

Section titled “Documentation”

Removal Timeline

Section titled “Removal Timeline”
  • v5.1: PlaceableInstance completely removed (no deprecation period)

The PlaceableInstance component was an internal, poorly documented class that was never part of the official public API. Its removal is considered a minor change rather than a breaking change since:

  1. It was never documented in user guides
  2. It was primarily used internally by the building system
  3. Most users never directly interacted with it
  4. The new metadata approach is superior in every way

If you were using PlaceableInstance in custom save/load code, migrate to GBPlacementPersistence immediately using the examples in the Placement Persistence Guide.