create-world-ui

name	create-world-ui
description	Create a World Space (diegetic) UI panel using UI Toolkit — UXML, USS, PanelSettings, UIDocument. Use when the user wants in-world UI like pit boards, machine displays, signage, or any 3D-positioned UI element.

Create World Space UI

Create a diegetic (in-world) UI panel using UI Toolkit: USS stylesheet, UXML document, PanelSettings asset, and UIDocument GameObject placed in 3D space.

Arguments

• name (required): PascalCase name for the UI document (e.g., "PitBoard", "LapCounter", "TrackSignage")
• description (required): What the UI should display — used to design UXML structure and USS styling
• style (optional): Visual style hint — defaults to R8EOX dark-noir motorsport terminal aesthetic
• elements (optional): Specific UI elements to include (labels, buttons, lists, etc.)
• scene (optional): Scene to place the UIDocument in — defaults to currently active scene
• position (optional): World-space position as x,y,z — defaults to 0,1.5,0
• rotation (optional): Euler rotation as x,y,z — defaults to 0,0,0
• scale (optional): Transform scale — defaults to 0.001 (makes a 1920x1080 panel ~1.9m wide)
• width (optional): Panel resolution width in pixels — defaults to 1920
• height (optional): Panel resolution height in pixels — defaults to 1080

Steps

1. Create USS Stylesheet

Use mcp__UnityMCP__manage_ui with action: "create", path: "Assets/UI/{name}/{name}.uss".

Generate USS based on description and style arguments, using the R8EOX design system:

/* R8EOX color palette for USS */
.root {
    background-color: rgba(20, 21, 26, 0.97);  /* PanelBg */
    padding: 16px;
    flex-direction: column;
    align-items: center;
}

.title-label {
    color: rgb(255, 255, 255);
    font-size: 24px;
    -unity-text-align: middle-center;
    margin-bottom: 12px;
}

.accent-text {
    color: rgb(0, 200, 255);  /* Primary cyan */
}

.action-button {
    background-color: rgb(20, 21, 26);     /* ButtonFill */
    color: rgb(0, 200, 255);               /* Primary */
    border-color: rgba(0, 200, 255, 0.3);  /* BorderStrong */
    border-width: 1px;
    padding: 8px 16px;
}

.action-button:hover {
    background-color: rgb(25, 26, 33);     /* SurfaceHover */
    border-color: rgba(0, 200, 255, 0.5);  /* BorderHalf */
}

.muted-text {
    color: rgb(136, 136, 136);  /* MutedText */
    font-size: 14px;
}

Key USS rules:

• Use rgba() / rgb() color values matching UIColors.cs
• Include :hover and :active pseudo-classes for interactive elements
• Use flex layout (all Visual Elements are flex by default)
• -unity-text-align instead of CSS text-align

2. Create UXML Document

Use mcp__UnityMCP__manage_ui with action: "create", path: "Assets/UI/{name}/{name}.uxml".

Structure:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
    <ui:VisualElement class="root">
        <ui:Label text="Title" class="title-label" />
        <!-- Elements per description argument -->
    </ui:VisualElement>
</ui:UXML>

CRITICAL: Do NOT include a <Style> or <ui:Style> element in the UXML — that is added automatically in Step 3.

3. Link Stylesheet to UXML

Use mcp__UnityMCP__manage_ui with:

• action: "link_stylesheet"
• path: "Assets/UI/{name}/{name}.uxml"
• stylesheet: "Assets/UI/{name}/{name}.uss"

This adds <ui:Style src="..."> with the correct ui: namespace prefix. Using bare <Style> without the prefix causes UI Builder to fail.

4. Create PanelSettings Asset

Use mcp__UnityMCP__manage_ui with:

• action: "create_panel_settings"
• path: "Assets/UI/{name}/{name}_PanelSettings.asset"
• width: {width} (default 1920)
• height: {height} (default 1080)
• settings:

{
  "renderMode": "WorldSpace",
  "referenceResolution": { "x": 1920, "y": 1080 },
  "scaleMode": "ConstantPixelSize"
}

5. Check Console

Use mcp__UnityMCP__read_console to verify no errors from asset creation.

6. Commit Each Asset

Commit each file individually with its .meta:

git add "Assets/UI/{name}/{name}.uss" "Assets/UI/{name}/{name}.uss.meta"
git commit -m "feat: add {name} World Space USS stylesheet"

git add "Assets/UI/{name}/{name}.uxml" "Assets/UI/{name}/{name}.uxml.meta"
git commit -m "feat: add {name} World Space UXML document"

git add "Assets/UI/{name}/{name}_PanelSettings.asset" "Assets/UI/{name}/{name}_PanelSettings.asset.meta"
git commit -m "feat: add {name} World Space PanelSettings"

Also commit the Assets/UI/{name}/ folder .meta and Assets/UI/ folder .meta if newly created.

7. Create UIDocument GameObject in Scene

Use mcp__UnityMCP__batch_execute to atomically:

1. Create GameObject named {name}_WorldUI at specified position/rotation/scale:

   { "tool": "manage_gameobject", "params": {
       "action": "create", "name": "{name}_WorldUI",
       "position": { "x": 0, "y": 1.5, "z": 0 },
       "rotation": { "x": 0, "y": 0, "z": 0 },
       "scale": { "x": 0.001, "y": 0.001, "z": 0.001 }
   }}
   

2. Attach UIDocument component:

   { "tool": "manage_ui", "params": {
       "action": "attach_ui_document",
       "target": "{name}_WorldUI",
       "source_asset": "Assets/UI/{name}/{name}.uxml",
       "panel_settings": "Assets/UI/{name}/{name}_PanelSettings.asset"
   }}
   

3. Save:

   { "tool": "execute_menu_item", "params": { "item_path": "R8EOX/Save All" }}
   

8. Verify Visual Tree

Use mcp__UnityMCP__manage_ui with action: "get_visual_tree", target: "{name}_WorldUI" to confirm the UI document loaded correctly.

9. Check Console Again

mcp__UnityMCP__read_console for runtime errors.

10. Commit Scene

git add "Assets/Scenes/{active_scene}.unity"
git commit -m "feat: add {name} World Space UIDocument to scene"

11. Create Folder CLAUDE.md

Create Assets/UI/{name}/CLAUDE.md documenting the folder contents. Commit immediately.

If Assets/UI/CLAUDE.md doesn't exist, create it too and update Assets/CLAUDE.md.

12. Render Preview

Use mcp__UnityMCP__manage_ui with action: "render_ui", target: "{name}_WorldUI" to capture a preview screenshot for user verification.

13. Report Results

Summarize: files created, world position, panel dimensions, and preview image.

Notes

UI Toolkit Fundamentals

• UXML = structure (like HTML), USS = styling (like CSS)
• <ui:UXML xmlns:ui="UnityEngine.UIElements"> is the required root element
• USS uses Unity-specific properties: -unity-font-size, -unity-text-align, -unity-font-style
• All Visual Elements use flexbox layout by default — no display: flex needed
• com.unity.modules.uielements is already present in the project (no package install needed)

World Space Specifics

• PanelSettings renderMode: "WorldSpace" is what makes this in-world instead of screen overlay
• The UIDocument GameObject's Transform controls position/rotation/scale in 3D space
• Default scale 0.001 makes a 1920x1080 panel roughly 1.9m wide in world units — adjust for your scene
• For interactive panels (clickable buttons), ensure PanelRaycaster or EventSystem ray-casting is configured
• Sort Order on UIDocument controls render priority when multiple panels overlap

R8EOX Design System (USS Colors)

• Panel BG: rgba(20, 21, 26, 0.97) — PanelBg
• Primary Cyan: rgb(0, 200, 255) — Primary
• Danger Red: rgb(255, 81, 84) — Danger
• Warning Gold: rgb(232, 184, 73) — Warning
• Button Fill: rgb(20, 21, 26) — ButtonFill
• Border Strong: rgba(0, 200, 255, 0.3) — BorderStrong
• Border Half: rgba(0, 200, 255, 0.5) — BorderHalf
• Muted Text: rgb(136, 136, 136) — MutedText
• Surface Hover: rgb(25, 26, 33) — SurfaceHover

Scale Reference

Transform Scale	1920x1080 Panel Size	Use Case
0.0005	~0.96m wide	Small labels, item tags
0.001	~1.92m wide	Pit boards, displays
0.002	~3.84m wide	Large signage, billboards
0.005	~9.6m wide	Jumbotron-scale

Commit Rules — No Exceptions

• One file per commit, committed immediately after creation
• Always include companion .meta files
• git add -A / git add . / --no-verify = BANNED