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

name, description

name	description
realtime-performance-budget	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.