03. Scene Doctor

← Previous: Dashboard & Editor UI | Next: Rule Reference →

Overview

Scene Doctor is the core diagnostic engine of FuzzyOptimizer. It audits all loaded scenes (active GameObjects and enabled components), the assets they reference (textures, meshes, audio clips, materials), and project-wide graphics and physics settings.

Every diagnostic test is defined as an independent, modular rule. For a full breakdown of the 49 checks, see the Rule Reference.

Issue Severities

Detected issues are categorized into three distinct severity levels:

Severity	Diagnostic Impact	Action Guidance
Critical	Major, measurable performance regression or GPU bottleneck (e.g. uncompressed 4K textures, heavy MeshColliders, infinite looping particle leaks).	Must resolve before releasing production builds.
Warning	Real, quantifiable overhead that strains CPU/GPU runtime resources (e.g. missing mipmaps, 32-bit index buffers, unshared duplicate materials).	Strongly recommended to address for target framerate stability.
Info	Context-dependent optimization opportunity or architectural best-practice recommendation.	Review based on specific project needs and artistic intent.

Health Score Algorithm

The Health Score is a dynamic quality indicator calculated on a scale from 0 to 100. The scene begins at a perfect score of 100, and points are deducted according to detected issues and platform budget overruns:

Penalty Source	Deduction Formula	Notes
Critical Issue	$-6$ points each	High-impact performance flaw
Warning Issue	$-2$ points each	Moderate performance strain
Info Issue	$-0.5$ points each	Minor advisory note (capped at max 5 points per category)
Category Cap	Max $-20$ points per category	Prevents one noisy rule category from completely destroying the score
Draw Calls Over Budget	Up to $-30$ points	Calculated as $25 \times \text{overrun ratio}$ against platform limit
Triangles Over Budget	Up to $-25$ points	Calculated as $20 \times \text{overrun ratio}$ against platform limit
Texture VRAM Over Budget	Up to $-20$ points	Calculated as $15 \times \text{overrun ratio}$ against platform limit

Health Score Ratings

Score Range	Health Status	Production Guidance
85 – 100	Excellent	Well optimized, ready for target hardware release.
65 – 84	Good	Production quality; minor optimizations recommended.
45 – 64	Fair	Noticeable performance degradation found on target hardware.
0 – 44	Critical	Severe bottlenecks; high risk of frame drops and thermal throttling.

Projected Score

The Overview tab and Scene Doctor calculate a real-time Projected Score. This indicates the score your scene will achieve immediately after applying all Safe automated fixes.

Fix Safety Levels

Every automated repair action is rated with a strict safety tier:

Safety Level	Technical Definition	Bulk Execution
Safe	Modifies import flags or rendering configuration with zero visual change and zero gameplay side-effects (e.g. GPU texture block compression, 16-bit mesh index buffers, enabling the SRP Batcher).	Applied automatically in Fix All Safe and in every One-Click Optimize preset.
Moderate	May subtly alter visuals, mesh fidelity, or runtime script assumptions (e.g. collider simplification, shadow distance trimming, disabling texture Read/Write).	Applied selectively, or as part of explicitly enabled One-Click steps.
Destructive	Permanently deletes or rewrites project source content.	Never executed automatically by FuzzyOptimizer.

Fixing Issues in Scene Doctor

Scene Doctor provides flexible, granular control over how fixes are applied:

Individual Fix: Click the dedicated action button next to an issue (e.g. Compress, Disable Shadows, Use 16-bit Indices).
Rule Group Fix: Click the group-level fix button to repair all occurrences of that rule at once.
Multi-Selection Fix: Select arbitrary issues across disparate categories using standard Ctrl+Click or Shift+Click and apply fixes in batch.
Fix All Safe: Instantly executes all Safe fixes across the entire scene in one command.

Assets requiring importer modifications are automatically batched so that Unity reimports each asset only once, saving significant asset pipeline turnaround time.

Ignoring False Positives

Sometimes a deliberate artistic choice conflicts with a standard performance rule (such as an uncompressed UI splash screen or a terrain needing special detail settings).

Ignore Object Issue: Right-click an issue in Scene Doctor and choose Ignore. The ignore key is composed of the rule’s stable ID plus the target’s Global Object ID (and an optional discriminator when one object triggers multiple sub-issues).
Persistent Storage: All ignores are serialized into ProjectSettings/FuzzyOptimizerSettings.json. Committing this file ensures that ignored false positives are shared across your entire development team and CI runners.
Disabling Rules Globally: If your team chooses not to enforce a particular check (e.g. mobile sample rate rules on desktop), disable the rule completely in the dashboard Settings tab.

History & Revert System

Every batch of changes—whether applied via an individual fix button, a rule group, the One-Click pipeline, or a specialized optimization tool—is recorded as an atomic Optimization Session.

What the Session Records

Asset Importer Changes: Creates full file backups of the asset and its corresponding .meta file.
Scene Objects & Project Settings: Logged to an independent, persistent change journal. This journal is independent of Unity’s Undo stack and survives editor restarts and domain reloads.
Generated Assets & Objects: Tracks newly created meshes, materials, and prefabs so the revert engine can cleanly delete them.
Scene File Backups: Creates an uncompressed snapshot copy of each affected scene file before the session initiates.

All session data is persisted locally in Library/FuzzyOptimizer/Sessions/ (this directory is local to your machine and excluded from version control).

Revert Capabilities

From the Scene Doctor ⋯ menu > History, you can:

Revert Last Session: Rolls back the most recent optimization session completely.
Revert to Historical Session: Rolls back through consecutive sessions in reverse order down to the chosen checkpoint.
Revert Single Rule: Reverts only the changes introduced by a specific rule within a multi-rule session.
Restore Scene Backup: Restores the raw scene file snapshot taken prior to optimization.

Manual changes you make in the scene after an optimization session are preserved when reverting the session journal.

Irreversible Operations

A small subset of operations cannot be reconstructed by the journal and are explicitly flagged:

Removing Missing-Script Components: Unity cannot reconstruct an unknown serialized component once deleted. Only Unity’s active Undo stack or restoring the full scene backup can recover them.
Re-baking Occlusion Culling: If the scene previously contained baked occlusion data, reverting clears the new bake; previous occlusion cache files cannot be restored.