Skip to content
Grid Building Docs

BuildingSystem

Summary

Section titled “Summary”

Manages placement of objects in the game world.

Handles preview, placement validation, and build actions. Uses tile collision indicators to show valid/invalid spots before placement. Checks all rules before adding objects to the world and emits signals for build success or failure.

Constants

Section titled “Constants”
const WARNING_INVALID_PLACEABLE = “Invalid placeable resource. Can’t instantiate. [%s]”

Tracks drag events for build button. InputEventScreenDrag instance used to track drag events for build actions. Updated as the user drags to new tiles during multi-build mode.

const WARNING_NO_PREVIEW = “No preview instance created to instantiate yet. Returning null.”

Properties

Section titled “Properties”
placement_polygons: Array[CollisionPolygon2D]

Instantiates building objects for placement.

Collision polygons for placement indicators.

preview_layer: int

Preview layer index for buildable/unbuildable tiles.

selected_placeable: Placeable

Currently selected placeable resource.

indicators_group: Node2D

Parent node for collision indicators.

Methods

Section titled “Methods”
static func create_with_injection( container: GBCompositionContainer ) -> BuildingSystem

Creates a BuildingSystem with injected dependencies from the container.

func get_building_state( )

The report of the active ongoing placement

legacy accessors expected in some validator/integration tests

func get_targeting_state( )
func is_ready_to_place( ) -> bool

Returns true if system is ready to place a selected placeable (should already be set) Checks if the system is ready to build by validating the selected placeable and build context. Returns true if all build requirements are met and no issues are found.

func is_in_build_mode( ) -> bool

Returns true if the building system is currently in build mode. Checks the current mode state to determine if build mode is active.

func exit_build_mode( ) -> void

Exits build mode and cleans up all build-related elements. Sets the mode to OFF, clears the preview, and tears down indicators.

func resolve_gb_dependencies( p_container: GBCompositionContainer ) -> void
func try_build( p_build_type: GBEnums.BuildType ) -> PlacementReport

Attempts to place a building at the current preview location if all placement rules pass. Validates all placement rules and emits success or failure signals based on the result. Returns the built Node2D if successful, null otherwise.

p_build_type: Type of build operation (SINGLE, DRAG, or AREA). Defaults to SINGLE.

func try_build_at_position( p_global_position: Vector2 ) -> PlacementReport

Legacy API compatibility method for tests Attempts to place a building at the specified position Temporarily moves the targeting system to the position, attempts placement, then restores position

func enter_build_mode( p_placeable: Placeable ) -> PlacementReport

Sets up a preview instance for the selected placeable. Switches to build mode, clears previous preview, and creates a new preview instance. Returns true if setup is successful.

p_placeable: Placeable - Placeable resource to create preview for

func clear_preview( )

Removes the current preview instance. Removes the current preview instance and resets placement manager state. Called when exiting build mode or clearing preview.

func _exit_build_cleanup( )

Cleans up build mode elements and resets indicators. Cleans up build mode elements, clears preview, and resets indicator manager. Called when exiting build mode or switching modes.

func _unhandled_input( event: InputEvent )

Handles input for building controls. Handles input events for building controls, including build confirmation and mode switching. Processes input based on current build mode and user actions.

func instance_preview( p_placeable: Placeable ) -> Node2D

Creates a preview instance with limited functionality. Strips scripts not needed for preview and replaces root node script if set in config. Used for visual feedback before placement.

p_placeable: Placeable - Placeable resource to create preview instance for

func get_runtime_issues( ) -> Array[String]

Validates that all required dependencies are set. This is called automatically when entering build mode, but can also be called manually after scene loads to check if all dependencies are properly configured. Returns list of validation issues (empty if valid).

func get_builder_owner( ) -> GBOwner

Get the current GBOwner of the building object which is the root node of the GBOwner in the active GBOwnerContext that is assigned to the BuildingState

func report_built( p_report: PlacementReport, p_build_type: GBEnums.BuildType ) -> void

Connects BuildingSystem to a DragManager scene component for drag-building support. Reports a successful build action through the BuildingState

p_report: The placement report for the build action p_build_type: Type of build operation (SINGLE, DRAG, or AREA)

func report_failure( p_report: PlacementReport, p_build_type: GBEnums.BuildType ) -> void

Reports a failed build action through the BuildingState

p_report: The placement report for the build action p_build_type: Type of build operation (SINGLE, DRAG, or AREA)

func _get_lazy_building_instantiator( ) -> BuildingInstantiator

Private lazy getter for building instantiator. Creates and configures the instantiator if it doesn’t exist.

return: BuildingInstantiator - The building instantiator instance

func _get_lazy_preview_builder( ) -> PreviewBuilder

Private lazy getter for preview builder. Creates and configures the preview builder if it doesn’t exist.

return: PreviewBuilder - The preview builder instance

func _try_setup( p_preview_instance: Node, p_placeable_rules: Array[PlacementRule] ) -> PlacementReport
func _build_instance( p_placeable: Placeable ) -> Node2D

Places the buildable scene into the world. Instantiates and places the buildable scene into the world at the preview location. Marks as placed using metadata.

p_placeable: Placeable - Placeable resource to build

func _validate_build_ready( ) -> bool

Validates if the building system is ready for placement.

func _align_preview_to_grid( collision_shape_global_position: Vector2 )

Make sure placement manager exists to put preview instances onto

Aligns preview to the grid system. Aligns the preview instance to the grid system based on the given global position. Used to snap preview to grid tiles for accurate placement feedback.

func _on_mode_changed( p_mode: GBEnums.Mode )

Handles changes to build mode. Cleans up build state and indicators when switching out of build mode.

Source

Section titled “Source”

addons/grid_building/systems/building/building_system.gd

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