Sentinel

Getting Started

Requirements

• Unity 2021.3 LTS or newer (including Unity 6)
• No external dependencies — works out of the box
• Editor-only — nothing is included in your player builds

Installation

After importing from the Asset Store, Sentinel lives at Assets/Sentinel/. Unity will compile the YourStudio.Sentinel.Editor assembly automatically. No setup required.

Opening Sentinel

Go to Window > Sentinel > Open Window or press Ctrl+Shift+Alt+S.

The main window has a toolbar and four tabs: Health, Issues, Unused Assets, and Dependencies.

Your First Scan

1. Open the Sentinel window
2. Click "Scan Full Project" in the toolbar
3. Wait for the progress bar to finish
4. Review the results in the Issues tab

Issues Finder

The Issues tab scans your entire project — including closed scenes (via YAML parsing, without opening them) — and reports problems organized by severity.

Built-in Detectors

Detector	Default Severity	What It Finds
Missing Script	Error	GameObjects with deleted/renamed MonoBehaviour scripts
Missing Reference	Error	Serialized fields pointing to destroyed/missing assets
Missing Material	Error	Renderers with null material slots
Shader Error	Error	Shaders that fail to compile
Empty UnityEvent	Warning	UnityEvent fields with zero persistent listeners
Invalid Layer	Warning	GameObjects assigned to undefined layer indices
Invalid Tag	Warning	GameObjects with tags that don't exist in the Tag Manager
Unused Component	Warning	Lone MonoBehaviours on childless leaf GameObjects
Empty GameObject	Info	GameObjects with only a Transform and no children
Duplicate Name	Info	Multiple assets sharing the same filename

Columns

Column	Description
Type	The issue detector name (e.g., MissingScript, MissingRef)
Asset Path	Full project path to the asset (e.g., Assets/Scenes/Level1.unity)
Object Type	The Unity asset type (e.g., SceneAsset, GameObject, MonoScript)
Message	Human-readable description of the issue

Click any column header to sort by that column. Click again to reverse the sort order.

Filtering

The left panel provides filters:

• Severity Filter — toggle visibility of Errors, Warnings, Infos, and Suppressed issues
• Issue Type Filter — enable/disable specific detector types
• Sort By — dropdown to sort by Severity, Asset, or Type

Fixing Issues

Issues that have automatic fixes show a "Fix:" option when right-clicked:

• Missing Script → "Fix: Remove Missing Script" — removes the null component
• Missing Reference → "Fix: Clear Reference" — sets the broken field to null

All fixes support Undo (Ctrl+Z). After any fix is applied, Sentinel automatically rescans the project and shows a popup confirming how many issues were resolved.

The "Fix All Auto-Fixable" button in the left panel applies the first available fix for every fixable issue at once.

Suppression

Right-click any issue and select "Suppress Issue" to hide it from future scans. Suppressions are saved to Assets/SentinelData/suppressions.json (version-controlled, shared with your team).

To remove a suppression, enable the "Suppressed" filter, find the issue, right-click, and select "Remove Suppression."

Context Menu

Right-click any issue row for:

• Fix: ... — available fix actions
• Suppress Issue / Remove Suppression
• Open Asset — opens the asset in its default editor
• Copy Path — copies the asset path to clipboard

Clicking any row pings the asset in the Project window.

Project Cleaner

The Unused Assets tab finds unreferenced assets — files that are not reachable from any build scene, Resources folder, or other root — and are safe to delete.

How It Works

Sentinel uses a root-tracing algorithm:

1. Identifies all root assets that must be kept (build scenes, Resources, StreamingAssets, scripts, Editor folders, Plugins, asset bundles, Addressables)
2. Recursively traces every dependency from each root using AssetDatabase.GetDependencies
3. Any asset in your project NOT reached by this trace is flagged as garbage

Protected Assets (Never Flagged)

• Scenes in Build Settings and all their dependencies
• Everything in Resources/ folders and their dependencies
• Everything in StreamingAssets/, Editor/, Plugins/, Gizmos/
• All scripts (.cs, .asmdef, .asmref)
• Assets with AssetBundle names and their dependencies
• Addressable asset data and its dependencies
• Assets from the last build report
• Project Settings files

Using the Cleaner

1. Switch to the Unused Assets tab
2. Click "Find Deletable Assets"
3. Review the results grouped by folder
4. Use checkboxes to select/deselect individual assets
5. Click "Delete Selected"

Delete Confirmation

When you click "Delete Selected," a confirmation dialog appears with two options:

Full Preview Window

Click "Open Full Preview Window" for a larger, dedicated window with:

• Select All / Deselect All buttons
• Export to CSV for external review
• Empty folder detection

References Finder

The Dependencies tab answers: "Where is this asset used?"

How to Use

1. Switch to the Dependencies tab
2. Drag an asset into the Target Asset field (or use the object picker)
3. Click "Find References"
4. The tree view shows every asset that references your target

Sentinel rebuilds the dependency map fresh each time you search, so it always reflects the current project state. It also performs a supplementary YAML search across all scene and prefab files to catch references that the map might miss.

Results

• Click a result row to ping the referencing asset in the Project window
• Expand a result to see precise locations (component, property path) — loaded on-demand for performance
• Scene results are marked with [Scene], prefabs with [Prefab]

Trends & Health Score

The Health tab tracks your project's health over time.

Health Score

A score from 0 to 100 calculated after each scan:

Score = 100 - (Errors × 5) - (Warnings × 1) - (Infos × 0.2)    clamped to [0, 100]

Delta Indicator

Shows whether issues increased or decreased since the previous scan.

Trends Chart

After 2+ scans, a line chart shows errors (red), warnings (yellow), and total issues (white) over time. Sentinel stores up to 60 scan snapshots.

Baseline

Lock a baseline to establish "known issues." Future scans will report how many new issues appeared since the baseline was locked. This is especially useful for CI pipelines: allow existing tech debt but block new regressions.

• Click "Lock New Baseline" in the Health tab
• The baseline is saved to Assets/SentinelData/baseline.json (version-controlled)
• The Issues tab status bar shows "X new since baseline"

Settings

Go to Edit > Project Settings > Sentinel to configure.

Scan Scope

• Included Folders — which folders to scan (default: Assets)
• Excluded Folders — folders to skip (e.g., Assets/Sandbox)

Severity Configuration

Override the default severity for each issue type. For example, change "Empty UnityEvent" from Warning to Info if your project uses event-driven patterns where empty events are intentional.

Scan Options

Option	Default	Description
Scan Open Scenes	On	Include currently open scenes in the scan
Scan Closed Scenes	On	Scan .unity files via YAML (without opening them)
Auto Scan on Compile	Off	Trigger a scan after every script compilation
Fail Build on Errors	Off	Block player builds if Error-severity issues exist

Notifications

Paste a Slack or Discord webhook URL to receive scan result notifications. Click "Test Webhook" to verify.

Build Pre-Check

When "Fail Build on Errors" is enabled, Sentinel runs a fast pre-build scan (Missing Scripts + Missing References only) before every player build. If errors are found, the build is blocked with a summary of issues.

Suppression via Code

Add the [SentinelIgnore] attribute to fields, properties, or entire classes to suppress issue detection:

[SentinelIgnore("Intentionally null during async loading")]
public GameObject optionalReference;

Project Window Context Menu

Right-click assets or folders in the Project window:

• Sentinel > Exclude Folder from Scans — adds the folder to the excluded list
• Sentinel > Suppress All Issues in This Asset — suppresses all detections for that asset

CI/CD Integration

Command-Line Usage

Run Sentinel in headless mode for CI pipelines:

Unity.exe -batchmode -quit -projectPath /path/to/project \
  -executeMethod YourStudio.Sentinel.Editor.SentinelCLI.RunScan \
  -sentinelOutput Reports/sentinel-report.json \
  -sentinelFailOn Error

CLI Arguments

Argument	Default	Description
-sentinelOutput	sentinel-report.json	Output path for the JSON report
-sentinelFailOn	Error	Minimum severity to fail (Error, Warning, Info)

Exit Codes

Code	Meaning
0	Scan passed — no issues at or above the fail threshold
1	Scan failed — issues found at or above the fail threshold
2	Scan error — crash, missing profile, or configuration problem

Output Reports

Two reports are generated side by side:

GitHub Actions Template

A ready-to-use workflow is included at Assets/Sentinel/CI/sentinel-ci.yml. Copy it to .github/workflows/sentinel-ci.yml in your repository. It uses Game CI (game-ci/unity-builder@v4).

Lock Baseline from CLI

Unity.exe -batchmode -quit -projectPath /path/to/project \
  -executeMethod YourStudio.Sentinel.Editor.SentinelCLI.LockBaseline

Git Post-Merge Hook

Sentinel can install a git hook that automatically runs a health scan after every git pull / git merge. Call SentinelGitHook.InstallPostMergeHook() from code or a menu item.

Custom Extensions

Sentinel's detector system is fully extensible. Create your own detectors to enforce project-specific rules — naming conventions, component limits, folder structure, and more. Custom extensions are auto-discovered via TypeCache — no registration, no config files.

Creating a Custom Detector

1. Create a new C# script in an Editor folder
2. Add an assembly definition (.asmdef) that references YourStudio.Sentinel.Editor and targets the Editor platform only
3. Create a class that extends SentinelExtensionBase
4. Override DetectorName and whichever lifecycle hooks you need
5. Call AddIssue() to report problems

SentinelExtensionBase API

Member	Description
DetectorName required	Unique string identifying your detector (e.g., "NamingConvention")
OnScanStart(ctx)	Called once when a scan begins. Use it to load settings or initialize state.
OnAssetScanned(assetPath, so)	Called for every asset in the project. so is the SerializedObject (may be null for non-serializable assets).
OnPrefabScanned(prefabPath, root)	Called for each prefab with its root GameObject.
OnSceneScanned(scenePath, rootObjects)	Called for each open scene with its root GameObject[] array.
OnSceneTextScanned(scenePath, sceneText)	Called for each closed scene with its raw scene-file text (YAML) as a string.
OnScanEnd(ctx)	Called once after all assets have been scanned. Use for project-wide checks.
AddIssue(record)	Reports an issue. Sentinel assigns a unique ID automatically.

Minimal Example

using System.IO;
using UnityEditor;

namespace YourStudio.Sentinel.Editor
{
    public class NamingConventionDetector : SentinelExtensionBase
    {
        public override string DetectorName => "NamingConvention";

        private SentinelSeverityConfig _severityConfig;

        public override void OnScanStart(SentinelScanContext ctx)
        {
            _severityConfig = SentinelProjectSettings.GetOrCreate().SeverityConfig;
        }

        public override void OnAssetScanned(string assetPath, SerializedObject so)
        {
            string fileName = Path.GetFileNameWithoutExtension(assetPath);

            // Prefabs should use PascalCase and have no spaces
            if (assetPath.EndsWith(".prefab") && fileName.Contains(" "))
            {
                AddIssue(new SentinelIssueRecord
                {
                    Severity = _severityConfig.GetSeverity("NamingConvention"),
                    IssueType = "NamingConvention",
                    AssetPath = assetPath,
                    Message = $"Prefab '{fileName}' contains spaces"
                });
            }
        }
    }
}

Assembly Definition Setup

Your custom extension needs its own .asmdef file to reference the Sentinel assembly:

{
    "name": "MyProject.SentinelExtensions",
    "rootNamespace": "",
    "references": [ "YourStudio.Sentinel.Editor" ],
    "includePlatforms": [ "Editor" ],
    "excludePlatforms": [],
    "allowUnsafeCode": false,
    "overrideReferences": false,
    "precompiledReferences": [],
    "autoReferenced": true,
    "defineConstraints": [],
    "versionDefines": [],
    "noEngineReferences": false
}

SentinelIssueRecord Fields

Field	Type	Description
Severity	SentinelIssueSeverity	Error, Warning, or Info. Use SeverityConfig.GetSeverity() to let users override.
IssueType	string	Must match your DetectorName.
AssetPath	string	Full asset path (e.g., Assets/Prefabs/Player.prefab).
ObjectPath	string	(Optional) Path within the asset (e.g., GameObject name).
Message	string	Human-readable description shown in the Issues tab.

Included Examples (SentinelExtensionDemo)

Sentinel ships with three example detectors in Assets/Sentinel/SentinelExtensionDemo/. These serve as both documentation and real, functional detectors you can modify or use as templates:

SentinelIgnore Attribute

The [SentinelIgnore] attribute can be applied to fields, properties, or entire classes to suppress issue detection for specific references:

using UnityEngine;
#if UNITY_EDITOR
using YourStudio.Sentinel.Editor;
#endif

public class MyComponent : MonoBehaviour
{
    [Tooltip("This reference is intentionally null at edit time")]
#if UNITY_EDITOR
    [SentinelIgnore("Assigned at runtime via Addressables")]
#endif
    public GameObject DynamicPrefab;
}

A complete working example is included at Assets/Sentinel/SentinelExtensionDemo/SentinelIgnoreDemo.cs.

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+Alt+S	Open Sentinel window

Menu Reference

Menu Path	Action
Window > Sentinel > Open Window	Opens the main Sentinel window
Window > Sentinel > Install Git Post-Merge Hook	Installs a git hook that runs a scan after every pull / merge
Tools > Sentinel > CI > Run Scan (Headless)	Runs a scan and writes reports (same as the CLI entry point)
Tools > Sentinel > CI > Lock Baseline (Headless)	Locks the current issue state as baseline
Edit > Project Settings > Sentinel	Opens Sentinel settings
Assets > Sentinel > Exclude Folder from Scans	Right-click context menu on folders
Assets > Sentinel > Suppress All Issues in This Asset	Right-click context menu on assets

Files Written by Sentinel

File	Location	Version Controlled?	Purpose
SentinelDependencyCache.json	Library/	No	Dependency graph cache (JSON)
SentinelSettings.json	ProjectSettings/	Yes	Shared scan configuration
suppressions.json	Assets/SentinelData/	Yes	Shared issue suppressions
baseline.json	Assets/SentinelData/	Yes	Shared issue baseline
SentinelTrends.asset	UserSettings/	No	Per-developer scan history
SentinelUserSettings.asset	UserSettings/	No	Per-developer UI preferences
SentinelBackups/*.zip	Library/	No	Pre-deletion backup archives
SentinelTrash/	Assets/	Optional	Reversible trash folder

FAQ

Support