Skip to content

t1k:unity:base:build-gate

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: build gate, build guard, build validation, BuildFailedException, Discord sentinel, Jenkins build failure, preprocess build

/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.

IntentRead
Write a new gateThe five calls → Checklist
Review / ship an existing gateChecklist → Gotchas
Marker + sanitising mechanicsreferences/sentinel-contract.md
Jenkins / Discord / CI sidereferences/jenkins-reporting.md
  1. using GameFoundation.Editor.Diagnostics; — and add GameFoundation.Editor to the consuming asmdef’s references. Check for a circular reference first: GameFoundation.Editor.asmdef references neither Localization nor 3rd, so those directions are safe.
  2. Implement IPreprocessBuildWithReport with a large negative callbackOrder (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 than BuildPlayer itself.
  3. DiscordErrorSentinel.LogError(headline, body) — headline is one line, body carries the detail and the call sites.
  4. throw new BuildFailedException(<plain message>) — UNWRAPPED.
  5. Nothing on the clean path: return early when there are no findings.
  • Sentinel emitted before the throw, on every failing path.
  • BuildFailedException message 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.Editor present in the consuming asmdef’s references.

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.

  • 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.ps1 builds $compileErrorLines from the CompilerOutput:/EndCompilerOutput pair 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”
PathShows
Packages/com.gdk.3rd/Configs/Editor/AdNetworkConflictBuildGuard.csGate + unwrapped throw
Packages/com.gdk.3rd/Configs/Editor/AdNetworkConflictBatchModeGuard.csBatch-mode fast path
Packages/com.gdk.core/Editor/Validator/AddressableDuplicateAddressBuildGuard.csClean-path early return
Packages/com.gdk.core/Editor/Localization/LocalizationMissingKeyBuildGate.csBypass reported as warnings
Packages/com.gdk.3rd/IAP/Editor/IAPTangleBuildGate.csGate 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).

  • t1k-unity-editor-cli — compile / refresh verification on the Editor side
  • t1k-jenkins-unity, t1k-jenkins-build — Jenkins-side build facts
  • t1k-unity-base-code-conventions — C# / Unity conventions this code must follow