Skip to main content

Build and CI checks

Find missing references and unset required fields before shipping the project.

Quick start​

Open Tools → Aspid 🐍 → FastTools → Settings and set Build / CI gate → Fail. Missing types now stop a player build. The default is Warn.

The check reports violations; for repair, see SerializeReference repair.

Pre-build checks​

The Build / CI gate setting picks how strict the check is:

ModePlayer buildStandalone CI run
OffSkips the checkNo scan and no report, an older report stays; exit code 0
WarnWarns and keeps buildingReport; violations in the log as warnings; exit code 0
FailMissing types stop the buildReport; violations in the log as errors; exit code 1 on violations

The build checks every asset under Assets/, not only what goes into it: in Fail mode an unused prefab stops it too — exclude such folders with Excluded scan folders.

What each run checks​

RunMissing typesEmpty fields with Required = true
Project References → Scan ProjectYes, with pending migrationsUnless the mode is Off, in a Required section
Asset ReferencesYesYes, in any mode
Player buildUnless the mode is OffNo
CI without -srGateRequiredUnless the mode is OffNo
CI with -srGateRequiredUnless the mode is OffUnless the mode is Off

Required section: an empty _primary field in two prefabsRequired section: an empty _primary field in two prefabs

A field is made required with [TypeSelector(Required = true)]; see Required field. In scenes, required fields inside managed references, collections and prefab overrides are not checked.

Detecting new breakages​

Breakage detection reports newly missing references and type names right after script, assembly or asset changes, with a notification as well as in the Console. It is on by default, under Tools → Aspid 🐍 → FastTools → Settings and Preferences → Aspid.FastTools → SerializeReference. It is a per-user setting: every team member has their own.

Scan scope​

  • saved .prefab, .asset, .unity, .controller (Animator Controller) and .playable (Timeline) files under Assets/, apart from Excluded scan folders;
  • [SerializeReference] and the names in SerializableType and SerializableMonoScript fields; [TypeSelector] strings are not checked;
  • pending MovedFrom migrations do not count as missing;
  • binary assets, unfetched Git LFS files and files that could not be opened (locked by another program, no read permission) are not scanned: Scan Project and the build gate warn about them in the Console, and CI lists them in its report; for a full scan, use Asset Serialization → Mode → Force Text, fetch LFS files and close the program that holds a locked file; to make CI count them as violations, pass -srGateStrict.
  • a file last saved before Unity 2021.2 stores managed references in an older format: the build and CI warn about it instead of checking it, until it is saved again, for example with AssetDatabase.ForceReserializeAssets().

Excluded scan folders excludes folders from Project References, player-build checks, CI and breakage detection.

Build / CI gate, Excluded scan folders and Auto de-alias duplicated list elements are project settings with a violet stripe. They live in ProjectSettings/SerializeReferenceSharedSettings.asset, shared by the team and CI, and also open in Project Settings → Aspid.FastTools → SerializeReference.

SerializeReference section of the Settings tab: project settings with a violet stripe, per-user ones with a gray oneSerializeReference section of the Settings tab: project settings with a violet stripe, per-user ones with a gray one

Running in CI​

Unity -batchmode -projectPath . \
-executeMethod \
Aspid.FastTools.SerializeReferences.Editors.SerializeReferenceCiGate.RunCheck \
-srGateReport SerializeReferenceGateReport.txt \
-srGateRequired -srGateFail

RunCheck works only with -batchmode: without it, it logs a warning and checks nothing. Exit code 2 means the check itself failed.

Command-line flags​

FlagBehaviour
-srGateReport <path>Report path from the project root, SerializeReferenceGateReport.txt by default; the folder must exist, the file is overwritten
-srGateRequiredAlso checks unset fields with Required = true
-srGateFailUses Fail instead of the project's mode, even Off
-srGateWarnOnlyUses Warn instead of the project's mode, even Off; takes precedence over -srGateFail if both are passed
-srGateStrictCounts files that could not be checked (unfetched Git LFS files, binary assets that can hold references, files that could not be opened, files saved before Unity 2021.2) as violations; in Warn mode the exit code stays 0

Report​

The report lists missing types, unset required fields and skipped files. Skipped files do not change the exit code, unless -srGateStrict is passed.

A player build and a CI run show the first 50 violations in the log and count the rest; the report and Scan Project list them all.

Report format

The report starts with a header:

# SerializeReference Gate Report
# Violations: 2
# Not scanned: 4
# Binary Assets/Legacy/OldLoadout.prefab
# LfsPointer Assets/Levels/Arena.unity
# Unreadable Assets/Levels/Boss.prefab
# UnsupportedReferencesVersion Assets/Legacy/OldWave.asset

Each skipped file comes with its reason: a binary file, an unfetched Git LFS file, a file that could not be opened (Unreadable: locked by another program or no read permission), or managed references in a format older than Unity 2021.2.

Then one line per violation, tab-separated:

KIND assetPath fileId rid className fieldPath origin ns asm
FieldContents
KINDMissingType, MissingTypeName or RequiredUnset
assetPathFile path
fileIdHost object ID within the file; for a prefab instance override, the ID of the prefab instance
ridManaged-reference ID; in RequiredUnset rows, -2 for an empty [SerializeReference] and 0 for a string or SerializableType; in MissingTypeName rows, the managed reference that holds the field, or 0
classNameStored class name for MissingType; the whole stored type name for MissingTypeName
fieldPathRequired field path; the wrapper field for MissingTypeName; for a MissingType override, the overridden field; otherwise empty
originoverride for a type set by a prefab instance override; otherwise empty
nsStored namespace for MissingType; otherwise empty
asmStored assembly for MissingType; otherwise empty

In Asset References, find an entry by its rid, and a RequiredUnset row with rid 0 by its fieldPath; an override row is in the Prefab instance overrides section of Project References instead. A MissingTypeName row is in its type name group of Project References.