ENG2-P9-01: Scene inspector MVP (egui or web client over the MCP relay): entity tree + live component editing

[aram-devdocs]

Parent

• Program: ENG2 — GoudEngine v2 Rebuild (see the pinned master tracking issue)
• Phase / Milestone: Phase 9 — Authoring, Platforms, Examples & Polish (eng2-p9-authoring)
• Batch / Group: Batch 9.1 — Platforms & tooling (4 groups, parallel), Group A
• Runbook spec: docs/src/runbook/phases/phase-9.md (committed with the roadmap)

Summary

Build a scene inspector MVP (egui native client or web client) that connects over the existing MCP debugger relay, renders a live entity tree, and allows editing components on a running engine instance.

Architecture Context

Layer: Layer 5 (FFI) — new client sits outside goud_engine/src/, driven entirely through the existing MCP relay/debugger surface; no new engine-internal coupling. (see tools/lint_layers.rs — downward-only deps).
Modules/types touched:

• tools/goudengine-mcp/src/server/tools.rs — existing 20-tool MCP surface (incl. inspect_entity, capture_frame) this inspector consumes; read-only dependency, not modified unless a gap blocks the MVP.
• New inspector client (egui desktop app or web client) — new crate/package, outside the engine's layer hierarchy, talking to the relay over its existing protocol.

Boundary constraints (only those that apply):

• Raw GPU calls stay in libs/graphics/backend/ — no wgpu::/gl:: outside it.
• The inspector is a client of the MCP relay, not a new engine module — it MUST NOT reach into engine internals directly; all reads/writes go through the existing debugger tool surface.

Pattern to follow: tools/goudengine-mcp/src/server/tools.rs's existing tool set (inspect_entity, capture_frame, etc.) — the inspector is a UI layered on top of tools that already exist, not a new debugger transport.

Scope

• Stand up an inspector client (egui or web) that connects to the running MCP debugger relay.
• Render a live entity tree for the connected scene/context.
• Support live component editing on a selected entity, round-tripped through the existing MCP tool calls (not a new bespoke protocol).
• Handle relay disconnect/reconnect without crashing the client.
• Tests: spec test at goud_engine/tests/spec/ + unit/isolation coverage for the new code paths.
• Docs/rules updates if this invalidates .agents/rules/* or docs/src/*.

Acceptance Criteria

• Inspector connects to a running engine instance over the MCP relay and displays its live entity tree.
• Editing a component's field in the inspector visibly changes the running scene (verified against an S1-scale scene per the Phase 9 gate).
• No new engine-internal API is required beyond the existing MCP tool surface (or any gap found is documented and minimally extended in tools.rs, not worked around client-side).
• cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings clean; cargo test green; ./codegen.sh && git diff --exit-code (drift gate)

Breaking Change & Throne Follow-up

None — additive; this is a new external tool, not a change to any existing public engine/FFI/SDK surface.

Blocked By

ENG2-P7-06 (multi-window support — the inspector-as-a-window model depends on the engine's WindowId-keyed window collection).

Files Likely Touched

• New/Modified/Generated: new inspector client (crate/package location TBD by the implementing agent — egui desktop app or sdks/typescript-adjacent web client), no required changes to tools/goudengine-mcp/src/server/tools.rs unless a gap is found

Agent Notes

• The MCP debugger is real and already exposes 20 tools including inspect_entity and capture_frame — confirmed by reading tools/goudengine-mcp/src/server/tools.rs directly. Do not assume the debugger needs to be built; it exists.
• There is currently no authoring tool at all: scenes are code/JSON only. Scene loading is ffi/scene_loading.rs:47; prefabs live at context_registry/scene/prefab.rs. This issue is the first authoring surface layered on the existing (real) inspection/debugger machinery — it is not replacing or duplicating the relay.
• F21: Debugger, Observability & AI Agent Runtime Tools #136 (F21 debugger) is already closed as shipped; this issue is its authoring successor per the disposition map in design-technical.md section 12.

Verification

cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings
cargo test
./codegen.sh && git diff --exit-code