Skip to content
Grid Building Docs

PlaceableSelectionUI

Summary

Section titled “Summary”

Unified UI component for selecting placeable objects and placeable sequences to build.

Provides a tabbed, grid-based interface for selecting placeables and placeable sequences to place in the world. Supports folder-based asset loading with [GBAssetResolver] for automatic discovery of content and category tags. Integrates with [BuildingSystem] to initiate placement mode when items are selected.

Key Features: [ul] - Mixed content grids supporting both individual placeables and sequences - Configurable sizing for consistent template height and icon dimensions - Variant cycling for sequences through enhanced [PlaceableListEntry] components - Automatic asset loading from configured folders - Category-based organization with tabs [/ul]

Usage:

var selection_ui = PlaceableSelectionUI.new()
selection_ui.placeables_folder = "res://my_placeables"
selection_ui.category_tags_folder = "res://my_categories"
selection_ui.fixed_template_height = 48
selection_ui.fixed_icon_size = 40

Signals

Section titled “Signals”
signal valid_changed( is_valid: bool )

Emitted when the UI validation state changes.

is_valid: True if the UI is properly configured and ready for use.

Properties

Section titled “Properties”
category_tags: Array[CategoricalTag] = []

Category tags to include alongside folder-loaded ones.

These tags are combined with tags loaded from [member category_tags_folder].

placeables: Array[Placeable] = []

Individual placeables to include alongside folder-loaded ones.

These are displayed in grids alongside sequences. Combined with placeables from [member placeables_folder].

sequences: Array[PlaceableSequence] = []

Placeable sequences to include alongside folder-loaded ones.

Sequences allow variant cycling within a single grid slot. Combined with sequences from [member sequences_folder].

placeable_entry_template: PackedScene

Template scene for individual placeable entries.

Should be a [PlaceableView] that displays icon and name.

sequence_entry_template: PackedScene

Template scene for sequence entries with variant cycling.

Should be a [PlaceableListEntry] that supports cycling through sequence variants.

fixed_template_height: int = 48

Fixed height for all templates to prevent resizing when cycling through sequence variants.

When set to a positive value, enforces consistent height for all template entries.

When set to 0, disables PlaceableSelectionUI-level height enforcement and allows templates to size naturally.

:::note[Note] Individual PlaceableView instances may still enforce their own height via their fixed_view_height property.

Default: 48 pixels for consistent template sizing. :::

fixed_icon_size: int = 40

Fixed icon size for all placeable view icons to ensure consistent icon dimensions.

When set to a positive value, enforces both width and height for all icon TextureRects in PlaceableView instances.

When set to 0, icon sizing is not enforced and will use template defaults.

Default: 40 pixels for standard icon sizing.

show_category_tab_names: bool = true

Whether category tab titles should be visible for manual category selection.

When false, tabs are hidden and only grid content is shown.

hide_ui_on_selection: bool = false

Whether to hide the selection UI when an item is selected.

When true, the UI automatically hides after the user selects a placeable or sequence.

ui_root: Control

Root control node for showing and hiding the entire UI.

tab_container: TabContainer

Tab container that handles category-based organization.

Each tab represents a category tag and contains a grid of matching placeables/sequences.

Methods

Section titled “Methods”
func _ready( )
func resolve_gb_dependencies( p_container: GBCompositionContainer ) -> void

Called by GBChildInjector to resolve dependencies on the UI.

p_container: GBCompositionContainer - Container with system dependencies and configuration

func _load_assets( ) -> void

Load assets using GBAssetResolver for both placeables and sequences

func rebuild( ) -> void

Rebuild the UI after changing content type or assets at runtime

func clear( )
func _setup_tabs( )

Generate tabs for each category and populate each tab with content in unified grid layout

func _get_placeables_with_tag( tag: Resource ) -> Array[Placeable]
func _get_sequences_with_tag( tag: Resource ) -> Array[PlaceableSequence]
func _create_mixed_content_grid( placeables_for_tag: Array[Placeable], sequences_for_tag: Array[PlaceableSequence] ) -> GridContainer

Creates a mixed content grid containing both placeables and sequences

func _on_placeable_selected( p_placeable: Placeable )
func _on_sequence_entry_selected( entry: PlaceableListEntry )
func _on_sequence_variant_changed( entry: PlaceableListEntry, variant_index: int )
func add_placeables( new_placeables: Array[Placeable] )

Adds placeable options to the UI and updates the corresponding visuals.

new_placeables: Array[Placeable] - Array of new placeable resources to add to the UI

func remove_placeables( rem_placeables: Array[Placeable] )

Removes placeable options from the UI and updates the corresponding visuals.

rem_placeables: Array[Placeable] - Array of placeable resources to remove from the UI

func get_runtime_issues( ) -> Array[String]

Run setup checks on the UI to ensure proper setup. Returns validation issues found during setup checks.

return: Array[String] - List of validation issues (empty if valid)

func _on_mode_changed( p_mode: GBEnums.Mode )
func _on_hidden( )

When hidden, if in build mode, automatically switch to off mode

func _validate_basic_components( ) -> void

Get the current building system from systems context Validates basic required components are properly assigned

func _validate_required_templates( ) -> void

Validates only the templates that are needed based on loaded content

func _get_building_system( ) -> BuildingSystem
func _enforce_template_height( template_entry: Control ) -> void

Enforces fixed height for consistent template sizing when fixed_template_height > 0.

When fixed_template_height is 0, height enforcement is disabled at the PlaceableSelectionUI level.

func _constrain_template_icons( template_entry: Control ) -> void

Constrains icon/image elements within templates to prevent height expansion

func _find_nodes_by_type( parent: Node, type_name: String ) -> Array[Node]

Recursively finds all nodes of a specific type within a parent node

Source

Section titled “Source”

addons/grid_building/ui/placeable/single/placeable_selection_ui.gd

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