Editor UI Infrastructure

Table of Contents

1. [Overview](#overview)
2. [When to Use](#when-to-use)
3. [Conceptual Model](#conceptual-model)

- [Drawers](#drawers) - [Elements](#elements) - [FieldEditors](#fieldeditors) - [EditorUIConstants](#editoruiconstants)

1. [Best Practices](#best-practices)
2. [Common Anti-Patterns](#common-anti-patterns)
3. [Integration Checklist](#integration-checklist)
4. [Reference Documentation](#reference-documentation)

Overview

The Editor UI infrastructure provides four layers of reusable UI components ensuring consistent styling and behavior across all editor panels and component editors.

Golden Rule: Never reimplement existing UI patterns. Always check if a Drawer, Element, or FieldEditor exists before writing custom ImGui code.

Benefits:

• Visual consistency across all editor panels
• Reduced code duplication
• Easier maintenance and global style changes
• Better user experience through familiar patterns

When to Use

Invoke this skill when:

• ✅ Implementing editor panels or component editors
• ✅ Adding UI elements to existing panels
• ✅ Questions about which UI utility to use
• ✅ Implementing drag-and-drop functionality
• ✅ Creating modal dialogs or confirmation prompts
• ✅ Rendering tables, trees, or structured data
• ✅ Adding buttons with consistent styling
• ✅ Working with field editors for primitive types

Conceptual Model

Drawers

What: Static utility classes for common UI patterns with consistent styling.

When: Use for standard UI operations (buttons, modals, tables, spacing, text).

Available: ButtonDrawer, ModalDrawer, TableDrawer, TreeDrawer, LayoutDrawer, TextDrawer, DragDropDrawer

Key Example:

// ❌ WRONG - Raw ImGui
if (ImGui.Button("Save", new Vector2(120, 30)))
    Save();

// ✅ CORRECT - Use ButtonDrawer
if (ButtonDrawer.DrawButton("Save", onClick: Save))
{
    // Additional logic if needed
}

Features:

• Automatic sizing via EditorUIConstants
• Semantic color coding (Error/Warning/Success/Info)
• Tooltip support
• Callback-based API reduces boilerplate

Common Methods:

• ButtonDrawer.DrawButton() - Standard button
• ButtonDrawer.DrawColoredButton() - Semantic colored button (red/green/yellow/blue)
• ModalDrawer.RenderConfirmationModal() - OK/Cancel dialog
• TableDrawer.BeginTable() - Consistent table rendering
• TreeDrawer.BeginTreeNode() - Expandable tree nodes
• LayoutDrawer.DrawSpacing() - Consistent vertical spacing
• TextDrawer.DrawText() - Colored text (Error/Warning/Success/Info)

See [references/drawers-api.md](references/drawers-api.md) for complete API reference (15+ button variants, modal types, etc.).

Elements

What: Complex, stateful UI components for specific interactions.

When: Use for specialized interactions (drag-drop, component selection, context menus).

Available: TextureDropTarget, AudioDropTarget, MeshDropTarget, ComponentSelector, EntityContextMenu, PrefabManager

Key Example:

// ❌ WRONG - Custom drag-drop implementation
ImGui.Button("Texture");
if (ImGui.BeginDragDropTarget())
{
    // Complex validation, error handling, visual feedback...
}

// ✅ CORRECT - Use specialized drop target
TextureDropTarget.Draw("Texture",
    currentPath: component.TexturePath,
    onTextureChanged: path => component.TexturePath = path,
    assetsManager: _assetsManager
);

Features:

• Built-in validation (file extensions, asset existence)
• Visual feedback (hover highlights, error messages)
• Consistent error handling
• Asset manager integration

Common Elements:

• TextureDropTarget - Texture files (.png, .jpg)
• AudioDropTarget - Audio files (.wav, .ogg)
• MeshDropTarget - Mesh files (.mesh)
• ComponentSelector - Searchable component list for "Add Component"
• EntityContextMenu - Right-click menu (duplicate, delete, rename)
• PrefabManager - Prefab creation/instantiation

See [references/elements-api.md](references/elements-api.md) for complete API reference and usage patterns.

FieldEditors

What: Non-generic, boxing-based editors for types discovered via reflection at runtime. Used exclusively by the script inspector (ScriptComponentEditor) to render public fields of NativeScript subclasses.

When: Use when implementing custom rendering for a new type in the script inspector. Do not use in component editors — component editors use UIPropertyRenderer and VectorPanel instead (see below).

Available: Built-in editors for int, float, double, bool, string, Vector2, Vector3, Vector4. Add new types via FieldEditorRegistry.

Interface (Editor/UI/FieldEditors/IFieldEditor.cs):

public interface IFieldEditor
{
    bool Draw(string label, object value, out object newValue);
}

How it works: FieldEditorRegistry.GetEditor(type) returns the matching IFieldEditor?. The script inspector calls editor.Draw(label, boxedValue, out newBoxedValue) and uses reflection to write the result back.

For component editors, use UIPropertyRenderer and VectorPanel instead — they avoid boxing and are the correct pattern:

// ✅ CORRECT - Component editor (known types, no boxing)
UIPropertyRenderer.DrawPropertyField("Speed", component.Speed,
    newValue => component.Speed = (float)newValue);

var pos = component.Position;
VectorPanel.DrawVec3Control("Position", ref pos);
if (pos != component.Position) component.Position = pos;

See editor-field-creation skill for full details on implementing custom IFieldEditor types.

EditorUIConstants

What: Centralized constants for consistent styling across all UI.

When: Use for ALL sizing, spacing, colors (never hardcode values).

Key Categories:

• Button Sizes: StandardButtonWidth (120), StandardButtonHeight (30)
• Layout Ratios: PropertyLabelRatio (0.33f), PropertyInputRatio (0.67f)
• Spacing: StandardPadding (8), LargePadding (16), SmallPadding (4)
• Colors: ErrorColor (red), WarningColor (yellow), SuccessColor (green), InfoColor (blue)
• Axis Colors: AxisXColor (red), AxisYColor (green), AxisZColor (blue)
• Input Buffers: MaxNameLength (128), MaxPathLength (512)

Key Example:

// ❌ WRONG - Magic numbers
ImGui.Button("Export", new Vector2(150, 35));
ImGui.Dummy(new Vector2(0, 10));
ImGui.PushStyleColor(ImGuiCol.Text, new Vector4(1, 0, 0, 1));

// ✅ CORRECT - Use constants
ButtonDrawer.DrawButton("Export",
    width: EditorUIConstants.WideButtonWidth,
    height: EditorUIConstants.StandardButtonHeight);
LayoutDrawer.DrawSpacing();
ImGui.PushStyleColor(ImGuiCol.Text, EditorUIConstants.ErrorColor);

Golden Rule: EditorUIConstants is the ONLY static class allowed in the codebase (all other code uses DI).

See [references/constants-catalog.md](references/constants-catalog.md) for complete catalog and design rationale.

Best Practices

1. Always Use Drawers Over Raw ImGui

Why: Ensures consistency, automatic sizing, proper callbacks.

// Use ButtonDrawer for all buttons
ButtonDrawer.DrawButton("Save");
ButtonDrawer.DrawColoredButton("Delete", MessageType.Error);

// Use ModalDrawer for confirmations
ModalDrawer.RenderConfirmationModal("Delete?", ref _show, "Sure?", () => Delete());

// Use LayoutDrawer for spacing
LayoutDrawer.DrawSpacing(); // Not ImGui.Dummy()

2. Use Specialized Drop Targets for Asset References

Why: Built-in validation, error handling, visual feedback.

// Use TextureDropTarget for textures
TextureDropTarget.Draw("Texture", onTextureChanged, assetsManager);

// Use AudioDropTarget for audio
AudioDropTarget.Draw("Audio Clip", onAudioChanged, assetsManager);

// Use MeshDropTarget for meshes
MeshDropTarget.Draw("Mesh", onMeshChanged, assetsManager);

3. Use UIPropertyRenderer and VectorPanel in Component Editors

Why: Component types are known at compile time — no boxing needed. IFieldEditor is for the script inspector only (reflection-based, runtime types).

// ✅ CORRECT - primitives via UIPropertyRenderer
UIPropertyRenderer.DrawPropertyField("Speed", component.Speed,
    newValue => component.Speed = (float)newValue);

UIPropertyRenderer.DrawPropertyField("Enabled", component.IsEnabled,
    newValue => component.IsEnabled = (bool)newValue);

// ✅ CORRECT - vectors via VectorPanel (axis colors, reset buttons)
var pos = component.Position;
VectorPanel.DrawVec3Control("Position", ref pos);
if (pos != component.Position) component.Position = pos;

// ❌ WRONG - IFieldEditor<T> doesn't exist; don't use IFieldEditor in component editors
_floatEditor.DrawField("Speed", ref component.Speed);

4. Use EditorUIConstants for All Sizing/Spacing

Why: Global style changes, visual consistency, no magic numbers.

// Always use constants
ButtonDrawer.DrawButton("Export",
    width: EditorUIConstants.WideButtonWidth);
LayoutDrawer.DrawSpacing(EditorUIConstants.LargePadding);
ImGui.PushStyleColor(ImGuiCol.Text, EditorUIConstants.ErrorColor);

// NEVER hardcode
ImGui.Button("Export", new Vector2(150, 35)); // ❌ WRONG
ImGui.Dummy(new Vector2(0, 10)); // ❌ WRONG

5. Use Semantic Colors for Actions

Why: Visual consistency, user expectations (red=danger, green=success).

// Destructive actions = Error (red)
ButtonDrawer.DrawColoredButton("Delete", MessageType.Error);
TextDrawer.DrawText("Validation failed", MessageType.Error);

// Confirmations = Success (green)
ButtonDrawer.DrawColoredButton("Save", MessageType.Success);
TextDrawer.DrawText("Saved successfully!", MessageType.Success);

// Cautions = Warning (yellow)
TextDrawer.DrawText("Overwriting existing file", MessageType.Warning);

6. Prefer ComponentSelector/EntityContextMenu Over Custom Menus

Why: Consistent UX, keyboard navigation, automatic component discovery.

// Use ComponentSelector for "Add Component"
private readonly ComponentSelector _selector = new();

if (ButtonDrawer.DrawButton("Add Component"))
    _selector.Show(entity);
_selector.Draw(); // Call every frame

// Use EntityContextMenu for right-click
private readonly EntityContextMenu _contextMenu = new();

if (ImGui.IsItemClicked(ImGuiMouseButton.Right))
    _contextMenu.Show(entity, scene);
_contextMenu.Draw(); // Call every frame

Common Anti-Patterns

1. Bypassing UI Infrastructure

Problem: Inconsistent sizing, breaks global style changes, harder to maintain.

// ❌ WRONG - Raw ImGui
if (ImGui.Button("Save", new Vector2(120, 30)))
    Save();
ImGui.SetNextItemWidth(200);

// ✅ CORRECT - Use infrastructure
if (ButtonDrawer.DrawButton("Save"))
    Save();
ImGui.SetNextItemWidth(EditorUIConstants.DefaultColumnWidth);

Why It's Bad: Hardcoded values prevent global style updates, break visual consistency.

2. Custom Drag-Drop Logic

Problem: Complex validation, error handling, visual feedback must be reimplemented.

// ❌ WRONG - Manual implementation
if (ImGui.BeginDragDropTarget())
{
    var payload = ImGui.AcceptDragDropPayload("CONTENT_BROWSER_ITEM");
    if (payload.NativePtr != null)
    {
        // File extension validation
        // Path validation
        // Error messages
        // Visual feedback
    }
}

// ✅ CORRECT - Use specialized target
TextureDropTarget.Draw("Texture", onChange, assetsManager);

Why It's Bad: Drop targets handle validation, errors, and visual feedback automatically.

3. Inline Field Editors

Problem: Breaks DI pattern, inconsistent layout ratios, no axis coloring.

// ❌ WRONG - Direct ImGui
ImGui.DragFloat("Speed", ref speed);
ImGui.DragFloat3("Position", ref position);

// ✅ CORRECT - Inject and use field editors
_floatEditor.DrawField("Speed", ref speed);
_vectorEditor.DrawField("Position", ref position); // Automatic X/Y/Z colors

Why It's Bad: Loses PropertyLabelRatio (33/67 split), axis color coding, reset buttons.

Integration Checklist

When implementing editor UI, ensure:

• All buttons use ButtonDrawer (not raw ImGui.Button)
• All asset references use drag-drop targets (TextureDropTarget, AudioDropTarget, etc.)
• All component editors inject field editors for primitive types
• All sizes/spacing use EditorUIConstants (no magic numbers)
• All colors use EditorUIConstants (ErrorColor, SuccessColor, AxisXColor, etc.)
• All modals use ModalDrawer.RenderConfirmationModal()
• All tables use TableDrawer.BeginTable()
• All trees use TreeDrawer
• All tooltips use LayoutDrawer.DrawTooltip()
• All spacing uses LayoutDrawer.DrawSpacing()

Reference Documentation

API References

Detailed API documentation for each infrastructure layer:

• [references/drawers-api.md](references/drawers-api.md): Complete Drawer APIs

- ButtonDrawer (15+ button variants) - ModalDrawer (confirmation dialogs, custom modals) - TableDrawer, TreeDrawer, LayoutDrawer, TextDrawer, DragDropDrawer - Common patterns and usage examples

• [references/elements-api.md](references/elements-api.md): Complete Element APIs

- Drag-drop targets (Texture, Audio, Mesh, Prefab) - ComponentSelector (searchable component list) - EntityContextMenu (right-click operations) - PrefabManager (prefab creation/instantiation)

• [references/constants-catalog.md](references/constants-catalog.md): EditorUIConstants Catalog

- Complete constant listing (button sizes, spacing, colors) - Design rationale (why PropertyLabelRatio = 0.33f, etc.) - Usage guidelines and quick reference

Related Files

• Editor/UI/Drawers/ - All drawer implementations
• Editor/UI/Elements/ - All element implementations
• Editor/UI/FieldEditors/ - All field editor implementations
• Editor/UI/Constants/EditorUIConstants.cs - Constant definitions

Summary

The Editor UI infrastructure provides four layers:

1. Drawers (7 classes): Static utilities for common patterns (buttons, modals, tables)
2. Elements (9 components): Stateful components for complex interactions (drop targets, selectors)
3. FieldEditors (8 generic types): Type-safe editors for component properties
4. EditorUIConstants (30+ constants): Centralized styling values

Key Principle: Never reimplement existing patterns. Check Drawers/Elements/FieldEditors first, then write custom ImGui code only if no match exists.