Skip to content
Grid Building Docs

GBMetadataResolver

Summary

Section titled “Summary”

Utility for resolving Grid Building metadata on nodes.

Provides metadata resolution for root node targeting and display name features. This class is stateless and all methods are static for maximum reusability.

Supported Metadata:

  • root_node: Specifies the logical root Node2D for targeting - display_name: Custom display name for UI

Methods

Section titled “Methods”
static func resolve_root_node( collision_object: CollisionObject2D ) -> Node2D

Resolves the root node for a collision object by checking metadata and Manipulatable components. Uses a priority search strategy for flexible targeting:

Search priority:

  1. Check collision object directly for “root_node” metadata (Node2D or NodePath)

  2. Search sibling nodes for Manipulatable component (uses Manipulatable.root)

  3. Search direct children (1 level deep) for Manipulatable component

  4. Search entire scene tree from root for Manipulatable component (hierarchy-independent)

  5. Return collision object if no metadata or Manipulatable found

collision_object: The CollisionObject2D to start searching from

Returns: The resolved root node (Node2D) or the collision object itself

static func _find_scene_root( node: Node ) -> Node

Finds the scene root by traversing up the tree to the top-most parent. The scene root is the highest parent node in the scene tree hierarchy.

node: Starting node to traverse from Returns: The scene root node, or null if node is null

static func _find_manipulatable_in_tree( node: Node ) -> Manipulatable

Recursively searches for the first Manipulatable component in the scene tree. Uses depth-first search to find any Manipulatable anywhere in the hierarchy.

node: Root node to start searching from Returns: The first Manipulatable found, or null if none found

static func resolve_manipulation_target( collision_object: CollisionObject2D ) -> Dictionary

Resolves BOTH the root node AND Manipulatable component from a collision object. This is the recommended method for manipulation systems to avoid duplicate resolution.

Uses the same 5-priority search as resolve_root_node(), but returns both components in a single pass for efficiency.

collision_object: The CollisionObject2D to resolve from

Returns: Dictionary with keys: “root” (Node2D) and “manipulatable” (Manipulatable or null)

static func resolve_display_name( node: Node, fallback: String ) -> String

Resolves display name for a node using multiple resolution strategies.

Priority order:

  1. get_display_name() method (if exists on node)

  2. display_name property (if exists on node)

  3. metadata/display_name (if present, non-empty string/StringName)

  4. node.name (standard node name)

  5. Fallback value (if node is null or has no name)

Accepts String or StringName for all display name sources.

node: The node to get display name for fallback: Value to return if node is null or has no valid name (default: “<none>”) Returns: The resolved display name string

Source

Section titled “Source”

addons/grid_building/utils/gb_metadata_resolver.gd

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