UnityLaparoscopicSceneSimulator/.opencode/skills/realtime-performance-budget/SKILL.md

---
name: realtime-performance-budget
description: Performance, profiling, and scene-cleanliness checks for the LaparoscopicSurgeryEmulation scene. Use after any visual or hierarchy change to verify draw calls, texture sizes, shader cost, light count, console warnings, and missing references stay inside the real-time Unity budget for this project.
---

# Real-time Performance Budget (project-scoped)

The scene must remain real-time. The laparoscope view is small and focused, so the budget is generous, but not unlimited. This skill sets the budgets and the verification routine.

## When to load

Load when:
- An agent has just applied a bounded visual, hierarchy, material, lighting, or post-processing change.
- The Performance/QA subagent is running its verification pass.
- A "scene feels heavy", "frame rate dropped", "long bake", or "console is full of warnings" report comes in.
- A package, asset, or model is being added to the project.

## Per-frame budget (Unity Editor, this scene)

These are starting targets. Tighten if the user reports frame drops; loosen only with explicit approval.

| Resource | Budget | Notes |
|---|---|---|
| Triangle count (visible from scope) | ≤ 250k | The cavity is small; most triangles should be culled |
| Draw calls (visible from scope) | ≤ 200 | Lower is better; static batching helps |
| SetPass calls | ≤ 100 | URP-specific; raised by unique shaders / materials |
| Real-time lights (visible) | ≤ 4 | One key, one fill, two rims, max; everything else baked |
| Reflection probes (visible) | ≤ 1 | One cavity probe at 256² is fine |
| Texture memory (visible) | ≤ 64 MB | Mostly mucosa + organ textures |
| Post-processing overrides | ≤ 8 | A profile with Bloom + Vignette + DoF + Tonemapping + ColorAdjustments + LensDistortion + ChromaticAberration + FilmGrain is already at the budget |
| Render scale | ≤ 1.25 | Bumping to 1.5+ to "fix" softness is a landmine |
| MSAA | 2× | 4× is fine on desktop, expensive on mobile |
| Volume profile count (active) | ≤ 1 global | Multiple globals cause blending surprises |

## Texture budget

| Texture role | Max size | Format | Notes |
|---|---|---|---|
| Mucosa base (`TissueMucosa.png`) | 2048 | BC7 (desktop) or ASTC (mobile) | 1024 is acceptable for non-hero work |
| Mucosa normal | 2048 | BC5 (desktop) or ASTC normal (mobile) | 1024 acceptable |
| Organ diffuse (`StylizedDigestiveSystem_Diffuse.png`) | 2048 | BC7 / ASTC | 1024 acceptable |
| Organ normal (`StylizedDigestiveSystem_Normal.png`) | 2048 | BC5 / ASTC normal | 1024 acceptable |
| Organ roughness (`StylizedDigestiveSystem_Roughness.png`) | 1024 | BC4 / ASTC | Single channel; do not store as RGBA |
| Decals (if added) | 512 | BC7 / ASTC | Smaller than tissue |

Verify texture import settings on any new or modified texture: `manage_asset(action="get_info", path="Assets/Textures/.../<file>.png")` then read `importSettings`. Look for:
- Correct sRGB on / off (sRGB on for colour, off for normal/roughness/AO).
- Correct texture type (Default vs Normal map vs Single Channel).
- Compression = the highest-quality option the platform supports without exceeding the memory budget.
- Max Size within the budget table.
- Generate Mip Maps: on (unless explicitly disabled for UI or distance-field textures).

## Shader cost

- Default to URP/Lit. URP/Simple Lit is acceptable as a fallback for non-hero materials.
- URP/Unlit only for HUD overlays or debug helpers; never for tissue or instruments.
- Custom shaders (the project's `RenderDepth.shader` and `BlendShader.compute`) are constrained to the depth / WebRTC pipelines. Do not extend them for visual work; a new bounded change is needed for any visual use.
- The "shader compiles per-variant" warning is a URP trap: every keyword you enable on a material adds a variant. Keep keywords minimal.

## Light count

- 1 directional (key) or 1 spot (scope-mounted).
- 0–2 fill (low-intensity, small radius).
- 0–2 rim (very low intensity, used to lift cavity walls).
- Baked lightmaps for any large static fill.
- Light probes (mixed mode) for the instrument proxy if it moves.
- Total real-time lights in the cavity: ≤ 4. If the scene needs more, propose baked lighting instead.

## Console hygiene

After any change, `read_console(types=["error","warning"])` and report:
- Missing-reference warnings.
- Shader-compile errors.
- "Material property is found in another shader" warnings (means a property was set on the wrong material).
- "The referenced script on this Behaviour is missing" warnings.
- Lightmap / light probe warnings.
- Any error, even if the change appears to work — a silent error is a future bug.

Use `read_console(action="clear")` only at the start of a clean run, never mid-investigation.

## Profiler

- `manage_profiler(action="profiler_start")` to begin a capture.
- `manage_profiler(action="profiler_get_counters", category="Render")` for per-frame draw calls and triangles.
- `manage_profiler(action="profiler_get_counters", category="Memory")` for texture / mesh / material memory.
- `manage_profiler(action="profiler_stop")` when done.
- `manage_profiler(action="get_frame_timing")` for GPU/CPU frame time without a capture.

A capture is **not** required for every change. Use it when:
- A material change made the frame slower.
- A new light or reflection probe was added.
- The user reports a frame rate regression.

## Scene cleanliness checks

Run these on the QA pass:

1. **Missing references** — `read_console` plus a manual scan of the hierarchy.
2. **Empty containers** — empty `GameObject` parents that no longer have children. Either delete or fill them.
3. **Off-limits paths** — no top-level GameObjects outside `SurgeryBenchmark/...` and the preserved `MainScene` subtrees. If a stray was created, remove it.
4. **Duplicate materials** — two `.mat` files with the same name suffix. If found, consolidate.
5. **Unused assets** — `.mat`, `.png`, `.fbx` not referenced by any scene or prefab. Surface in the handoff; do not auto-delete.
6. **Stale meta files** — not relevant to the agent; ignore.
7. **On-Disk vs Library cache** — not relevant; ignore.

## Reversibility / cleanup

If the QA pass finds a regression caused by a recent bounded change:
1. Identify the change via the most recent handoff's `CHANGED` block.
2. Reverse it (delete the GameObject, reset the material property, remove the Volume override).
3. Re-verify with `read_console` and a screenshot.
4. Report the rollback in the handoff's `CHANGED` block, prefixed with `REVERTED:`.

## Common MCP calls (cheat sheet)

| Intent | MCP call |
|---|---|
| Console scan | `read_console(action="get", types=["error","warning"], count=20, include_stacktrace=true)` |
| Console clear | `read_console(action="clear")` (only at start of a clean run) |
| Texture info | `manage_asset(action="get_info", path="Assets/Textures/LaparoscopicBenchmark/TissueMucosa.png")` |
| Render counters | `manage_profiler(action="profiler_get_counters", category="Render")` |
| Frame timing | `manage_profiler(action="get_frame_timing")` |
| Memory counters | `manage_profiler(action="profiler_get_counters", category="Memory")` |
| Begin capture | `manage_profiler(action="profiler_start", log_file="Assets/Logs/qa_capture.raw")` |
| End capture | `manage_profiler(action="profiler_stop")` |
| Run EditMode tests | `run_tests(mode="EditMode")` |
| Run PlayMode tests | `run_tests(mode="PlayMode", init_timeout=120000)` |
| Validate a script | `validate_script(uri="Assets/Scripts/<...>.cs", level="standard", include_diagnostics=true)` |

## Anti-patterns to refuse

- Bumping `RenderScale` to 1.5+ to mask softness or aliasing.
- Adding more than 4 real-time lights to the cavity.
- Using a 4K+ texture for any role.
- Importing a model with 1M+ triangles when 50k is enough for the cavity.
- Disabling frustum culling or occlusion culling to "fix" a missing mesh.
- Adding a new URP renderer feature without a bounded change statement.
- Re-baking lighting on every iteration when only a small region changed.
- Claiming a change is performance-safe without counters.