home / skills / besty0728 / unity-skills / ui

ui skill

safe

/unity-skills/skills/ui

This skill lets you create Unity UI elements efficiently using batch calls to instantiate 2+ elements and organize them under panels.

npx playbooks add skill besty0728/unity-skills --skill ui

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

6.3 KB

---
name: unity-ui
description: "Create UI elements (Canvas, Button, Text, etc.). Use ui_create_batch for 2+ elements."
---

# Unity UI Skills

> **BATCH-FIRST**: Use `ui_create_batch` when creating 2+ UI elements.

## Skills Overview

| Single Object | Batch Version | Use Batch When |
|---------------|---------------|----------------|
| `ui_create_*` | `ui_create_batch` | Creating 2+ UI elements |

**Query/Utility Skills**:
- `ui_set_text` - Update text content
- `ui_find_all` - Find UI elements

---

## Single-Object Skills

### ui_create_canvas
Create a UI Canvas container.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Canvas" | Canvas name |
| `renderMode` | string | No | "ScreenSpaceOverlay" | ScreenSpaceOverlay/ScreenSpaceCamera/WorldSpace |

### ui_create_panel
Create a Panel container.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Panel" | Panel name |
| `parent` | string | No | null | Parent Canvas/object |
| `r/g/b/a` | float | No | 1,1,1,0.5 | Background color |
| `width/height` | float | No | 200 | Size in pixels |

### ui_create_button
Create a Button.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Button" | Button name |
| `parent` | string | No | null | Parent object |
| `text` | string | No | "Button" | Button label |
| `width/height` | float | No | 160/30 | Size |
| `x/y` | float | No | 0 | Position offset |

### ui_create_text
Create a Text element.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Text" | Text name |
| `parent` | string | No | null | Parent object |
| `text` | string | No | "Text" | Content |
| `fontSize` | int | No | 24 | Font size |
| `r/g/b/a` | float | No | 0,0,0,1 | Text color |
| `width/height` | float | No | 200/50 | Size |

### ui_create_image
Create an Image element.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Image" | Image name |
| `parent` | string | No | null | Parent object |
| `spritePath` | string | No | null | Sprite asset path |
| `r/g/b/a` | float | No | 1,1,1,1 | Tint color |
| `width/height` | float | No | 100 | Size |

### ui_create_inputfield
Create an InputField.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "InputField" | Field name |
| `parent` | string | No | null | Parent object |
| `placeholder` | string | No | "Enter text..." | Placeholder |
| `width/height` | float | No | 200/30 | Size |

### ui_create_slider
Create a Slider.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Slider" | Slider name |
| `parent` | string | No | null | Parent object |
| `minValue` | float | No | 0 | Minimum value |
| `maxValue` | float | No | 1 | Maximum value |
| `value` | float | No | 0.5 | Initial value |
| `width/height` | float | No | 160/20 | Size |

### ui_create_toggle
Create a Toggle/Checkbox.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | No | "Toggle" | Toggle name |
| `parent` | string | No | null | Parent object |
| `label` | string | No | "Toggle" | Label text |
| `isOn` | bool | No | false | Initial state |

### ui_set_text
Update text content.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Text object name |
| `text` | string | Yes | New content |

### ui_find_all
Find UI elements in scene.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `uiType` | string | No | null | Filter: Button/Text/Image/etc. |
| `limit` | int | No | 100 | Max results |

---

## Batch Skill

### ui_create_batch
Create multiple UI elements in one call.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | Yes | Array of UI element configs |

**Item properties**: `type` (required), `name`, `parent`, `text`, `width`, `height`, `x`, `y`, `r`, `g`, `b`, `a`, etc.

**Supported types**: Button, Text, Image, Panel, Slider, Toggle, InputField

```python
unity_skills.call_skill("ui_create_batch", items=[
    {"type": "Button", "name": "StartBtn", "parent": "MenuPanel", "text": "Start", "y": 60},
    {"type": "Button", "name": "OptionsBtn", "parent": "MenuPanel", "text": "Options", "y": 0},
    {"type": "Button", "name": "QuitBtn", "parent": "MenuPanel", "text": "Quit", "y": -60}
])
```

---

## Example: Efficient Menu Creation

```python
import unity_skills

# BAD: 5 API calls
unity_skills.call_skill("ui_create_canvas", name="MainMenu")
unity_skills.call_skill("ui_create_panel", name="MenuPanel", parent="MainMenu")
unity_skills.call_skill("ui_create_button", name="StartBtn", parent="MenuPanel", text="Start", y=60)
unity_skills.call_skill("ui_create_button", name="OptionsBtn", parent="MenuPanel", text="Options", y=0)
unity_skills.call_skill("ui_create_button", name="QuitBtn", parent="MenuPanel", text="Quit", y=-60)

# GOOD: 2 API calls
unity_skills.call_skill("ui_create_canvas", name="MainMenu")
unity_skills.call_skill("ui_create_batch", items=[
    {"type": "Panel", "name": "MenuPanel", "parent": "MainMenu", "width": 300, "height": 200},
    {"type": "Button", "name": "StartBtn", "parent": "MenuPanel", "text": "Start", "y": 60},
    {"type": "Button", "name": "OptionsBtn", "parent": "MenuPanel", "text": "Options", "y": 0},
    {"type": "Button", "name": "QuitBtn", "parent": "MenuPanel", "text": "Quit", "y": -60}
])
```

## TextMeshPro Support

UI Skills auto-detect TextMeshPro:
- **With TMP**: Uses `TextMeshProUGUI`
- **Without TMP**: Falls back to legacy `UnityEngine.UI.Text`

Response includes `usingTMP` field to indicate which was used.

## Best Practices

1. Always create Canvas first
2. Use Panels to organize related elements
3. Use meaningful names for scripting access
4. Set parent for proper hierarchy
5. WorldSpace canvas for 3D UI (health bars, etc.)

Overview

This skill creates Unity UI elements (Canvas, Panel, Button, Text, Image, InputField, Slider, Toggle) and supports efficient multi-element creation via a batch API. It auto-detects TextMeshPro and returns which text system was used. Use ui_create_* for single items and ui_create_batch for two or more elements to minimize calls and keep hierarchy consistent.

How this skill works

Each ui_create_* call instantiates a configured UI GameObject with sensible defaults (names, sizes, colors, positions) and optional parent assignment. ui_create_batch accepts an items array of element configs to create many objects in one call. The skill inspects the project for TextMeshPro; if present it creates TextMeshProUGUI objects and includes a usingTMP flag in responses.

When to use it

Create a single UI element quickly (ui_create_button, ui_create_text, etc.).
Build a menu, HUD, or dialog with multiple elements using ui_create_batch to reduce API calls.
Initialize a Canvas or switch between ScreenSpace and WorldSpace rendering.
Generate grouped UI under a Panel for layout and scripting access.
Create runtime UI dynamically (settings panels, tooltips, in-game HUD).

Best practices

Always create a Canvas before other UI elements to ensure correct rendering.
Use ui_create_batch whenever creating two or more elements to improve performance and keep hierarchy changes atomic.
Assign meaningful names and set parent to simplify Find and runtime scripting.
Use Panels to group related elements and control layout or visibility.
Prefer WorldSpace Canvas for 3D UI like floating health bars.

Example use cases

Build a main menu: create a Canvas, then use ui_create_batch to add a panel and multiple buttons (Start, Options, Quit).
Spawn an in-game HUD: batch-create health bar (Image), score text, and minimap panel at runtime.
Quickly add a settings section: create toggles, sliders, and input fields grouped under a Panel.
Convert legacy projects: detect TextMeshPro and create TMP text objects automatically when available.
Prototype UI layouts in code without manually creating GameObjects in the editor.

FAQ

How does TextMeshPro detection work?

The skill checks for TextMeshPro in the project. If found it creates TextMeshProUGUI elements; otherwise it falls back to UnityEngine.UI.Text and reports usingTMP in the response.

When should I always use ui_create_batch?

Use ui_create_batch whenever you need to create two or more UI elements in the same operation. It reduces the number of API calls, preserves intended hierarchy, and is faster for grouped UI creation.