t1k:unity:optimize:assets
| Field | Value |
|---|---|
| Module | optimize |
| Version | 2.35.6 |
| Effort | medium |
| Tools | — |
Keywords: asset-optimize, audio-import, build-size, editor-closed, import-preset, meta-scan, static-audit, texture-import
How to invoke
Section titled “How to invoke”/t1k:unity:optimize:assets[--tier low|mid] [--target <BuildTarget>] [--class <assetClass>] [--limit N] [--json-out <path>] [--include-submodules]Unity Asset Optimization — Static, Editor Closed
Section titled “Unity Asset Optimization — Static, Editor Closed”Reads .meta YAML, prefab/scene/material documents, ProjectSettings/, and binary asset headers
on disk, then emits a byte-ranked, evidence-carrying report plus per-submodule work orders. It
never acquires the Unity Editor, so it runs in CI, headless, on a build agent, and while a
teammate holds the Editor mutex (t1k-unity-editor-cli SKILL.md § “Editor mutex: obligations that stay”).
What this does NOT do
Section titled “What this does NOT do”This skill reads files on disk. It never opens the Unity Editor, never builds, and never runs
the game. Everything below is a structural boundary, not a missing feature. Read this section
before you read a report — a finding count means nothing without the list of what was never
looked at (rules/green-that-proves-nothing.md).
It cannot measure anything that only exists while a frame is rendering. Overdraw, fill rate,
draw-call and batch counts, SetPass calls, per-frame GC, actual frame time, real memory
residency. No file contains a frame. Where a static property correlates with one of these —
raycast-target ratio, instancing off, MSAA level — it is reported in a separate frame-time
section carrying no byte figure, because a correlate is not a measurement. Profile on a device
with t1k:unity:editor:profiling, or against a live Editor,
before acting on any of it.
It cannot know what your build produced. Compressed on-disk size after crunch, atlas page
count and packing efficiency, shader variants surviving stripping, bundle layout, bundle-level
dedup, final APK/IPA size. A crunched texture reports estimatedSavingBytes: null rather than a
guessed number. Those figures come from a build, or from a profiling session —
t1k:unity:editor:profiling owns that ground, not this skill.
It cannot know your build target. EditorUserBuildSettings lives under Library/, which is
gitignored, so a fresh clone and a CI checkout have no build target at all. Pass --target
explicitly; it is never inferred. Without it, findings are evaluated against the
DefaultTexturePlatform block — which is what the project ships from anyway: every one of the
6,095 per-platform blocks in the calibration project is overridden: 0.
It cannot see references made in code. Only 8 of 30 Resources.Load call sites in the
calibration project pass a string literal; the rest pass a variable, as does
Addressables.LoadAssetAsync(key). Every “unused”/“orphan” finding is a lower bound on
liveness and an over-report of orphans, is informational only, is never denominated in savings,
and must never be the sole basis for deleting an asset.
It cannot resolve prefab-variant and nested-prefab overrides. A value read from a prefab file is that file’s value, not the value the scene instance ends up with. VFX and UI component counts are therefore an explicit lower bound.
Its 3D rules are fixture-validated, not corpus-validated. The calibration project is 2D: no LODGroup, no real SkinnedMeshRenderer, no Terrain, and two FBX cards between them. Every LOD, skinning, mesh, terrain and URP rule was proven red-then-green against a hand-built synthetic fixture and has never fired on a real 3D project. Treat 3D output as a first draft and check it by hand.
Some rules ship mute because no threshold was ever sourced. A rule whose predicate reads a
budget path that resolves to a blind[] entry emits nothing and pushes its property into
coverage[<class>].measuredBlind instead. 72 rules ship mute for want of a sourced threshold
— they are listed in references/asset-classes.md, and the remainder fire out of the box. A
consumer who authors the missing values in references/budgets.json un-mutes them.
It never writes. v1 is report-only: no .meta write, no Editor script, no t1k unity call
anywhere in this skill. To apply, use the Editor tooling below.
Before you run this: do you already have a better tool?
Section titled “Before you run this: do you already have a better tool?”If this project ships UITemplate’s Optimization Hub (Assets/UITemplate/Tools/Optimization/,
menu TheOne → Optimization Hub — OptimizationHubWindow.cs:20), use it for in-Editor bulk
apply, real SpriteAtlas membership resolved by the packer, and Addressables group-schema
questions. It applies (SaveAndReimport() at Modules/TextureModule.cs:277,324,
Modules/AudioModule.cs:723, Modules/MeshModule.cs:310 — the module files live under
Modules/, not beside the window); this skill does not. This skill covers the layer the Hub does
not reach: per-platform import policy, registered import Presets, URP/QualitySettings/
GraphicsSettings project policy, cross-type duplicate content, shipping-vs-editor separation,
submodule scoping, and running at all with the Editor closed.
If this project ships TheOneFeature, the ten Project Auditor descriptors are available
natively at Packages/TheOneFeature/Editor/ProjectAuditorOptimizerToolModule.cs, and
t1k:unity:optimize:project-auditor consumes a .projectauditor report directly. This skill does
not import that report — four of the ten fixes are already decided here from committed
ProjectSettings/ values with no report and no Editor, and the overlapping rules emit the same
finding ids so the two outputs are comparable rather than contradictory.
Both of those tools require a live Editor and the Editor mutex. This skill runs in CI, headless,
on a build agent, and while a teammate holds the Editor — and it ships to every theonekit-unity
consumer, most of whom have neither submodule. That gap is why it exists. Full comparison, the
per-module coverage tables, the dead-code finding, and the recorded prior-art search scope:
references/prior-art-and-positioning.md.
Required input and tier
Section titled “Required input and tier”- Unity project root — the directory holding
Assets/andProjectSettings/. Positional argument. A repo containing more than one is a hard error listing them, never a silent pick. --tier— required, resolved against the populated tier keys ofreferences/budgets.json. There is no default and no fallback: an unpopulated or unknown tier is a hard error that lists the tiers that exist, because a documented flag that can only ever error is worse than one that does not exist.--target— explicit build target, never inferred (see the boundary section above).--limit— human render only. Its default isbudgets.report.maxExampleRowsPrintedinreferences/budgets.json; that section is the single source, and this body deliberately does not restate its value.
Every threshold in every rule resolves through references/budgets.json. No number in this skill
is written into a predicate.
Workflow
Section titled “Workflow”1. Scan.
bun scripts/scan.cjs <unityRoot> --tier <tier> [--target <BuildTarget>] \ --json-out .t1k/optimize-report.jsonThe bounded render goes to stdout and is what you read; the complete document is written to that
path and is what you re-query for detail. Never read the full document into context — that is
what --json-out exists to prevent (skills/t1k-team/references/lean-brief-pointer-not-payload.md (theonekit-core)).
2. Read coverage first. Print applicable / structuralBlind / measuredBlind per class
before naming a single finding. A “0 findings” result is bounded by that block and means nothing
without it.
3. Rank. Byte-ranked table from findings.manual, ordered by currentBytes descending, with
estimatedSavingBytes and totals.estimatedSavingUnknownCount printed together —
never a saving total without its unknown count. shipping: false rows are excluded from the
ranking by default. totals.frameTimeFindingCount is a separate section and is never folded into
a byte total.
4. Work orders. submoduleWorkOrders[] becomes one order per submodule, each with its remote
URL, finding count, byte total and top finding ids, so the informational bucket is not a dead end.
There is no step 5. v1 ends at the report; applying belongs to the Editor tools above. The detail
surface for step 3 is --limit, --sort, --fail-on, --class and --include-submodules;
--fail-on is what makes the scan a CI gate.
Acting on the report at scale
Section titled “Acting on the report at scale”Acting on the report at scale. This skill only reports. The moment you or the user act on the
report across more than a handful of assets — opening the Hub’s bulk “Fix All”, hand-editing a
batch of .meta files, or running a future apply layer — the batch rule fires
(rules/preview-first-batch.md: whichever comes first, more than ten items or more than two
minutes; unknown volume fires it by default).
- State the estimate before the first mutating call: “smoke a five-asset slice, then the full
”. Unknown volume is itself the estimate — say so rather than staying silent. - Smoke the smallest meaningful slice and surface the result — per-item wall clock, the values changed, anything unexpected.
- Then call
AskUserQuestion(rules/always-ask-on-unresolved.md— prose “shall I continue?” is a rule violation, not a shortcut) with these options: · Proceed — run the full batch as smoked · Investigate — stop and examine the smoke result before deciding · Re-smoke — different slice or smaller N · Abort — revert the smoke and stop - A clean smoke is not permission. Ask even when nothing looked wrong. If the smoke wrote files, list them and the rollback command in the question body.
If AskUserQuestion is deferred this session, run
ToolSearch(query="select:AskUserQuestion") and then call it. Deferral is never a
licence for a prose fallback.
Submodule scope is part of the same gate: a batch touching a path under scope.submodulePrefixes
dirties a tree this repo cannot commit (rules/kit-pr-workflow-boundary.md), so the question body
must name the submodules involved.
Reference docs
Section titled “Reference docs”Machine-read registries, loaded by the scripts and by the tests: references/asset-classes.md
(class + rule registry, and the muted-rule list), references/rule-registry.md (canonical for
every rule predicate), references/budgets.json, references/unity-enums.json,
references/meta-key-vocabulary.md, references/serialized-name-map.json,
references/fix-set-schema.md.
Per-class prose — what the class is, its rules with the serialized key each reads, what the class
is blind to, and the budget key paths it consults: references/texture.md,
references/sprite.md, references/sprite-atlas.md, references/font.md,
references/audio.md, references/model.md, references/lod.md, references/material.md,
references/shader.md, references/animation.md, references/ui.md, references/vfx.md,
references/addressables.md, references/scene.md, references/lighting.md,
references/terrain.md, references/render-texture.md, references/plugin.md,
references/project.md, references/resources.md, references/orphan.md,
references/duplicate.md, references/editor-shipping.md.
Positioning against the two in-repo Editor tools: references/prior-art-and-positioning.md.
Executed by
Section titled “Executed by”The scripts/collect-*.cjs collectors and scripts/scan.cjs are read-only and deterministic:
| Step | Agent |
|---|---|
Run scan.cjs and read the byte-ranked report | t1k-fact-fetcher |
| Tally bytes per asset class and tier | t1k-metrics-reporter |
| Decide which import-setting changes to recommend or apply at scale | reasoning tier — t1k-unity-base-optimizer; the skill itself writes nothing |
Hard rules
Section titled “Hard rules”| Gotcha | What it means |
|---|---|
| Editor-closed by design | This skill never calls t1k unity and never opens the Editor. If a question needs the Editor, it belongs to another skill — say so, don’t reach for t1k unity eval. |
| Indent is part of the key | Six keys are bare-name ambiguous in three different ways, and a bare-name grep reads the wrong value with no error. Four exist at two indents with inverted distributions, so no “take the deeper one” heuristic is right: maxTextureSize (Assets/icon.png.meta:34 @2 vs :72 @4), textureFormat, isReadable (@2 on TextureImporter, icon.png.meta:24; @4 under ModelImporter.animations, …/Star.fbx.meta:33), preloadAudioData (@2 on AudioImporter sv6, …/Music3.ogg.meta:17; @4 on sv8, Assets/Audios/sfx_drag_begin.mp3.meta:14). One exists only at 4-space inside a platform block: crunchedCompression (icon.png.meta:77) — a 2-space grep returns nothing and reads as “no crunch anywhere”. One exists twice at the same indent under two parents — next row. |
overridden: 0 means the Default block governs | Not “skip”. No per-platform block in the calibration project is overridden — the DefaultTexturePlatform block is what ships. Never write overridden: 1. |
Atlases carry two textureCompression keys | Both at 4-space, under different parents. textureSettings.textureCompression is not the governing value; platformSettings[DefaultTexturePlatform].textureCompression is. Verified in Packages/TheOneFeature.PuzzleUI/Common/SpritesAtlas.spriteatlasv2.meta at :10 under textureSettings: against :22 under platformSettings:. Reading the wrong one reports every atlas uncompressed. |
| Preset-driven drift | A registered default Preset (ProjectSettings/PresetManager.asset → Assets/Importers/AudioImporter.preset) rewrites preloadAudioData back on for every newly imported clip. Fix the Preset first, or every applied fix regresses on the next import. |
| Preset paths use a second vocabulary | The Preset says m_DefaultSettings.preloadAudioData; the .meta says defaultSettings.preloadAudioData. The join goes through references/serialized-name-map.json, never a mechanical m_ transform. |
| Editor art is excluded from ship-size | shipping: false — an Editor/ or Gizmos/ path segment, or an editor-only .asmdef — drops a finding out of the byte ranking. Including it inflates the texture bucket enormously. |
| Submodule findings are informational, never skipped | They route to work orders carrying a remote URL. A skipped reason of “submodule” does not exist. |
| Orphans are a lower bound on liveness | Code-built keys leave no static trace. Never delete on an orphan finding alone. |
| 3D rules are fixture-validated | Fixture-validated, not corpus-validated: the calibration corpus is 2D. Treat 3D output as a first draft. |
--target is explicit | EditorUserBuildSettings lives under gitignored Library/; a fresh clone has no build target. Inferring one makes the tool answer differently on a dev machine than in CI. |