Editor UI Infrastructure

Editor UI Infrastructure

Table of Contents

1. Overview
2. When to Use
3. Conceptual Model
   • Drawers
   • Elements
   • FieldEditors
   • EditorUIConstants
4. Best Practices
5. Common Anti-Patterns
6. Integration Checklist
7. 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 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 (.obj, .fbx)
• ComponentSelector - Searchable component list for "Add Component"
• EntityContextMenu - Right-click menu (duplicate, delete, rename)
• PrefabManager - Prefab creation/instantiation

See references/elements-api.md for complete API reference and usage patterns.

FieldEditors

What: Generic type-safe editors for primitive types, used in component editors.

When: Use in component editors for properties (int, float, Vector3, string, bool).

Available: IFieldEditor for bool, int, float, double, string, Vector2, Vector3, Vector4

Key Example:

// ❌ WRONG - Direct ImGui calls
public class MyComponentEditor : IComponentEditor<MyComponent>
{
    public void DrawEditor(MyComponent component)
    {
        ImGui.DragFloat("Speed", ref component.Speed);
        ImGui.Checkbox("Enabled", ref component.IsEnabled);
    }
}

// ✅ CORRECT - Inject field editors
public class MyComponentEditor : IComponentEditor<MyComponent>
{
    private readonly IFieldEditor<float> _floatEditor;
    private readonly IFieldEditor<bool> _boolEditor;
    private readonly IFieldEditor<Vector3> _vectorEditor;

    public MyComponentEditor(
        IFieldEditor<float> floatEditor,
        IFieldEditor<bool> boolEditor,
        IFieldEditor<Vector3> vectorEditor)
    {
        _floatEditor = floatEditor;
        _boolEditor = boolEditor;
        _vectorEditor = vectorEditor;
    }

    public void DrawEditor(MyComponent component)
    {
        _floatEditor.DrawField("Speed", ref component.Speed);
        _boolEditor.DrawField("Enabled", ref component.IsEnabled);
        _vectorEditor.DrawField("Offset", ref component.Offset);
    }
}

Features:

• Automatic label rendering with PropertyLabelRatio (33/67 split)
• Consistent spacing using EditorUIConstants
• Drag behavior for numeric types
• Axis color coding for vectors (X=red, Y=green, Z=blue)
• Reset buttons for vectors (right-click)

Dependency Injection Pattern:

• Always inject field editors via constructor
• Registered in DryIoc container automatically
• Never create field editors inline

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 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. Inject Field Editors in Component Editors

Why: DI pattern, consistency, automatic layout ratios.

// Always inject field editors via primary constructor
public class MyComponentEditor(
    IFieldEditor<float> floatEditor,
    IFieldEditor<Vector3> vectorEditor) : IComponentEditor
{
    // Use in DrawEditor - injected parameters are available as fields
    public void DrawEditor()
    {
        floatEditor.DrawField("Speed", ref component.Speed);
        vectorEditor.DrawField("Position", ref component.Position);
    }
}

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: 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: 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: 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.