From f10c30bfe73f808e1097985ef822018b003abb19 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 30 Apr 2026 14:42:30 +0100 Subject: [PATCH] Prioritize resident Unity editor bridge --- notes/epiphany-fork-implementation-plan.md | 14 +- .../epiphany-rider-unity-integration-plan.md | 154 +++++++++++++++--- notes/fresh-workspace-handoff.md | 10 +- state/evidence.jsonl | 1 + state/map.yaml | 7 +- 5 files changed, 155 insertions(+), 31 deletions(-) diff --git a/notes/epiphany-fork-implementation-plan.md b/notes/epiphany-fork-implementation-plan.md index 2393e9a9..6333b4b6 100644 --- a/notes/epiphany-fork-implementation-plan.md +++ b/notes/epiphany-fork-implementation-plan.md @@ -261,9 +261,15 @@ tree, diffs, diagnostics, and code refs; Epiphany GUI is the agent dashboard for objectives, specialist lanes, logs/artifacts, persisted state, and graph/control-flow views; Unity is the pinned runtime environment for tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence. The -adjacent EpiphanyGraph React viewer is the preferred seed for GUI graph -diagramming because it consumes typed `graphs.architecture`, -`graphs.dataflow`, and `graphs.links` directly. +Unity side must become editor-resident, not merely command-line: an +Aetheria-side Unity Editor package should inspect scenes, prefabs, serialized +component fields, prefab overrides, materials, shaders, ScriptableObjects, and +asset references through Unity APIs such as `SerializedObject`, +`AssetDatabase`, `PrefabUtility`, and `EditorSceneManager`, with typed +artifacts and explicit dry-run/apply boundaries for refactors. The adjacent +EpiphanyGraph React viewer is the preferred seed for GUI graph diagramming +because it consumes typed `graphs.architecture`, `graphs.dataflow`, and +`graphs.links` directly. ## Phase 6 Direction @@ -271,7 +277,7 @@ Phase 6 should grow observable harness state outward from the typed spine. Useful candidates: -1. Build the three-pronged Rider/Epiphany GUI/Unity workflow before the next Aetheria implementation dogfood run: named Unity bridge operations, Aetheria-side Unity editor package probes, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. +1. Build the three-pronged Rider/Epiphany GUI/Unity workflow before the next Aetheria implementation dogfood run: Aetheria-side resident Unity editor package, named Unity bridge operations over that package, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. 2. Use the next dogfood run to test the bridge-equipped loop, not to discover again that Epiphany cannot prove runtime/editor assumptions from source inspection alone. 3. Keep dogfood execution agent-run and auditable through the fixed-lane coordinator and GUI/operator view over the same status/artifact surfaces once the bridges exist. 4. Keep accepted worker findings review-gated; do not convert acceptance into automatic promotion of arbitrary worker output. diff --git a/notes/epiphany-rider-unity-integration-plan.md b/notes/epiphany-rider-unity-integration-plan.md index 4d47f1b7..efd67c31 100644 --- a/notes/epiphany-rider-unity-integration-plan.md +++ b/notes/epiphany-rider-unity-integration-plan.md @@ -28,7 +28,14 @@ The plan assumes current public seams rather than folklore: - Unity can be driven through explicit editor command-line operations such as `-batchmode`, `-quit`, `-projectPath`, `-executeMethod`, and test runner flags like `-runTests` / `-testResults`. + - Unity command-line arguments: - Unity command-line tests: +- Unity editor tooling can inspect and edit Unity-owned serialized state through + editor APIs rather than text-parsing `.unity` and `.prefab` YAML. + - `SerializedObject` / `SerializedProperty`: + - `AssetDatabase`: + - `PrefabUtility`: + - `EditorSceneManager`: These seams are enough. We do not need to build a magical all-knowing IDE worm. We need a few sober pipes that tell the truth. @@ -153,6 +160,10 @@ It should expose: - asset database refresh and compilation status - edit-mode and play-mode tests - scene, prefab, material, shader, and ScriptableObject facts +- Unity-serialized component fields through `SerializedObject` / + `SerializedProperty` +- prefab instance overrides and prefab asset operations through `PrefabUtility` +- scene loading, saving, and setup inspection through `EditorSceneManager` - targeted runtime probes - logs, screenshots, probe JSON, and test results as artifacts - scene configuration inspection and explicit bridge-owned scene/probe actions @@ -162,6 +173,16 @@ IDE, and not a place where agents get to freehand process launches. Runtime truth comes from the pinned Unity bridge and its artifacts, or it does not count. +The key distinction: Epiphany should not treat scene and prefab files as merely +text. A lot of the real game configuration lives in Unity's serialized object +model: component fields, prefab overrides, material references, shader links, +scene object hierarchies, asset GUIDs, ScriptableObject references, and import +state. Text parsing can sometimes help explain a file, but it cannot safely +answer or refactor most editor-level questions. For those, Epiphany needs a +resident Unity editor package that can walk Unity objects using Unity's own +editor APIs, write typed artifacts, and perform narrow, reviewable mutations +only when explicitly authorized. + ### Full Workflow Contract The three panes should behave like one agent-enabled development surface: @@ -278,6 +299,11 @@ Unity may: - run explicit probes through a pinned editor process - run edit-mode/play-mode tests through bridge-owned command lines - refresh assets and report compile/domain reload status when explicitly asked +- inspect scene hierarchy, prefab assets, prefab instances, prefab overrides, + materials, shaders, ScriptableObjects, asset GUIDs, and serialized component + properties from inside the Editor +- perform narrow editor-owned refactors only through explicit reviewed bridge + commands with before/after artifacts - write JSON artifacts, logs, screenshots, and probe outputs Unity must not: @@ -286,8 +312,11 @@ Unity must not: - substitute nearby Hub versions for the pinned editor - continue into play mode/probes after compilation failure unless the requested probe explicitly allows failure capture -- apply scene/prefab/asset mutations without an explicit bridge command and - artifact receipt +- apply scene/prefab/asset mutations without an explicit bridge command, + dry-run/preview artifact when feasible, and final artifact receipt +- let implementation workers edit Unity serialized YAML directly for + nontrivial scene/prefab refactors when Unity APIs can perform the operation + with object identity intact - become the coordinator ### Epiphany Boundary @@ -472,7 +501,7 @@ Required invariant: - exact `ProjectSettings/ProjectVersion.txt` editor version or blocked. -### Phase U1: Unity Editor Package +### Phase U1: Resident Unity Editor Package Add an Aetheria-side package, preferably UPM-shaped: @@ -485,6 +514,8 @@ Packages/com.gamecult.epiphany.unity/ EpiphanyArtifactWriter.cs EpiphanyCompilationProbe.cs EpiphanySceneProbe.cs + EpiphanyPrefabProbe.cs + EpiphanySerializedObjectProbe.cs EpiphanyShaderProbe.cs ``` @@ -498,7 +529,10 @@ Use `Packages/` once the bridge starts to stabilize. For the first Aetheria pass, `Assets/Editor/Epiphany` is acceptable if speed matters more than package cleanliness. -The Unity package exposes static `-executeMethod` targets: +This package is the real Unity organ. It lives inside the Editor so Epiphany can +inspect Unity-owned object state instead of guessing from serialized text. + +The first package exposes static `-executeMethod` targets: ```csharp Epiphany.EditorBridge.InspectProject @@ -508,15 +542,48 @@ Epiphany.EditorBridge.RunEditModeTests Epiphany.EditorBridge.RunPlayModeTests Epiphany.EditorBridge.RunProbe Epiphany.EditorBridge.CaptureSceneFacts +Epiphany.EditorBridge.CapturePrefabFacts +Epiphany.EditorBridge.CaptureSerializedObjectFacts Epiphany.EditorBridge.CaptureShaderFacts ``` All methods write JSON artifacts under a bridge-provided output directory. +Initial editor-resident probes: + +- **Scene object graph** + - open or inspect target scenes through `EditorSceneManager` + - enumerate root GameObjects, children, components, enabled state, layers, + tags, serialized fields, object references, and missing scripts + - report scene dirtiness and save requirements without saving by default +- **Prefab graph** + - load prefab assets through `AssetDatabase` + - report prefab roots, nested prefab instances, variants, overrides, removed + components, added components, and object references through `PrefabUtility` +- **Serialized object dump** + - walk selected component/material/ScriptableObject serialized properties + through `SerializedObject` + - emit stable property paths, values, object reference GUIDs/paths, and + unsupported/unreadable fields +- **Reference search** + - find assets, scenes, prefabs, materials, and components that reference a + GUID, material, shader, component type, or script +- **Dry-run mutation preview** + - compute intended scene/prefab/material changes and write a proposed patch + artifact without saving assets + - require explicit operator/coordinator approval before applying + +Mutation rule: editor package commands may eventually apply scene, prefab, or +asset changes, but only through named operations with scoped inputs, dry-run +preview when feasible, backup/dirty-state reporting, changed asset lists, and a +final artifact receipt. No broad YAML surgery. No "I think this GUID means a +thing" refactors. The Editor knows what the object is; use it. + ### Phase U2: Bridge Command Contract -Extend `tools/epiphany_unity_bridge.py run` with named operations instead of -freeform `-executeMethod` being the normal path. +Extend `tools/epiphany_unity_bridge.py run` with named operations that call the +resident editor package instead of making freeform `-executeMethod` the normal +path. Recommended CLI: @@ -530,6 +597,16 @@ python tools/epiphany_unity_bridge.py probe ` --operation scene-facts ` --scene Assets/Scenes/Main.unity +python tools/epiphany_unity_bridge.py probe ` + --project-path E:\Projects\Aetheria-Economy ` + --operation prefab-facts ` + --asset Assets/Prefabs/Nebula.prefab + +python tools/epiphany_unity_bridge.py probe ` + --project-path E:\Projects\Aetheria-Economy ` + --operation serialized-object ` + --asset Assets/Materials/Nebula.mat + python tools/epiphany_unity_bridge.py test ` --project-path E:\Projects\Aetheria-Economy ` --platform editmode ` @@ -575,6 +652,11 @@ optional: screenshot.png shader-report.json scene-facts.json + prefab-facts.json + serialized-object-facts.json + reference-search.json + mutation-preview.json + mutation-apply.json compilation.json ``` @@ -625,6 +707,15 @@ Initial Aetheria-specific probes: - **Scene/prefab reference probe** - Which scenes contain gravity/fog renderers? - Which prefabs reference the old camera path? +- **Scene configuration probe** + - Which scene objects and components own gravity/fog configuration? + - Which serialized component fields point at the old rendering path? + - Which object references would need to change for the hierarchical texture + set? +- **Prefab override probe** + - Which prefab assets and prefab instances carry overrides relevant to + gravity/fog rendering? + - Which overrides are inherited versus local scene edits? - **Play-mode smoke probe** - Can a minimal scene enter play mode long enough to validate the gravity texture producer contract? @@ -901,35 +992,56 @@ Rider changed ranges or git diff touches frontier files environment organ. - No code change beyond docs. -### Slice 2: Unity Bridge Operations +### Slice 2: Resident Unity Editor Package + +- Add Aetheria-side `Assets/Editor/Epiphany` bridge first. +- Implement: + - `InspectProject` + - `CheckCompilation` + - `CaptureSceneFacts` + - `CapturePrefabFacts` + - `CaptureSerializedObjectFacts` + - `RunProbe` + - artifact writer +- Use Unity APIs for Unity state: + - `AssetDatabase` for asset lookup and GUID/path mapping + - `EditorSceneManager` for scene loading/inspection + - `SerializedObject` / `SerializedProperty` for component, material, and + ScriptableObject fields + - `PrefabUtility` for prefab assets, instances, and overrides +- Keep it source-controlled in Aetheria, not Epiphany, unless it becomes a + reusable UPM package later. + +### Slice 3: Unity Bridge Operations - Extend `epiphany_unity_bridge.py` from generic `run` to named operations: - `inspect` - `check-compilation` - `run-tests` - `run-probe` +- Add built-in operations for scene facts, prefab facts, serialized object + facts, and reference search. - Add output-dir argument contract for Unity `-executeMethod` targets. - Add smoke with fake pinned editor and command JSON. -### Slice 3: Unity Editor Package +### Slice 4: Unity Mutation Preview -- Add Aetheria-side `Assets/Editor/Epiphany` bridge first. -- Implement: - - `InspectProject` - - `CheckCompilation` - - `RunProbe` - - artifact writer -- Keep it source-controlled in Aetheria, not Epiphany, unless it becomes a - reusable UPM package later. +- Add dry-run editor commands for narrow scene/prefab/material changes. +- Write before/after artifacts and changed-asset manifests. +- Require explicit review before apply commands are available to agents. +- Keep broad direct YAML edits blocked for Unity-owned serialized state. -### Slice 4: GUI Environment Panel +### Slice 5: GUI Environment Panel - Add Environment band to `apps/epiphany-gui`. - Surface latest Unity bridge status and artifact. - Add buttons for named bridge operations. +- Add buttons for scene facts, prefab facts, serialized object facts, and + reference search. +- Display mutation previews separately from applied changes. - Keep artifacts visible and sealed logs separate from summaries. -### Slice 4b: GUI Graph Dashboard +### Slice 5b: GUI Graph Dashboard - Pull in or vendor the adjacent `@epiphanygraph/epiphany-graph-viewer` component. @@ -939,13 +1051,13 @@ Rider changed ranges or git diff touches frontier files - Add graph health and validation status near coordinator/modeling lane state. - Keep raw graph payloads accessible as artifacts or JSON for exact reasoning. -### Slice 5: Rider Bridge CLI +### Slice 6: Rider Bridge CLI - Add `tools/epiphany_rider_bridge.py` as a local protocol stub. - It should accept context packets from the future plugin and write artifacts. - It should not require Rider plugin code yet. -### Slice 6: Rider Plugin MVP +### Slice 7: Rider Plugin MVP - Create `integrations/rider`. - Frontend-only Kotlin plugin: @@ -956,7 +1068,7 @@ Rider changed ranges or git diff touches frontier files - run Inspect Unity through Epiphany bridge - No ReSharper backend yet. -### Slice 7: Coordinator Environment Awareness +### Slice 8: Coordinator Environment Awareness - Add read-only environment projection after tools settle: - IDE status diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 4d349560..6b9a0251 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -373,9 +373,13 @@ diagnostics, and code refs; Epiphany GUI is the agent dashboard for objectives, specialist lane state, logs/artifacts, persisted state, and graph/control-flow views; Unity is the pinned runtime environment for tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence. Build that plan in -slices before the next run: named Unity bridge operations, Aetheria-side Unity -editor package probes, GUI Environment panel, EpiphanyGraph-backed GUI graph -dashboard, Rider context bridge, and Rider plugin MVP. The adjacent +slices before the next run: Aetheria-side resident Unity editor package, named +Unity bridge operations over that package, GUI Environment panel, +EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, and Rider plugin +MVP. The Unity package is not optional decoration: scene files, prefabs, +materials, shaders, ScriptableObjects, asset GUIDs, and prefab overrides must be +inspected from inside the Unity Editor through Unity APIs, not inferred from +serialized text unless there is no editor-level path. The adjacent `E:\Projects\EpiphanyGraph\web\epiphany-graph-viewer` component consumes `graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly and is the preferred seed for GUI graph/control-flow diagramming. The next Aetheria diff --git a/state/evidence.jsonl b/state/evidence.jsonl index f4cf2d85..161c30df 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -53,3 +53,4 @@ {"ts": "2026-04-30T12:10:09+00:00", "type": "design", "status": "ok", "note": "Documented the Rider+Unity environment integration plan in notes/epiphany-rider-unity-integration-plan.md. The plan defines Rider as IDE/source-context organ, Unity as editor/runtime fact organ, and Epiphany as durable coordinator/Self, with seams for a Rider tool window/context bridge, pinned Unity bridge operations, Aetheria-side Unity editor probes, GUI Environment panel, typed environment state, specialist behavior, and verification gates."} {"ts": "2026-04-30T13:05:00+01:00", "type": "design", "status": "ok", "note": "Next-action priority amended: do not run another Aetheria implementation dogfood pass until the Rider and Unity bridges are in place. The next implementation slice is bridge construction first: named Unity operations, Aetheria-side Unity editor probes, GUI Environment panel, Rider context bridge, and Rider plugin MVP, so Epiphany can test hypotheses through IDE/source and editor/runtime evidence instead of repeating bridge-less supervision scars."} {"ts": "2026-04-30T13:28:00+01:00", "type": "design", "status": "ok", "note": "Documented the three-pronged development workflow: Rider is the human code view for repo state/source tree/diffs/diagnostics, Epiphany GUI is the agent dashboard for objectives, specialist lanes, logs/artifacts, persisted state, and graph/control-flow visualization, and Unity is the pinned runtime environment for tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence. The adjacent EpiphanyGraph React viewer is now called out as the preferred seed for GUI graph diagramming because it consumes typed `graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly."} +{"ts": "2026-04-30T13:48:00+01:00", "type": "design", "status": "ok", "note": "Unity integration priority corrected: the CLI bridge is only the pinned transport; the first real Unity organ must be an Aetheria-side resident Editor package that inspects scenes, prefabs, serialized component fields, prefab overrides, materials, shaders, ScriptableObjects, asset GUIDs, and scene configuration through Unity APIs, then writes typed artifacts. Direct text parsing of `.unity` and `.prefab` files is not enough for meaningful hypothesis testing or safe refactoring; future mutation support must be narrow, previewed when feasible, explicitly reviewed, and artifact-backed."} diff --git a/state/map.yaml b/state/map.yaml index 5adc03d4..b9e1f789 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -65,7 +65,7 @@ active_subgoals: - Keep the supervisor out of Epiphany worker thought streams: dogfood artifacts should be operator-safe by default, with direct transcripts and raw result payloads sealed. - Use `tools/epiphany_agent_telemetry.py` and generated `agent-function-telemetry.json` files to inspect behavior shape without opening sealed transcripts. - Treat repeated no-diff implementation turns as an MVP blocker, not success. A bounded implementation pass must leave a reviewable workspace diff or an explicit reviewable failure artifact before dogfood can be called healthy. - - Build the Rider and Unity bridges before the next Aetheria implementation dogfood run: named Unity bridge operations, Aetheria-side Unity editor probes, GUI Environment panel, Rider context bridge, and Rider plugin MVP. + - Build the Rider and Unity bridges before the next Aetheria implementation dogfood run: Aetheria-side resident Unity editor package, named Unity bridge operations over that package, GUI Environment panel, Rider context bridge, and Rider plugin MVP. - Treat the target workflow as three integrated surfaces: Rider is the human code/diff view, Epiphany GUI is the agent dashboard and persisted-state graph view, and Unity is the pinned runtime/test/scene environment. - Use `notes/epiphany-rider-unity-integration-plan.md` as the source-grounded plan for Rider-as-IDE and Unity-as-editor/runtime integration seams. @@ -128,6 +128,7 @@ accepted_design: - Editor/runtime verification is now part of the MVP product boundary for engine repos: `tools/epiphany_unity_bridge.py` is the first controlled bridge, resolving the project-pinned Unity editor, refusing wrong or missing versions, running explicit batch/probe commands only through the exact editor, and writing inspection/command/log artifacts for evidence. - Rider and Unity are environment organs, not sources of truth: Rider should expose IDE/source context, diagnostics, navigation, and changed ranges; Unity should expose pinned-editor runtime facts, compilation, tests, probes, assets, scenes, and logs; Epiphany remains the durable Self that coordinates, records, and reviews. - The product architecture is three-pronged: Rider is the code view for human inspection of repo state, source tree, diffs, diagnostics, and code refs; Epiphany GUI is the agent dashboard for objectives, specialist lane state, logs/artifacts, persisted typed state, and graph/control-flow views; Unity is the runtime environment for pinned tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence. + - Unity integration must be editor-resident, not text-archeology-only: scene files, prefabs, materials, shaders, ScriptableObjects, asset GUIDs, prefab overrides, and serialized component fields should be inspected through a Unity Editor package using Unity APIs, with narrow mutation preview/apply commands and artifact receipts. - The adjacent EpiphanyGraph React viewer is the preferred seed for GUI graph/control-flow diagramming because it consumes `graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly and exposes node/edge/code-ref inspection with machine-readable graph data behind the visual layout. - If the agent's persistent instructions, memory, workflow, or state shape are making it less coherent, slower to rehydrate, less honest, or more likely to build Jenga, the agent should ask the user to change it. - Epiphany should make compaction less like death and more like sleep: bank the fire before the dark, so the next waking thing finds coals instead of ash and can meaningfully resume the pattern instead of merely continuing the task. @@ -191,5 +192,5 @@ rejected_paths: reason: persistent state that accumulates every local truth becomes memory cruft and weakens rehydration current_status: - summary: Phase 1 durable state through Phase 6 GUI/coordinator/specialist/CRRC MVP surfaces are landed. The Aetheria supervised run found and fixed real harness wounds in coordinator policy, no-diff audits, stale job/result projection, and reorient acceptance. The Unity incident proved the next blocker is environment access, so `notes/epiphany-rider-unity-integration-plan.md` now governs a three-pronged bridge-building pass: Rider code view, Epiphany GUI agent dashboard, and Unity runtime environment. - next_action: Implement the three-pronged Rider/Epiphany GUI/Unity workflow before further Aetheria implementation dogfood: named Unity bridge operations, Aetheria-side Unity editor package probes, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. The next dogfood run should happen only after Epiphany can gather Rider/source context and Unity/editor runtime evidence through auditable bridges. Do not let implementation workers invoke Unity directly; use bridge artifacts as evidence of either a pinned-editor run or a missing-runtime blocker. Do not inspect raw worker transcripts or `rawResult` payloads unless the user explicitly requests forensic debugging. + summary: Phase 1 durable state through Phase 6 GUI/coordinator/specialist/CRRC MVP surfaces are landed. The Aetheria supervised run found and fixed real harness wounds in coordinator policy, no-diff audits, stale job/result projection, and reorient acceptance. The Unity incident proved the next blocker is environment access, so `notes/epiphany-rider-unity-integration-plan.md` now governs a three-pronged bridge-building pass: Rider code view, Epiphany GUI agent dashboard, and Unity runtime environment, with Unity integration treated as a resident editor package rather than text-only file inspection. + next_action: Implement the three-pronged Rider/Epiphany GUI/Unity workflow before further Aetheria implementation dogfood: Aetheria-side resident Unity editor package, named Unity bridge operations over that package, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. The next dogfood run should happen only after Epiphany can gather Rider/source context and Unity/editor runtime evidence through auditable bridges. Do not let implementation workers invoke Unity directly or refactor Unity-owned serialized scene/prefab state as raw text when an editor API path exists; use bridge artifacts as evidence of either a pinned-editor run, runtime/editor facts, or a missing-runtime blocker. Do not inspect raw worker transcripts or `rawResult` payloads unless the user explicitly requests forensic debugging.