t1k:unity:ui:toolkit
| Field | Value |
|---|---|
| Module | ui |
| Version | 3.43.4 |
| Effort | medium |
| Tools | — |
Keywords: UI Toolkit, USS, UXML
How to invoke
Section titled “How to invoke”/t1k:unity:ui:toolkitUnity UI Toolkit — UXML, USS & Runtime UI
Section titled “Unity UI Toolkit — UXML, USS & Runtime UI”UI Toolkit reference for Unity 6 (6000.x). Preferred over UGUI for new UI, including world-space since Unity 6 made it a first-class render mode.
UI Toolkit is a builtin editor module in Unity 6 — there is no com.unity.ui package to install.
Route to the right reference
Section titled “Route to the right reference”| You are doing… | Read |
|---|---|
| Authoring UXML, writing USS, fixing layout / “my element is 0-sized” | uxml-uss-and-patterns.md (references/uxml-uss-and-patterns.md) |
Binding UI to data (dataSource, SetBinding, [CreateProperty]) | data-binding.md (references/data-binding.md) |
Writing a custom VisualElement, or migrating off UxmlFactory/UxmlTraits | custom-controls.md (references/custom-controls.md) |
| UIDocument/PanelSettings, scale modes, world-space, safe area, Editor UI | runtime-panels-and-worldspace.md (references/runtime-panels-and-worldspace.md) |
| Picking a control, event handling, ListView/virtualization, performance | controls-events-and-performance.md (references/controls-events-and-performance.md) |
When to Use What
Section titled “When to Use What”| Feature | UI Toolkit | UGUI (Canvas) |
|---|---|---|
| Editor UI | Yes | No |
| Runtime menus/HUD | Yes (preferred) | Yes |
| World-space UI | Yes — Panel Settings Render Mode = World Space (Unity 6) | Yes, more battle-tested |
| Data binding | Built-in runtime binding system | Manual |
| Per-element 3D transform / custom shaders | Limited | Yes |
| Performance | Retained mode, batched | Immediate-mode rebuilds |
Prefer UI Toolkit for new work. Reach for UGUI when you need per-element custom shaders/materials, a mature world-space stack, or an existing UGUI codebase.
- Create a Panel Settings asset:
Assets → Create → UI Toolkit → Panel Settings - Create a UI Document (UXML):
Assets → Create → UI Toolkit → UI Document - Add a
UIDocumentcomponent to a GameObject → assign Panel Settings + the UXML source asset - Query and wire elements from
uiDocument.rootVisualElementinOnEnable
Unity 6 — what changed (a stale skill will get these wrong)
Section titled “Unity 6 — what changed (a stale skill will get these wrong)”- Runtime data binding exists.
element.dataSource+SetBinding("text", new DataBinding { … })with[CreateProperty]on the bound property. This is separate from the old Editor-onlySerializedObjectbinding. →references/data-binding.md - Custom controls use
[UxmlElement]/[UxmlAttribute]. The class must bepartial.UxmlFactory/UxmlTraitsare the legacy path. →references/custom-controls.md - World-space UI is a Render Mode, not a workaround. Set Panel Settings
Render Mode = World Spaceand add a Panel Input Configuration component for input. →references/runtime-panels-and-worldspace.md
Hard rules
Section titled “Hard rules”Q()returns null — name/type mismatch, or the UXML has not been cloned into the panel yet.- Styles not applying — the USS must be linked from UXML (
<Style src="…">) or added viastyleSheets.Add(); also check selector specificity. - Element invisible / zero-sized — almost always flexbox: no
flex-grow, no explicit size, or a parent with no height. See the troubleshooting list inuxml-uss-and-patterns.md. - Cached element references go stale —
rootVisualElementis rebuilt when theUIDocumentre-enables. Re-query inOnEnable; do not cache across disable/enable. - Pooled
ListViewitems bleed state —bindItemmust fully reset every visual it touches. - Invisible overlay eats taps — set
pickingMode = PickingMode.Ignoreon non-interactive overlays. - Fonts — use
-unity-font-definitionfor TextMeshPro font assets in USS.
Project conventions
Section titled “Project conventions”- UI is Tier-3 MonoBehaviour, never an ECS system. Menus, shops, HUD screens and settings are
stateful and small-data. In a plain MonoBehaviour project, drive them directly from your own
model/events. In a DOTS project (
Packages/manifest.jsonlistscom.unity.entities), drive them from a thin bridge that reads ECS singletons — seet1k-unity-dots-core-architecture. Do not introduce ECS types into a project that has none. - Addressables only — no
Resources.Loadin runtime asmdefs when loading UXML/USS assets. - C# style per
rules/code-conventions-unity.md: private fieldscamelCase(no underscore prefix),this.prefix,[SerializeField] private. - Avoid
System.Linqand per-frame string allocation in UI update paths; prefer ZString.
Related Skills & Agents
Section titled “Related Skills & Agents”t1k:unity:ui:ugui— Canvas/UGUI, plus the DOTS→UI bridge patterns (DOTS projects only)t1k:unity:ui:mobile-ui— touch ergonomics, thumb reach, portrait layoutt1k:unity:base:localization— localized UI stringst1k:unity:base:input-system— UI navigation inputt1k:unity:base:addressables— loading UI assets on demand
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
uxml-uss-and-patterns.md (references/uxml-uss-and-patterns.md) | UXML structure + templates, USS selectors/variables/transitions/theming, flexbox layout, zero-size troubleshooting, mobile sizing |
data-binding.md (references/data-binding.md) | Runtime binding vs legacy SerializedObject binding, dataSource/SetBinding/PropertyPath, [CreateProperty], BindingMode, change notification, converters, diagnostics |
custom-controls.md (references/custom-controls.md) | [UxmlElement]/[UxmlAttribute], migration off UxmlFactory/UxmlTraits, composite controls, custom painting, styling hooks |
runtime-panels-and-worldspace.md (references/runtime-panels-and-worldspace.md) | UIDocument/PanelSettings, scale modes for portrait mobile, world-space render mode + Panel Input Configuration, safe area, runtime input, Editor UI |
controls-events-and-performance.md (references/controls-events-and-performance.md) | Control catalogue, querying, event phases + key events, ListView/MultiColumn virtualization, performance and profiling |
Visual change notice
Section titled “Visual change notice”A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:
- Capture OLD before the first edit and NEW after the last (screen:
ScreenCapturein Play mode pert1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file). - Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries
visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending:”, never a fake image.