Skip to content
Grid Building Docs

GBPlacementPersistence

Summary

Section titled “Summary”

Utility class for managing placement persistence using metadata

Replaces the PlaceableInstance component node with a lightweight metadata-based approach. This provides the same functionality without scene tree pollution and hidden nodes.

METADATA-BASED APPROACH: - Marks placed objects using node metadata (gb_placement) - Stores placeable resource reference for save/load operations - Static utility methods for consistency with other GB utilities

USAGE PATTERNS:

Marking an object as placed:

GBPlacementPersistence.mark_as_placed(instance, placeable)

Checking if an object is placed:

if GBPlacementPersistence.is_placed(node):
    var placeable = GBPlacementPersistence.get_placeable(node)

Save/load operations:

# Save
var save_data = GBPlacementPersistence.save_placement_data(node, true)


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

Batch operations:

# Save all placements in hierarchy
var all_saves = GBPlacementPersistence.save_all_placements(root_node, true)


# Load all placements
var loaded = GBPlacementPersistence.load_all_placements(all_saves, parent)

Methods

Section titled “Methods”
static func mark_as_placed( p_node: Node, p_placeable: Placeable ) -> void

Marks a node as placed by the building system

Stores placement metadata including reference to the source Placeable resource. This metadata is used for save/load operations and identification of placed objects.

p_node: The node to mark as placed p_placeable: The Placeable resource that was used to create this instance

static func is_placed( p_node: Node ) -> bool

Checks if a node has been marked as placed

p_node: The node to check Returns: True if the node has placement metadata, false otherwise

static func get_placeable( p_node: Node ) -> Placeable

Retrieves the Placeable resource associated with a placed node

p_node: The placed node Returns: The Placeable resource, or null if not found or node not marked as placed

static func is_preview( p_node: Node ) -> bool

Checks if a node is a preview object (should be excluded from save operations)

Preview objects are marked with “gb_preview” metadata by the building/manipulation systems.

p_node: The node to check Returns: True if the node has preview metadata, false otherwise

static func save_placement_data( p_node: Node ) -> Dictionary

Saves placement data for a single node

Creates a dictionary containing all data needed to recreate the placed object: - Instance name (for identification) - Transform (position, rotation, scale) - Placeable resource reference (for instantiation)

Returns empty dictionary if node is not marked as placed.

p_node: The placed node to save Returns: Dictionary containing save data, or empty dict if not a placed object

static func save_all_placements( p_root: Node ) -> Array[Dictionary]

Saves placement data for all placed objects in a node hierarchy

Recursively searches for placed objects and creates save data for each. Automatically excludes preview objects (marked with “gb_preview” metadata).

p_root: The root node to search from Returns: Array of save data dictionaries for all placed objects

static func instance_from_save( p_save_data: Dictionary, p_parent: Node ) -> Node

Instances a placed object from save data

Creates a new instance from the saved Placeable resource, applies the saved transform, and marks it as placed with appropriate metadata.

Returns null if save data is invalid or Placeable resource cannot be loaded.

p_save_data: Dictionary containing save data (from save_placement_data()) p_parent: Parent node to add the instance to Returns: The created instance, or null if instantiation failed

static func load_all_placements( p_save_data_array: Array[Dictionary], p_parent: Node ) -> Array[Node]

Loads multiple placed objects from an array of save data

Convenience method for batch loading operations.

p_save_data_array: Array of save data dictionaries p_parent: Parent node to add all instances to Returns: Array of created instances (may contain nulls if some loads failed)

static func get_placed_objects( p_root: Node ) -> Array[Node]

Gets all placed objects in a node hierarchy

Recursively searches for nodes with placement metadata. Automatically excludes preview objects.

p_root: The root node to search from Returns: Array of all placed nodes found in hierarchy

static func _collect_placed_objects_recursive( p_node: Node, p_result: Array[Node] ) -> void

Recursive helper for get_placed_objects()

Source

Section titled “Source”

addons/grid_building/utils/gb_placement_persistence.gd

This API reference is automatically generated from the plugin source code. For implementation examples and usage guides, see the guides section.