c51e6d1369
:Release Notes: - Agents files for opencode and claude - Skills for opencode and claude - 3d models with medical organs - Some textures :Detailed Notes: - :Testing Performed: - :QA Notes: - Looks like shit :) :Issues Addressed: TG-1
104 lines
7.3 KiB
Markdown
104 lines
7.3 KiB
Markdown
---
|
|
name: unity-hierarchy-hygiene
|
|
description: Maintain a clean, readable, reusable Unity scene hierarchy in the LaparoscopicSurgeryEmulation scene. Use when adding, moving, renaming, parenting, prefab-ifying, or activating GameObjects under the SurgeryBenchmark/ authored roots.
|
|
---
|
|
|
|
# Unity Hierarchy Hygiene (project-scoped)
|
|
|
|
This skill encodes the scene's authoring contract so additions stay reversible, organized, and do not collide with the preserved `MainScene` objects.
|
|
|
|
## When to load
|
|
|
|
Load when the agent is about to:
|
|
- Create, rename, move, parent, or delete any GameObject in the active scene.
|
|
- Convert a GameObject to a prefab, or instantiate a prefab into a slot.
|
|
- Activate or deactivate a scenario root.
|
|
- Touch the `SurgeryBenchmark/*` authored roots or the `SurgeryBenchmark/Shared/*Slot` replacement anchors.
|
|
|
|
## The authoring contract (from `Assets/Scenes/LaparoscopicSurgeryEmulation.md`)
|
|
|
|
These paths are the **stable contract** for external control. Do not rename or move them.
|
|
|
|
| Path | Role | Default state |
|
|
|---|---|---|
|
|
| `SurgeryBenchmark/Shared` | Reusable assets (cavity, anatomy placeholder, instrument placeholder) | active |
|
|
| `SurgeryBenchmark/Shared/AnatomySlot` | Replacement anchor for the organ mesh | empty / placeholder |
|
|
| `SurgeryBenchmark/Shared/CavitySlot` | Replacement anchor for the cavity wall | empty / placeholder |
|
|
| `SurgeryBenchmark/Shared/InstrumentSlot` | Replacement anchor for the instrument proxy | empty / placeholder |
|
|
| `SurgeryBenchmark/Scenarios/Scenario_01_CleanTissue` | Active benchmark scenario | **active** |
|
|
| `SurgeryBenchmark/Scenarios/Scenario_02_WetSpecular` | Wet specular variant | inactive |
|
|
| `SurgeryBenchmark/Scenarios/Scenario_03_LowTexture` | Low-texture variant | inactive |
|
|
| `SurgeryBenchmark/Scenarios/Scenario_04_PartialOcclusion` | Partial occlusion variant | inactive |
|
|
| `SurgeryBenchmark/Scenarios/Scenario_05_InstrumentOcclusion` | Instrument occlusion variant | inactive |
|
|
|
|
External automation (including subagents) **toggles scenario roots only**. Never rename, never reorder, never reparent scenario roots or slot anchors.
|
|
|
|
## Off-limits subtrees (preserved from `MainScene`)
|
|
|
|
Do not rename, move, delete, or restructure objects that came from `MainScene`:
|
|
- The stereo rig (left + right laparoscope cameras and their parents).
|
|
- `Blending` (depth / colour blend controller).
|
|
- UI canvases and UI events.
|
|
- WebRTC sender / receiver objects (driven by `WEBRTCSender.cs`).
|
|
- RPC objects (driven by `CrpcApi.cs` / `MinimalRpcServer.cs`).
|
|
|
|
These are the project's external-interop surface. Renaming them breaks WebRTC peers and any automation that addresses them by name.
|
|
|
|
## Naming convention
|
|
|
|
Use PascalCase for GameObject names that act as authored containers (`AnatomySlot`, `CavitySlot`). Use descriptive PascalCase for everything else (`CavityWall_Main`, `Tissue_Default_Slot01`). Avoid spaces, avoid leading numbers, avoid names that look like IDs (e.g., `Cube_42` is acceptable as a primitive placeholder but should be renamed before promotion).
|
|
|
|
For dynamically generated objects (e.g., benchmark instances), use the pattern `<Type>_<ScenarioTag>_<Index>`:
|
|
- `CavityWall_S02_00`
|
|
- `Tissue_Default_S01_00`
|
|
- `InstrumentProxy_S05_00`
|
|
|
|
## Parenting rules
|
|
|
|
1. **Slot rule.** Anything that fills `AnatomySlot`, `CavitySlot`, or `InstrumentSlot` lives as a child of the slot, not as a sibling. This keeps the slot a stable, swappable anchor.
|
|
2. **Scenario rule.** Scenario-specific geometry goes under the scenario root. Anything shared across scenarios goes under `SurgeryBenchmark/Shared`.
|
|
3. **Scaffolding rule.** Editor scaffolding (gizmos, debug helpers, placeholders) goes under `SurgeryBenchmark/Shared/_Editor` (prefix with underscore) so it is obvious it is not authored content. Off by default in builds if you control build settings; otherwise hide via the `_Editor` convention.
|
|
4. **No flat hierarchies.** If you are about to add a top-level GameObject, stop — almost everything should be under `SurgeryBenchmark/...` or under one of the preserved `MainScene` subtrees.
|
|
|
|
## Prefab boundaries
|
|
|
|
- A GameObject becomes a prefab when **more than one scenario** needs the same instance, **or** when the agent wants the change to be reusable across scenes.
|
|
- Prefabs for this project live in `Assets/Prefabs/LaparoscopicBenchmark/` (create the folder if missing; this is bounded).
|
|
- Slot contents that are reusable across scenarios should be authored as a prefab variant rooted at the slot, not as a duplicated hierarchy.
|
|
- When converting to a prefab, use `manage_prefabs(action="create_from_gameobject")` and `prefab_folder="Assets/Prefabs/LaparoscopicBenchmark"`. Reuse the existing one if it already exists.
|
|
|
|
## Activation vs destruction
|
|
|
|
Default to **activation** (`SetActive(false)` on a scenario root) over deletion. The five scenario roots are an explicit external contract — they exist so external automation can toggle them. Deleting one breaks the contract.
|
|
|
|
If a child object truly has no future use, prefer to move it under `SurgeryBenchmark/Shared/_Retired` (with a one-line note in the handoff) rather than delete it. Destructive deletions of authored content require explicit approval.
|
|
|
|
## Common operations and the right MCP call
|
|
|
|
| Intent | MCP call | Notes |
|
|
|---|---|---|
|
|
| Activate a scenario | `manage_gameobject(action="modify", target="Scenario_02_WetSpecular", search_method="by_path", set_active=true)` | Always by path, not by name, to avoid collisions |
|
|
| Deactivate siblings | Same with `set_active=false` | Do it as a batch |
|
|
| Add a child to a slot | `manage_gameobject(action="create", name="...", parent="AnatomySlot", search_method="by_path", primitive_type=...)` | Parent path is stable |
|
|
| Rename | `manage_gameobject(action="modify", target="...", new_name="...")` | Only inside the authored roots, never on the scenario roots or slots |
|
|
| Inspect children | `find_gameobjects(search_term="SurgeryBenchmark/Shared", search_method="by_path", include_inactive=true)` | Use to confirm activation state before activating |
|
|
| Convert to prefab | `manage_prefabs(action="create_from_gameobject", target="...", prefab_path="Assets/Prefabs/LaparoscopicBenchmark/<Name>.prefab")` | Then re-instantiate in each scenario via `manage_gameobject` or by editing the scenario root |
|
|
|
|
## Reversibility checklist (before any hierarchy change)
|
|
|
|
1. Is the target under `SurgeryBenchmark/...` or a preserved `MainScene` subtree? If preserved, **stop and ask**.
|
|
2. Will renaming it break any script reference, prefab variant, or external automation? If yes, **stop and ask**.
|
|
3. Can the change be expressed as "toggle active" instead of "delete"? If yes, prefer that.
|
|
4. Is the new name in PascalCase and descriptive? If not, fix it.
|
|
5. After the change, does `read_console` show missing-reference warnings? If yes, fix before reporting done.
|
|
|
|
## Anti-patterns to refuse
|
|
|
|
- Adding top-level GameObjects outside `SurgeryBenchmark/...` and the preserved subtrees.
|
|
- Renaming `SurgeryBenchmark/Scenarios/Scenario_0X_*` roots or `SurgeryBenchmark/Shared/*Slot` anchors.
|
|
- Moving the stereo rig, `Blending`, UI, WebRTC, or RPC objects.
|
|
- Deleting a scenario root instead of deactivating it.
|
|
- Flat hierarchies with 10+ top-level GameObjects that should be in a container.
|
|
- Magic-number indices (`Cube (42)`) being promoted to authored names.
|
|
- Creating prefabs in the root of `Assets/` instead of `Assets/Prefabs/LaparoscopicBenchmark/`.
|