BuildingSystem

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

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

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

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

Resolves and injects all required dependencies from the composition container.

Sets up all system dependencies including states, settings, contexts, actions, and logger. Connects to mode change signals and initializes lazy components. Validates that all dependencies are properly configured and logs any issues found.

p_container: The composition container providing all system dependencies and configuration.

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

Attempts to place a building at the specified global position.

Temporarily moves the targeting positioner to the given position, attempts to build using the current placeable and rules, then restores the original positioner position. Used for programmatic building at specific coordinates without affecting the current targeting state.

p_global_position: The global position where the building should be attempted. Returns: Placement report indicating success or failure of the build operation.

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( )

Clears the current building preview and resets all related state.

Removes the preview instance, tears down placement indicators, and resets the manipulation parent transform to prevent rotation persistence between placeables. Called when exiting build mode, switching placeables, or clearing the current 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 and sets up a preview instance for the specified placeable.

Instantiates a preview version of the placeable, sets it as the selected placeable, and initializes placement rules and indicators for visual feedback. The preview instance is used to show where the building will be placed before confirmation.

p_placeable: The placeable resource to create a preview instance for. Returns: The created preview Node2D instance, or null if creation fails.

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

Retrieves the current builder owner from the building state.

Gets the GBOwner instance that represents the root node context for building operations. This owner is used to determine the scene hierarchy and ownership for placed buildings.

Returns: The current GBOwner instance, or null if building state is not available.

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 _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 that all required components are properly configured for building.

Performs comprehensive validation of the building system state, including dependency injection status and critical component availability. Asserts on critical configuration issues to catch setup problems early in development.

Returns: True if the building system is ready for placement operations, false otherwise.

func _align_preview_to_grid( collision_shape_global_position: Vector2 )

Make sure placement manager exists to put preview instances onto

Aligns the building preview to the grid system at the specified position.

Snaps the preview instance to the nearest valid grid position based on the collision shape’s global position. Ensures accurate placement feedback by aligning the preview with the underlying grid system.

collision_shape_global_position: The global position of the collision shape to align to the grid.

func _on_mode_changed( p_mode: GBEnums.Mode )

Handles mode change events to clean up building state when exiting build mode.

Responds to global mode changes by clearing the selected placeable and performing cleanup operations when switching away from BUILD mode. Ensures the building system state remains consistent with the current application mode.

p_mode: The new mode that the application is switching to.

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.