Scenario Unity Pipeline Automation

Unity pipeline automation (tools and build engineer)

Expert level here means a pipeline that gives the same result on every machine and every run: rules applied at import time, edits made through serialization, content packed by when it loads, tests that gate the build, and a build that CI runs from a clean checkout. The stance: nothing is done by hand twice, nothing is trusted without a count, a test or a frame, and a second run changes nothing. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-unity-expert (channels, job protocol, review loop, 6.3 traps). Import its toolkit; this skill adds scripts/ut_pipeline.py and scripts/AgentKit/Pipeline/.

Status (2026-09-24, after the blind-grade refactor): every procedure ran in Unity 6000.3.21f1 on this Mac against a 200-FBX Blender drop: tests/code/unity-pipeline-automation/ (results in archive/tests/unity-pipeline-automation/live_results.jsonl).

Stance (the expert delta)

1. Import rules are code that runs at import, and deterministic, and you prove it. Settings in OnPreprocess*, GetVersion() bumped on every code change, config declared before it is read (context.DependsOnSourceAsset), no clocks, no dictionary order, no asset writes in callbacks (6.3 Manual; Javier Abud Chavez, S2P9n5U9xVw [00:04:35], [00:19:29]). Proof: -consistencyCheck before trusting a shared cache or CI (Manual). Observed: 12,184 assets checked in 23.5 s; a random-pixel probe texture flagged, 0 of the 593 governed files. A bump or a new postprocessor reimports every asset of that importer type, packages included (1,513 textures).
2. An edit counts only if it goes through serialization, on the exact object. Record Undo on the component that changes, before the change (Freya Holmér, pZ45O2hg_30 [03:01:01]). Observed: Undo.RecordObject(go) then a move is not undone; RecordObject(go.transform) is. A direct write on a prefab instance reverts at the next prefab update; a ScriptableObject is not saved without SetDirty.
3. One AssetDatabase batch per stage, measured. StartAssetEditing / StopAssetEditing in try/finally (Abud Chavez [00:30:21]), and SaveAndReimport / ImportAsset inside it too. Count with the AssetDatabase counters, not the log (Abud Chavez [00:26:44]). Observed: two remap passes over 195 FBX, 19.0 s one by one vs 5.1 s batched.
4. Pack Addressables by loading condition, not by folder, in a stable order. Assets needed under exactly the same conditions share a group; dependencies used by several groups are placed explicitly (Olle Axelsson, Valheim, Fzu2Das_1FU [00:23:08]). Unassigned shared dependencies are copied into every bundle [00:18:44]; observed, that includes URP's Lit.shader. Assign in ordinal order (6.3 Manual, Addressables determinism): 2.9.1 sorts groups and entries by GUID when it saves, but the label table keeps insertion order.
5. Released is not unloaded, and references are loads. Memory returns when the bundle's refcount reaches zero (Addressables 2.9 manual); a build scene that references Addressable content loads it with the scene and again from the bundle (Code Monkey, C6i_JiRoIfk [00:03:32]; Axelsson [00:24:49]). Gate it; measure unloads in the player.
6. Fix the platform at launch, the same on every stage, and ship the content you built. Target switches inside a batch job do nothing (Manual; Thom Hopper, BlVsi2cSJ88 [00:27:18]); build target is an import dependency (Abud Chavez [00:15:49]). Observed: one stage on Android reimported 1,717 assets in 52 s; switching back reused cached artifacts (60 imports). Addressables' default settings rebuild all content inside every player build.
7. Tests are the gate. Content rules as parametric Edit Mode tests, one case per asset (Warnecke and Fine, wTiF2D0_vKA [00:24:28]), run synchronously in a pre-build callback that logs the pass [00:31:43]. Any logged error fails a test unless LogAssert.Expected (Manual); observed, that includes an import error logged by a reimport inside the test. Never -quit with -runTests.
8. Release builds come from a clean tree, without debug defines, with provenance kept (docs digest checklist; Hopper, profile defines). Narrow named tools over generic execution (git-amend, VPjo-M6mPkE [00:03:54]; Unity, DgNrgZeJOxQ [00:07:41]).

Establish first

• Drop contract: DCC and export settings, folder per category, suffixes, units. Default: Blender "FBX All" + "Apply Transform", _BaseColor/_Normal, a manifest.csv for extra labels.
• Loading conditions: loaded as a set (level, biome) or one by one? Default: labels, key_by="label"; streaming uses key_by="root".
• Targets and budgets: platforms (one -buildTarget per pipeline run), texture cap per platform, vertex budget, bundle budget per label. Defaults: 1024 px desktop, 512 mobile, 5,000 vertices.
• Content updates: remote content after release? Archive addressables_content_state.bin per platform per release.
• Channel and CI: is the user's editor open on the project (ut_live.channel(P))? Git repo? Accelerator? License: Personal (Hub sign-in only) or paid seat.

Workflow

1. Preflight. ut_env.preflight(P); ut_pipeline.install(P). Editor open: the same jobs through ut_live.call or the [CliCommand] tools. Pipeline code a team's tests must call: its own Editor asmdef plus a test asmdef (install_asmdef_template). GATE: Echo ok, zero compile errors (one aborts every batch job).
2. Scan the drop offline. up.scan_drop(drop), same rules JSON. GATE: every reject has a reason; duplicates reject every copy.
3. Import. up.import_drop(P, drop, target=T): changed files into <root>/<Category>/<Name>/, one batch, audit. GATE: accepted = found - rejected; audit errors explained; after a postprocessor change, up.consistency_check(P, target=T) flags nothing under Assets/.
4. Materials and prefabs. up.build_prefabs(P, target=T): URP Lit per prop, keywords by ShaderGUI.ValidateMaterial, FBX remaps with SaveAndReimport inside the batch, Prefab Variants built in a preview scene, saved only when a value changed. GATE: prefabs = accepted - size errors; a rerun rewrites 0 files (git status clean).
5. Look at it. EditorEditJobs.BuildLineup then AgentCapture.CaptureViews with graphics=True, ut_review.review_capture, open the sheet. GATE: no magenta, black or blank flags; props upright, grounded, in scale.
6. Addressables groups. up.assign_addressables(P, "condition", target=T). GATE: implicit_duplicates == 0; up.hard_references(P) ok.
7. Content build. up.build_content(P, T): builder index >= 0, ClearCachedData + BuildCache.PurgeCache(false), DoNotBuildWithPlayer, layout read back, state archived. GATE: duplicated assets 0, bytes per label within budget.
8. Tests. ut_run.run_tests(P, "EditMode", categories="PipelinePreBuild", extra_args=["-buildTarget", up.cli_target(T)]). GATE: failed 0, total equals the expected asset count.
9. Player build. Profile copied from a committed template (PipelineBuild.CreateBuildProfile with template), ut_run.build(P, T, profile=...), or raw -activeBuildProfile ... -executeMethod AgentKit.Pipeline.PipelineBuild.BuildFromCommandLine. Release: -agentRelease (gate refuses debug defines), clean tree, up.release_ready(repo, app). GATE: AGENT_GATE ok with hard_references 0, BuildReport Succeeded.
10. Smoke the player. up.player_smoke(app, label). GATE: loaded assets equal the manifest count; bundles unload after release.
11. CI. up.write_ci(repo): ci/pipeline.sh (one process per stage, the same -buildTarget on each; ACCELERATOR=, CONSISTENCY=1, RELEASE=1) and GitHub Actions files. GATE: passes from a checkout without Library/; license returned if: always(); with Accelerator, the log's cache server= count above 0.