Skip to content
Grid Building Docs

GridTargetingState

Summary

Section titled “Summary”

State for targeting objects within the Grid Building System.

Signals

Section titled “Signals”
signal ready_changed( value: bool )

Emitted when the readiness status of the state has changed - usually after successful validation.

signal target_changed( new: Node2D, old: Node2D )

Emitted when the target node changes. The “target” is the resolved logical root object (for display/manipulation/game logic).

:::note[Note] Target is automatically resolved from the collision object via GBMetadataResolver. Use get_target() to access the resolved target. :::

signal positioner_changed( positioner: Node2D )

Emitted when the node responsible for positioning grid building placement objects and indicators is changed on the BuildingState.

signal target_map_changed( target_map: TileMapLayer )

Emitted when the targeted map node is changed. This represents the main target TileMapLayer node on the state.

signal maps_changed( maps: Array[TileMapLayer] )

Emitted when the list of known maps is changed.

This is a list of maps that can be accessed without the need for any collision check calls.

Properties

Section titled “Properties”
positioner: Node2D :

Private backing field for the collision target Private backing field for the collision object (raw collision detected by TargetingShapeCast2D)

Private backing field for the resolved target (the logical root for display/manipulation)

Parent node for positioning grid building objects onto the game world.

target_map: TileMapLayer :

The TileMapLayer or TileMap node to be used when determining grid distances in your game world

You could think of this as the main map node usually where characters stand on

maps: Array[TileMapLayer]:

All maps to be known by the targeting state for testing against without casting for collisions.

You can exclude any purely cosmetic maps that shouldn’t have gameplay impacts.

tile_size: Vector2i :

Tile size property that delegates to the target map’s tile set

collision_exclusions: Array[Node] = []

Nodes that should be excluded from collision detection during indicator validation. This is primarily used during manipulation move operations to exclude the original object being moved, so indicators only detect collisions with OTHER objects.

IMPORTANT: This list is automatically cleared when:

  • The target changes (manipulation ends and switches to a different target) - Manually calling clear_collision_exclusions()

Usage: Set this at the start of manipulation move operations and it will auto-clear when manipulation ends.

is_manual_targeting_active: bool = false

Flag indicating whether manual targeting mode is currently active. When true, automatic targeting systems (like TargetingShapeCast2D) will not overwrite the manually-set target, and collision_exclusions will persist across target updates. Used during BUILD mode (preview) and MOVE mode (manipulation copy). Set via set_manual_target() and cleared via clear().

Methods

Section titled “Methods”
func _init( p_owner_context: GBOwnerContext )

References the user root that serves as the origin for this targeting state

func is_ready( ) -> bool

Returns true if the targeting state has all runtime requirements met for operation

func clear_collision_exclusions( ) -> void

Clears the collision exclusion list. This is called automatically when the target changes (and manipulation is not active), but can also be called manually when ending manipulation operations.

func set_manual_target( p_target: Node2D ) -> void

Sets a manual target and prevents automatic targeting updates. This prevents automatic targeting systems (like TargetingShapeCast2D) from overwriting the manually-set target. Used during: - BUILD mode: Locks preview as target - MOVE mode: Locks manipulation copy as target

If p_target is null, clears manual targeting mode (equivalent to clear()). Otherwise, enables manual targeting and assigns the target.

Note: This method sets the target DIRECTLY without resolution logic. When you call set_manual_target(), you’re saying “this exact node IS the target” - no metadata lookup, no root resolution. Manual = exact node.

p_target: The node to manually target, or null to clear manual targeting

func clear( ) -> void

Clears manual targeting mode and resumes automatic targeting. Call this when BUILD or MOVE mode ends to allow TargetingShapeCast2D to automatically update the target again.

This fully resets the targeting state by:

  • Clearing the target and collider (set to null) - Disabling manual targeting flag

  • Disconnecting lifecycle signals

After calling this, automatic targeting systems will resume updating the target.

func get_target_map_tile_shape( ) -> TileSet.TileShape

Get the shape of the currently targeted TileMapLayer’s tileset tiles

func get_target_map_tile_set( ) -> TileSet

Gets the tileset of the currently targeted TileMapLayer

func get_target( ) -> Node2D

Returns the resolved target node (the logical root).

This is what you should use for display, manipulation, and game logic.

This is the primary public API for accessing the current target.

func get_collider( ) -> Node2D

Returns the raw collision object that detection by ShapeCast etc connected with

Internal use only. Most code should use get_target() instead, which returns the resolved logical root.

func get_tile_size( ) -> Vector2i

Gets the tile size from the target map’s tile set

func set_collider( p_collider: Node2D ) -> void

Sets the collision object and automatically resolves the target.

This is the primary method used by TargetingShapeCast2D and other targeting systems.

Behavior:

  • Resolves logical root from collision object via GBMetadataResolver

  • Emits target_changed signal with the RESOLVED target (not collision object)

  • Auto-clears collision exclusions based on context

  • Connects to collision object lifecycle (tree_exiting signal)

p_collider: The collision object detected (or null to clear)

func set_map_objects( p_target_map: TileMapLayer, p_maps: Array[TileMapLayer] ) -> void

Sets the target map and maps array for this targeting state

func set_tile_size( size: Vector2i ) -> void

Sets the tile size on the target map’s tile set

func validate_runtime( logger: GBLogger ) -> bool

Ensures that the targeting state is ready for runtime operation and logs any issues found

func get_owner( ) -> Node
func get_owner_root( ) -> Node
func get_origin( ) -> Node

Returns the origin node associated with this targeting state. Returns: The origin node provided by the owner context or null when unavailable.

func _revalidate_on_change( ) -> void

Internal: Re-validate when critical properties change so ‘ready’ flips to true at the right time.

func get_editor_issues( ) -> Array[String]

Returns an array of issues found during editor validation

func get_runtime_issues( ) -> Array[String]

Should be called AFTER necessary properties on the state have been set Checks the minimum setup dependencies for the state.

func _disconnect_collider_signal( ) -> void

Disconnects the tree_exiting signal from the current collider (if connected)

func _on_collider_tree_exiting( ) -> void

Called when the current collider is about to exit the scene tree

func _is_same_context_update( new_target: Node2D ) -> bool

Checks if the new target is part of the same object tree as any exclusion Returns true if new_target is a child/descendant of an excluded node This helps detect when TargetingShapeCast2D detects a different node of the same logical object

Source

Section titled “Source”

addons/grid_building/systems/grid_targeting/grid_targeting_state.gd

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