game_engine/docs/superpowers/plans/2026-03-26-entity-inspector.md

Entity Inspector Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add entity hierarchy tree and property inspector panels to the editor, supporting Transform/Tag/Parent component display and editing.

Architecture: Two public functions (hierarchy_panel, inspector_panel) in a new inspector.rs module that take UiContext + World and draw IMGUI widgets. No new structs needed. Copy-out pattern for Transform editing to avoid borrow conflicts. Tag editing via caller-owned staging buffer.

Tech Stack: Rust, voltex_ecs (World, Entity, Transform, Tag, Parent, Children, roots), voltex_editor (UiContext, Rect, LayoutState, widgets)

Spec: docs/superpowers/specs/2026-03-26-entity-inspector-design.md

---

Task 1: hierarchy_panel + tests

Files:

• Create: crates/voltex_editor/src/inspector.rs

• Modify: crates/voltex_editor/src/lib.rs

• Modify: crates/voltex_editor/Cargo.toml

• Step 1: Add voltex_ecs dependency

In crates/voltex_editor/Cargo.toml, add:

voltex_ecs.workspace = true

• Step 2: Write failing tests

Create crates/voltex_editor/src/inspector.rs:

use crate::ui_context::UiContext;
use crate::dock::Rect;
use crate::layout::LayoutState;
use voltex_ecs::world::World;
use voltex_ecs::entity::Entity;
use voltex_ecs::transform::Transform;
use voltex_ecs::scene::Tag;
use voltex_ecs::hierarchy::{roots, Children, Parent};

const COLOR_SELECTED: [u8; 4] = [0x44, 0x66, 0x88, 0xFF];
const COLOR_TEXT: [u8; 4] = [0xEE, 0xEE, 0xEE, 0xFF];
const LINE_HEIGHT: f32 = 16.0;
const INDENT: f32 = 16.0;
const PADDING: f32 = 4.0;

#[cfg(test)]
mod tests {
    use super::*;
    use voltex_math::Vec3;

    fn make_test_world() -> (World, Entity, Entity, Entity) {
        let mut world = World::new();
        let e1 = world.spawn();
        world.add(e1, Transform::from_position(Vec3::new(0.0, 0.0, 0.0)));
        world.add(e1, Tag("Root".to_string()));

        let e2 = world.spawn();
        world.add(e2, Transform::from_position(Vec3::new(1.0, 0.0, 0.0)));
        world.add(e2, Tag("Child1".to_string()));

        let e3 = world.spawn();
        world.add(e3, Transform::from_position(Vec3::new(2.0, 0.0, 0.0)));
        world.add(e3, Tag("Child2".to_string()));

        // e2, e3 are children of e1
        voltex_ecs::hierarchy::add_child(&mut world, e1, e2);
        voltex_ecs::hierarchy::add_child(&mut world, e1, e3);

        (world, e1, e2, e3)
    }

    #[test]
    fn test_count_nodes() {
        let (world, _, _, _) = make_test_world();
        let root_entities = roots(&world);
        let count: usize = root_entities.iter().map(|e| count_entity_nodes(&world, *e)).sum();
        assert_eq!(count, 3); // Root + Child1 + Child2
    }

    #[test]
    fn test_hierarchy_panel_draws_commands() {
        let (world, _, _, _) = make_test_world();
        let mut ui = UiContext::new(800.0, 600.0);
        let mut selected: Option<Entity> = None;
        let rect = Rect { x: 0.0, y: 0.0, w: 200.0, h: 400.0 };

        ui.begin_frame(0.0, 0.0, false);
        hierarchy_panel(&mut ui, &world, &mut selected, &rect);
        ui.end_frame();

        assert!(ui.draw_list.commands.len() > 0, "should draw entity names");
    }

    #[test]
    fn test_hierarchy_panel_click_selects() {
        let (world, e1, _, _) = make_test_world();
        let mut ui = UiContext::new(800.0, 600.0);
        let mut selected: Option<Entity> = None;
        let rect = Rect { x: 0.0, y: 0.0, w: 200.0, h: 400.0 };

        // Frame 1: mouse down on first entity row (y ~= PADDING, within LINE_HEIGHT)
        ui.begin_frame(50.0, PADDING + 2.0, true);
        hierarchy_panel(&mut ui, &world, &mut selected, &rect);
        ui.end_frame();

        assert_eq!(selected, Some(e1), "clicking first row should select root entity");
    }

    #[test]
    fn test_hierarchy_panel_empty_world() {
        let world = World::new();
        let mut ui = UiContext::new(800.0, 600.0);
        let mut selected: Option<Entity> = None;
        let rect = Rect { x: 0.0, y: 0.0, w: 200.0, h: 400.0 };

        ui.begin_frame(0.0, 0.0, false);
        hierarchy_panel(&mut ui, &world, &mut selected, &rect);
        ui.end_frame();

        assert!(selected.is_none());
    }
}

• Step 3: Run tests to verify they fail

Run: cargo test -p voltex_editor --lib inspector Expected: FAIL (functions don't exist)

• Step 4: Implement hierarchy_panel

Add implementation above tests in inspector.rs:

/// Count total nodes in the subtree rooted at entity (including self).
fn count_entity_nodes(world: &World, entity: Entity) -> usize {
    let mut count = 1;
    if let Some(children) = world.get::<Children>(entity) {
        for &child in &children.0 {
            count += count_entity_nodes(world, child);
        }
    }
    count
}

/// Draw a single entity row in the hierarchy tree.
fn draw_entity_node(
    ui: &mut UiContext,
    world: &World,
    entity: Entity,
    depth: usize,
    selected: &mut Option<Entity>,
    base_x: f32,
    row_w: f32,
) {
    let y = ui.layout.cursor_y;
    let x = base_x + PADDING + depth as f32 * INDENT;

    // Highlight selected
    if *selected == Some(entity) {
        ui.draw_list.add_rect(base_x, y, row_w, LINE_HEIGHT, COLOR_SELECTED);
    }

    // Click detection
    if ui.mouse_clicked && ui.mouse_in_rect(base_x, y, row_w, LINE_HEIGHT) {
        *selected = Some(entity);
    }

    // Build display text
    let has_children = world.get::<Children>(entity).map_or(false, |c| !c.0.is_empty());
    let prefix = if has_children { "> " } else { "  " };
    let name = if let Some(tag) = world.get::<Tag>(entity) {
        format!("{}{}", prefix, tag.0)
    } else {
        format!("{}Entity({})", prefix, entity.id)
    };

    // Draw text
    let gw = ui.font.glyph_width as f32;
    let gh = ui.font.glyph_height as f32;
    let text_y = y + (LINE_HEIGHT - gh) * 0.5;
    let mut cx = x;
    for ch in name.chars() {
        let (u0, v0, u1, v1) = ui.font.glyph_uv(ch);
        ui.draw_list.add_rect_uv(cx, text_y, gw, gh, u0, v0, u1, v1, COLOR_TEXT);
        cx += gw;
    }

    ui.layout.cursor_y += LINE_HEIGHT;

    // Recurse into children
    if let Some(children) = world.get::<Children>(entity) {
        let child_list: Vec<Entity> = children.0.clone();
        for child in child_list {
            draw_entity_node(ui, world, child, depth + 1, selected, base_x, row_w);
        }
    }
}

/// Draw the hierarchy panel showing entity tree.
pub fn hierarchy_panel(
    ui: &mut UiContext,
    world: &World,
    selected: &mut Option<Entity>,
    rect: &Rect,
) {
    let root_entities = roots(world);

    // Count total nodes for scroll content height
    let total_nodes: usize = root_entities.iter().map(|e| count_entity_nodes(world, *e)).sum();
    let content_height = total_nodes as f32 * LINE_HEIGHT + PADDING * 2.0;

    ui.begin_scroll_panel(
        9000, // unique scroll panel ID
        rect.x, rect.y, rect.w, rect.h,
        content_height,
    );

    ui.layout.cursor_y = rect.y + PADDING - ui.scroll_offsets.get(&9000).copied().unwrap_or(0.0);

    for &entity in &root_entities {
        draw_entity_node(ui, world, entity, 0, selected, rect.x, rect.w);
    }

    ui.end_scroll_panel();
}

Note: The scroll panel sets cursor position internally, but we need to manually track y for our custom row rendering. The begin_scroll_panel pushes a scissor rect — we draw inside that clipped area.

Actually, let's simplify: don't use scroll_panel for v1. The spec mentions it, but for a first pass with few entities, just set layout cursor and draw directly. Add scroll in a follow-up if needed, to keep this task focused.

Simplified: just set ui.layout = LayoutState::new(rect.x + PADDING, rect.y + PADDING) and draw rows. No scroll for now.

pub fn hierarchy_panel(
    ui: &mut UiContext,
    world: &World,
    selected: &mut Option<Entity>,
    rect: &Rect,
) {
    let root_entities = roots(world);
    ui.layout = LayoutState::new(rect.x + PADDING, rect.y + PADDING);

    for &entity in &root_entities {
        draw_entity_node(ui, world, entity, 0, selected, rect.x, rect.w);
    }
}

• Step 5: Add module to lib.rs

pub mod inspector;
pub use inspector::{hierarchy_panel, inspector_panel};

(inspector_panel will be a stub for now — pub fn inspector_panel(...) {})

• Step 6: Run tests

Run: cargo test -p voltex_editor --lib inspector -- --nocapture Expected: all 4 tests PASS

• Step 7: Commit

git add crates/voltex_editor/Cargo.toml crates/voltex_editor/src/inspector.rs crates/voltex_editor/src/lib.rs
git commit -m "feat(editor): add hierarchy_panel with entity tree display and selection"

---

Task 2: inspector_panel + tests

Files:

• Modify: crates/voltex_editor/src/inspector.rs

• Step 1: Write failing tests

Add to mod tests in inspector.rs:

#[test]
fn test_inspector_panel_no_selection() {
    let mut world = World::new();
    let mut ui = UiContext::new(800.0, 600.0);
    let rect = Rect { x: 0.0, y: 0.0, w: 300.0, h: 400.0 };

    ui.begin_frame(0.0, 0.0, false);
    let mut tag_buf = String::new();
    inspector_panel(&mut ui, &mut world, None, &rect, &mut tag_buf);
    ui.end_frame();

    // Should have drawn "No entity selected" text
    assert!(ui.draw_list.commands.len() > 0);
}

#[test]
fn test_inspector_panel_with_transform() {
    let mut world = World::new();
    let e = world.spawn();
    world.add(e, Transform::from_position(Vec3::new(1.0, 2.0, 3.0)));

    let mut ui = UiContext::new(800.0, 600.0);
    let rect = Rect { x: 0.0, y: 0.0, w: 300.0, h: 400.0 };

    ui.begin_frame(0.0, 0.0, false);
    let mut tag_buf = String::new();
    inspector_panel(&mut ui, &mut world, Some(e), &rect, &mut tag_buf);
    ui.end_frame();

    // Should have drawn Transform header + sliders
    // Sliders produce multiple draw commands (bg + handle + label text)
    assert!(ui.draw_list.commands.len() > 10);
}

#[test]
fn test_inspector_panel_with_tag() {
    let mut world = World::new();
    let e = world.spawn();
    world.add(e, Transform::new());
    world.add(e, Tag("TestTag".to_string()));

    let mut ui = UiContext::new(800.0, 600.0);
    let rect = Rect { x: 0.0, y: 0.0, w: 300.0, h: 400.0 };

    ui.begin_frame(0.0, 0.0, false);
    let mut tag_buf = String::new();
    inspector_panel(&mut ui, &mut world, Some(e), &rect, &mut tag_buf);
    ui.end_frame();

    // tag_buf should be synced to "TestTag"
    assert_eq!(tag_buf, "TestTag");
}

• Step 2: Run tests to verify they fail

Run: cargo test -p voltex_editor --lib inspector Expected: FAIL (inspector_panel is stub)

• Step 3: Implement inspector_panel

Replace the stub with:

/// Draw the inspector panel for the selected entity.
/// `tag_buffer` is a caller-owned staging buffer for Tag editing.
pub fn inspector_panel(
    ui: &mut UiContext,
    world: &mut World,
    selected: Option<Entity>,
    rect: &Rect,
    tag_buffer: &mut String,
) {
    ui.layout = LayoutState::new(rect.x + PADDING, rect.y + PADDING);

    let entity = match selected {
        Some(e) => e,
        None => {
            ui.text("No entity selected");
            return;
        }
    };

    // --- Transform ---
    if world.has_component::<Transform>(entity) {
        ui.text("-- Transform --");

        // Copy out values (immutable borrow ends here)
        let (px, py, pz, rx, ry, rz, sx, sy, sz) = {
            let t = world.get::<Transform>(entity).unwrap();
            (t.position.x, t.position.y, t.position.z,
             t.rotation.x, t.rotation.y, t.rotation.z,
             t.scale.x, t.scale.y, t.scale.z)
        };

        // Sliders (no world borrow)
        let new_px = ui.slider("Pos X", px, -50.0, 50.0);
        let new_py = ui.slider("Pos Y", py, -50.0, 50.0);
        let new_pz = ui.slider("Pos Z", pz, -50.0, 50.0);
        let new_rx = ui.slider("Rot X", rx, -3.15, 3.15);
        let new_ry = ui.slider("Rot Y", ry, -3.15, 3.15);
        let new_rz = ui.slider("Rot Z", rz, -3.15, 3.15);
        let new_sx = ui.slider("Scl X", sx, 0.01, 10.0);
        let new_sy = ui.slider("Scl Y", sy, 0.01, 10.0);
        let new_sz = ui.slider("Scl Z", sz, 0.01, 10.0);

        // Write back (mutable borrow)
        if let Some(t) = world.get_mut::<Transform>(entity) {
            t.position.x = new_px;
            t.position.y = new_py;
            t.position.z = new_pz;
            t.rotation.x = new_rx;
            t.rotation.y = new_ry;
            t.rotation.z = new_rz;
            t.scale.x = new_sx;
            t.scale.y = new_sy;
            t.scale.z = new_sz;
        }
    }

    // --- Tag ---
    if world.has_component::<Tag>(entity) {
        ui.text("-- Tag --");

        // Sync buffer from world if it doesn't match
        if let Some(tag) = world.get::<Tag>(entity) {
            if tag_buffer.is_empty() || *tag_buffer != tag.0 {
                *tag_buffer = tag.0.clone();
            }
        }

        let input_x = rect.x + PADDING;
        let input_y = ui.layout.cursor_y;
        let input_w = rect.w - PADDING * 2.0;
        if ui.text_input(8888, tag_buffer, input_x, input_y, input_w) {
            // Buffer changed — write back to world
            if let Some(tag) = world.get_mut::<Tag>(entity) {
                tag.0 = tag_buffer.clone();
            }
        }
        ui.layout.advance_line();
    }

    // --- Parent ---
    if let Some(parent) = world.get::<Parent>(entity) {
        ui.text("-- Parent --");
        let parent_text = format!("Parent: Entity({})", parent.0.id);
        ui.text(&parent_text);
    }
}

• Step 4: Update the function signature in lib.rs re-export

Make sure inspector_panel in pub use includes the new signature.

• Step 5: Run tests

Run: cargo test -p voltex_editor --lib inspector -- --nocapture Expected: all 7 tests PASS (4 hierarchy + 3 inspector)

• Step 6: Commit

git add crates/voltex_editor/src/inspector.rs
git commit -m "feat(editor): add inspector_panel with Transform, Tag, Parent editing"

---

Task 3: Integrate into editor_demo

Files:

• Modify: examples/editor_demo/src/main.rs

• Step 1: Add ECS World and demo entities

Read current examples/editor_demo/src/main.rs. Add to AppState:

world: World,
selected_entity: Option<Entity>,
tag_buffer: String,

In resumed, after scene mesh creation, create ECS entities that mirror the scene:

let mut world = World::new();
let ground = world.spawn();
world.add(ground, Transform::from_position(Vec3::new(0.0, 0.0, 0.0)));
world.add(ground, Tag("Ground".to_string()));

let cube1 = world.spawn();
world.add(cube1, Transform::from_position(Vec3::new(0.0, 0.5, 0.0)));
world.add(cube1, Tag("Cube1".to_string()));

let cube2 = world.spawn();
world.add(cube2, Transform::from_position(Vec3::new(2.0, 0.5, 1.0)));
world.add(cube2, Tag("Cube2".to_string()));

let cube3 = world.spawn();
world.add(cube3, Transform::from_position(Vec3::new(-1.5, 0.5, -1.0)));
world.add(cube3, Tag("Cube3".to_string()));

// Cube2 is child of Cube1
voltex_ecs::hierarchy::add_child(&mut world, cube1, cube2);

• Step 2: Wire panels to hierarchy/inspector

In the dock panel loop, replace panel 0 (Debug) with Hierarchy, and panel 2 (Properties) with Inspector:

0 => {
    // Hierarchy panel
    hierarchy_panel(&mut state.ui, &state.world, &mut state.selected_entity, rect);
}
// ... panel 1 stays as viewport ...
2 => {
    // Inspector panel
    inspector_panel(&mut state.ui, &mut state.world, state.selected_entity, rect, &mut state.tag_buffer);
}

Update dock panel names to ["Hierarchy", "Viewport", "Inspector", "Console"].

• Step 3: Build and test

Run: cargo build -p editor_demo Expected: compiles

Run: cargo test -p voltex_editor -- --nocapture Expected: all tests pass

• Step 4: Commit

git add examples/editor_demo/src/main.rs
git commit -m "feat(editor): integrate hierarchy and inspector panels into editor_demo"

---

Task 4: Update docs

Files:

• Modify: docs/STATUS.md

• Modify: docs/DEFERRED.md

• Step 1: Update STATUS.md

Add to Phase 8-4:

- voltex_editor: hierarchy_panel, inspector_panel (Transform/Tag/Parent editing)

Update test count.

• Step 2: Update DEFERRED.md

- ~~**엔티티 인스펙터**~~ ✅ Transform/Tag/Parent 편집 완료. 커스텀 컴포넌트 리플렉션 미구현.

• Step 3: Commit

git add docs/STATUS.md docs/DEFERRED.md
git commit -m "docs: update STATUS.md and DEFERRED.md with entity inspector"