t1k:unity:base:build-gate
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: build gate, build guard, build validation, BuildFailedException, Discord sentinel, Jenkins build failure, preprocess build
How to invoke
Section titled “How to invoke”/t1k:unity:base:build-gate[new gate <feature> | review <path-to-gate>]Unity Editor Build Gate — Reporting Contract
Section titled “Unity Editor Build Gate — Reporting Contract”Every Editor build gate that fails a build MUST also say why, in the build log, in a form Jenkins
forwards to Discord. A gate that throws BuildFailedException with nobody told why turns a real
defect into “Unknown error, showing last 20 lines” — the reader gets the failure and no
diagnosis. That gap is the entire reason this skill exists.
SSOT (in the project, not here): Packages/com.gdk.core/Editor/Diagnostics/DiscordErrorSentinel.cs,
namespace GameFoundation.Editor.Diagnostics, asmdef GameFoundation.Editor. Never touch the marker
strings directly — call the class. It is the producer side of a contract the Jenkins scanner owns.
Decision Tree
Section titled “Decision Tree”| Intent | Read |
|---|---|
| Write a new gate | The five calls → Checklist |
| Review / ship an existing gate | Checklist → Gotchas |
| Marker + sanitising mechanics | references/sentinel-contract.md |
| Jenkins / Discord / CI side | references/jenkins-reporting.md |
The five calls a gate makes
Section titled “The five calls a gate makes”using GameFoundation.Editor.Diagnostics;— and addGameFoundation.Editorto the consuming asmdef’sreferences. Check for a circular reference first:GameFoundation.Editor.asmdefreferences neither Localization nor 3rd, so those directions are safe.- Implement
IPreprocessBuildWithReportwith a large negativecallbackOrder(e.g.-10000) so it runs before sibling preprocessors — including any third-party SDK that adds one later. It orders against siblings only; it cannot move the check earlier thanBuildPlayeritself. DiscordErrorSentinel.LogError(headline, body)— headline is one line, body carries the detail and the call sites.throw new BuildFailedException(<plain message>)— UNWRAPPED.- Nothing on the clean path: return early when there are no findings.
Checklist
Section titled “Checklist”- Sentinel emitted before the throw, on every failing path.
-
BuildFailedExceptionmessage is plain — never the sentinel-wrapped text. - Body has somewhere to go: key +
file:line, not merely a count. - A bypass path reports its findings as warnings (see below).
- Decision logic is pure and static (
DescribeFailure,DescribeErrorSites) so an EditMode test can drive it without starting a build. -
GameFoundation.Editorpresent in the consuming asmdef’sreferences.
Why one call, never a LogStart/LogEnd pair
Section titled “Why one call, never a LogStart/LogEnd pair”Splitting the block across several Debug.LogError calls lets Unity’s stack traces land inside
the captured region and corrupt it. There is deliberately no paired logging API: Wrap is a pure
string builder for callers that need the string, and LogError emits the whole block in one call so
the stack trace falls after EndErrorToDiscord. Mechanics: references/sentinel-contract.md.
A bypass that still fails the build is a lie
Section titled “A bypass that still fails the build is a lie”A Debug.LogError fails a batch-mode build by itself. So a gate with an escape hatch
(T1K_SKIP_* env var) must report its findings as warnings when bypassed — otherwise the bypass
still fails everything it was invoked to let through.
Reference: LocalizationMissingKeyBuildGate.OnPreprocessBuild. It reads the variable from this
process’s own environment, treats an EMPTY value as no bypass (an accidental empty export must
never silently disable a gate while CI reports green), and names the variable in the failure message
— the failure is where someone reads it, and an escape hatch documented only in a plan file is not
available in the CI run that is stuck.
Editor-driven build vs CI — two callbacks, not one
Section titled “Editor-driven build vs CI — two callbacks, not one”IPreprocessBuildWithReport fires inside BuildPipeline.BuildPlayer. By then script
compilation, asset import and the Addressables build have all already happened, so it is the
authoritative path and the slowest one.
A batch-mode fast path at the first domain reload ([InitializeOnLoadMethod] +
Application.isBatchMode) catches the same problem minutes earlier on CI. It never replaces the
build guard: an Editor-driven build must fail its build, not kill the developer’s Editor — so the
fast path is restricted to the main batch-mode process, guarded by
AssetDatabase.IsAssetImportWorkerProcess() (without that, every import worker aborts too, and the
real message stays buried in the worker’s own log). Detail: references/jenkins-reporting.md.
Hard rules
Section titled “Hard rules”- The gate is late by construction. Everything it would have flagged has already been paid for. That is why the batch-mode fast path exists — do not present the gate as an early check.
- CI may not surface your compile errors at all.
JenkinsScripts/Scripts/Util_AnalyseUnityLog.ps1builds$compileErrorLinesfrom theCompilerOutput:/EndCompilerOutputpair on line 11 and then never uses it — every failure prints “Unknown error, showing last 20 lines”. Never assume a gate’s message reaches the reader through that path; that assumption is what the sentinel pair exists to defeat. Do NOT “fix” that script from a gate task — it is out of scope. - The markers are not
T1K_-tagged, deliberately. They are fixed verbatim by the Jenkins scanner. Do not rename them to fit the repo’s tag convention. - Never emit a pair around nothing. A whitespace-only body returns empty rather than a marker pair — the class already does this. Do not bypass it by assembling the string yourself.
Reference implementations — read one before writing a new gate
Section titled “Reference implementations — read one before writing a new gate”| Path | Shows |
|---|---|
Packages/com.gdk.3rd/Configs/Editor/AdNetworkConflictBuildGuard.cs | Gate + unwrapped throw |
Packages/com.gdk.3rd/Configs/Editor/AdNetworkConflictBatchModeGuard.cs | Batch-mode fast path |
Packages/com.gdk.core/Editor/Validator/AddressableDuplicateAddressBuildGuard.cs | Clean-path early return |
Packages/com.gdk.core/Editor/Localization/LocalizationMissingKeyBuildGate.cs | Bypass reported as warnings |
Packages/com.gdk.3rd/IAP/Editor/IAPTangleBuildGate.cs | Gate keyed on a define + per-target table, reflection probe, bypass as warnings |
Editor-side build gates and how they report. Not: Jenkins job / define-symbol mutation
(t1k-unity-mobile-floor-probing-jenkins), Editor-side compile verification
(t1k-unity-editor-cli), or general C# conventions (t1k-unity-base-code-conventions).
Related
Section titled “Related”t1k-unity-editor-cli— compile / refresh verification on the Editor sidet1k-jenkins-unity,t1k-jenkins-build— Jenkins-side build factst1k-unity-base-code-conventions— C# / Unity conventions this code must follow