Draft — Unreleased:This page is in active development. APIs, class names, and behavior may change before the release is finalized. Use it as a preview of what's coming — not as a stable integration target.
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 [PlacementAssetResolver] for automatic discovery of content and category tags. Integrates with [PlacementSystem] to initiate placement mode when items are selected. [b]Key Features:[/b] [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] [b]Usage:[/b] [codeblock] var selection_ui = PlaceableSelectionUI.new() selection_ui.placeables_folder = "res://my_placeables" selection_ui.category_profiles_folder = "res://my_profiles" selection_ui.fixed_template_height = 48 selection_ui.fixed_icon_size = 40 [/codeblock]
Source: addons/grid_placement/ui/placeable/single/placeable_selection_ui.gd
Syntax
class PlaceableSelectionUI extends PlacementControlMembers
| Name | Kind | Summary |
|---|---|---|
valid_changed | Event | Emitted when the UI validation state changes.[br] [param is_valid] True if the UI is properly configured and ready for use. |
placeable_activated | Event | Emitted whenever the user clicks a placeable entry, INCLUDING when [member read_only_catalog] suppresses the built-in 2D build-mode dispatch. 3D sessions listen to this to drive [ObjectPlacementService3D]. |
category_profiles_folder | Property | Path to folder containing category tag resources.[br] Profiles found here are automatically loaded and added to [member category_profiles]. |
placeables_folder | Property | Path to folder containing placeable resources.[br] Placeables found here are automatically loaded and added to [member placeables]. |
sequences_folder | Property | Path to folder containing placeable sequence resources.[br] Sequences found here are automatically loaded and added to [member sequences]. |
category_profiles | Property | Category tags to include alongside folder-loaded ones.[br] These profiles are combined with profiles loaded from [member category_profiles_folder]. |
placeables | Property | Individual placeables to include alongside folder-loaded ones.[br] These are displayed in grids alongside sequences. Combined with placeables from [member placeables_folder]. |
sequences | Property | ScenePlacementEntry sequences to include alongside folder-loaded ones.[br] Sequences allow variant cycling within a single grid slot. Combined with sequences from [member sequences_folder]. |
grid_columns | Property | Number of columns for the grid layout.[br] Default: 1 (single column list layout). |
placeable_entry_template | Property | Template scene for individual placeable entries.[br] Should be a [PlaceableView] that displays icon and name. |
sequence_entry_template | Property | Template scene for sequence entries with variant cycling.[br] Should be a [PlaceableListEntry] that supports cycling through sequence variants. |
fixed_template_height | Property | Fixed height for all templates to prevent resizing when cycling through sequence variants.[br][br] When set to a positive value, enforces consistent height for all template entries.[br] When set to 0, disables PlaceableSelectionUI-level height enforcement and allows templates to size naturally.[br] Note: Individual PlaceableView instances may still enforce their own height via their fixed_view_height property.[br] Default: 48 pixels for consistent template sizing. |
fixed_icon_size | Property | Fixed icon size for all placeable view icons to ensure consistent icon dimensions.[br][br] When set to a positive value, enforces both width and height for all icon TextureRects in PlaceableView instances.[br] When set to 0, icon sizing is not enforced and will use template defaults.[br] Default: 40 pixels for standard icon sizing. |
show_category_tab_names | Property | Whether category tab titles should be visible for manual category selection.[br] When false, tabs are hidden and only grid content is shown. |
hide_ui_on_selection | Property | Whether to hide the selection UI when an item is selected.[br] When true, the UI automatically hides after the user selects a placeable or sequence. |
read_only_catalog | Property | When true, renders catalog entries without entering placement mode on click. Use for demos that can display catalog data before their placement pipeline supports the entry type, such as the current 3D demo's Node3D entries. |
ui_root | Property | Root control node for showing and hiding the entire UI. |
tab_container | Property | Tab container that handles category-based organization.[br] Each tab represents a category tag and contains a grid of matching placeables/sequences. |
get_mode_state | Method | |
resolve_placement_dependencies | Method | |
seeded_categories | Property | |
seeded_placeables | Property | |
seeded_sequences | Property | |
folder_profiles | Property | |
catalog | Property | |
issues | Property | |
folder_placeables | Property | |
folder_sequences | Property | |
seen_keys | Property | |
i | Property | |
item | Property | |
key | Property | |
catalog_v | Property | |
rebuild | Method | |
clear | Method | |
actual_tab_index | Property | |
profile | Property | |
matched_placeables | Property | |
matched_sequences | Property | |
unified_grid | Property | |
page | Property | |
matched | Property | |
matched | Property | |
sequence_matches | Property | |
grid | Property | |
entry_node | Property | |
entry | Property | |
entry_node | Property | |
entry | Property | |
entered | Property | |
active_placeable | Property | |
entered | Property | |
add_placeables | Method | |
cat_item_list | Property | |
remove_placeables | Method | |
cat_item_list | Property | |
get_runtime_issues | Method | |
issues | Property | |
has_placeables | Property | |
has_sequences | Property | |
at_least_one_category | Property | |
has_placeables | Property | |
has_sequences | Property | |
texture_rects | Property | |
tex_rect | Property | |
found_nodes | Property |
Source
addons/grid_placement/ui/placeable/single/placeable_selection_ui.gd
Plugin docs root:gdscript/plugins/grid_placement_dev/docs