godot-ui-containers

What this skill does

# UI Containers

Container auto-layout, size flags, anchors, and split ratios define responsive UI systems.

## Available Scripts

### [responsive_layout_builder.gd](scripts/responsive_layout_builder.gd)
Expert container builder with breakpoint-based responsive layouts.

### [responsive_grid.gd](scripts/responsive_grid.gd)
Auto-adjusting GridContainer that changes column count based on available width.

### [responsive_inventory_grid.gd](scripts/responsive_inventory_grid.gd)
Expert logic for dynamic Grid columns based on available width and item minimum size.

### [terminal_autoscroll.gd](scripts/terminal_autoscroll.gd)
Safe ScrollContainer management. Handles the common "one-frame delay" bug when adding logs or chat.

### [viewport_3d_preview.gd](scripts/viewport_3d_preview.gd)
High-performance 3D-in-UI setup. Uses `stretch_shrink` and `transparent_bg` for character previews.

### [dynamic_tab_manager.gd](scripts/dynamic_tab_manager.gd)
Pattern for dynamic tab spawning, custom titles, and tab closing logic.

### [responsive_tag_cloud.gd](scripts/responsive_tag_cloud.gd)
Wrapping item lists using `HFlowContainer`, essential for tag clouds and responsive menus.

### [performance_anchor_layout.gd](scripts/performance_anchor_layout.gd)
Optimization architecture. Replaces deep container nesting with lightweight Anchor and Offset logic.

### [custom_radial_container.gd](scripts/custom_radial_container.gd)
Expert custom container logic implementing a radial/circle layout via `NOTIFICATION_SORT_CHILDREN`.

### [animated_container_shuffle.gd](scripts/animated_container_shuffle.gd)
Dynamic sibling reordering and animation logic for interactive UI lists.

### [aspect_ratio_mini_map.gd](scripts/aspect_ratio_mini_map.gd)
Enforcing strict aspect ratios (e.g. 1:1, 16:9) across fluid window resizes using `AspectRatioContainer`.

### [container_size_flags_pro.gd](scripts/container_size_flags_pro.gd)
Advanced sizing logic using `SIZE_EXPAND_FILL` and `stretch_ratio` for weighted layouts.

## NEVER Do in UI Containers

- NEVER ignore **`mouse_filter`** properties; strictly set to `PASS` or `IGNORE` on overlay containers to prevent them from blocking clicks to underlying buttons.
- NEVER instantiate thousands of nodes in a `ScrollContainer`; strictly use **Virtual List Pooling** with a `VScrollBar` hook and a single spacer child to simulate list height for O(1) rendering performance.
- NEVER manually calculate card dimensions for responsive grids; strictly use an **`AspectRatioContainer`** to lock proportions (e.g., 2:3 ratio) while allowing parent containers to handle scaling.
- **NEVER manually set child `position` or `size` in a Container** — Containers override child transforms during `queue_sort()`. Use `custom_minimum_size` or `size_flags` instead [1].
- **NEVER forget `size_flags` for expansion** — Default is `SIZE_SHRINK_BEGIN`. Children will stay tiny unless you set `SIZE_EXPAND_FILL` for responsive containers.
- **NEVER use `GridContainer` without setting `columns`** — Default is 1, creating a simple vertical list. For responsive wrapping, use `HFlowContainer` instead [8].
- **NEVER nest containers too deeply (10+ levels)** — Heavy nesting causes layout recalculation spikes. Replace intermediate containers with Anchor Layouts for static padding [16].
- **NEVER skip separation overrides** — Default theme separation is often too tight. Use `add_theme_constant_override("separation", value)` for professional breathing room.
- **NEVER use `ScrollContainer` without a minimum size** — Without it, the container may collapse to zero or expand infinitely, breaking the scroll mechanism.
- **NEVER scroll to a new child on the same frame it was added** — The layout hasn't updated yet. You MUST `await get_tree().process_frame` before setting `scroll_vertical` [5].
- **NEVER scale a `SubViewportContainer` to change its size** — This distorts the rendered contents. Adjust margins or use `stretch` and `stretch_shrink` properties instead [2].
- **NEVER leave `mouse_filter` on default for layered Viewports** — Input events might not reach children. Use `MOUSE_FILTER_PASS` or `STOP` to ensure events drill down [6].
- **NEVER use `GridContainer` for responsive wrapping** — Use `HFlowContainer` if you want items to wrap based on width. GridContainer enforces a strict column count [7].
- **NEVER animate `position` directly inside a container** — Use `Tween` on `custom_minimum_size` to smoothly "push" siblings during transitions [1].

---

```gdscript
# VBoxContainer example
# Automatically stacks children vertically
# Children:
#   Button ("Play")
#   Button ("Settings")
#   Button ("Quit")

# Set separation between items
$VBoxContainer.add_theme_constant_override("separation", 10)
```

## Responsive Layout

```gdscript
# Use anchors and size flags
func _ready() -> void:
    # Expand to fill parent
    $MarginContainer.set_anchors_preset(Control.PRESET_FULL_RECT)
    
    # Add margins
    $MarginContainer.add_theme_constant_override("margin_left", 20)
    $MarginContainer.add_theme_constant_override("margin_right", 20)
```

## Expert Layout Patterns

### 1. Split-Screen-Container (Dynamic)
Standard pattern for local multiplayer or comparisons using `HSplitContainer`.

```gdscript
# split_screen.gd
func setup_split(v1: SubViewport, v2: SubViewport):
    var hsplit = HSplitContainer.new()
    var c1 = SubViewportContainer.new()
    c1.stretch = true # Resize viewport to match container
    c1.add_child(v1)
    hsplit.add_child(c1)
    # repeat for c2/v2...
```

### 2. Virtual List ScrollContainer (Pooling)
High-performance list for thousands of items by recycling a small node pool and using a spacer.

```gdscript
# virtual_list.gd
func _on_scroll():
    var scroll_y = get_v_scroll_bar().value
    var start_idx = int(scroll_y / item_height)
    for i in range(node_pool.size()):
        var node = node_pool[i]
        # Move node down the list
        node.position.y = (start_idx + i) * item_height
        # Inject data from the massive array
        node.update_data(massive_data_array[start_idx + i])
```

### 3. Aspect-Ratio-Locked Cards
Responsive cards that maintain proportions (e.g., 2:3) in any grid or flow container.

```gdscript
# card_grid.gd
func add_card(texture: Texture2D):
    var arc = AspectRatioContainer.new()
    arc.ratio = 0.66 # 2:3 proportions
    arc.stretch_mode = AspectRatioContainer.STRETCH_FIT
    
    var tr = TextureRect.new()
    tr.texture = texture
    tr.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
    tr.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
    
    arc.add_child(tr)
    grid_container.add_child(arc)
```

## SizeFlags

```gdscript
# Control how children expand in containers
button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
button.size_flags_vertical = Control.SIZE_SHRINK_CENTER
```

## Reference
- [Godot Docs: GUI Containers](https://docs.godotengine.org/en/stable/tutorials/ui/gui_containers.html)


### Related
- Master Skill: [godot-master](../godot-master/SKILL.md)