docs: add entity inspector implementation plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 10:50:34 +09:00
parent e14a53c3fa
commit 8ecf883ef6
1 changed files with 553 additions and 0 deletions
--- a/docs/superpowers/plans/2026-03-26-entity-inspector.md
+++ b/docs/superpowers/plans/2026-03-26-entity-inspector.md
@@ -0,0 +1,553 @@
+# 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:
+```toml
+voltex_ecs.workspace = true
+```
+
+- [ ] **Step 2: Write failing tests**
+
+Create `crates/voltex_editor/src/inspector.rs`:
+
+```rust
+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`:
+
+```rust
+/// 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.
+
+```rust
+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**
+
+```rust
+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**
+
+```bash
+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:
+
+```rust
+#[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:
+
+```rust
+/// 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**
+
+```bash
+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:
+```rust
+world: World,
+selected_entity: Option<Entity>,
+tag_buffer: String,
+```
+
+In `resumed`, after scene mesh creation, create ECS entities that mirror the scene:
+```rust
+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:
+```rust
+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**
+
+```bash
+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**
+
+```bash
+git add docs/STATUS.md docs/DEFERRED.md
+git commit -m "docs: update STATUS.md and DEFERRED.md with entity inspector"
+```