Skip to content

t1k:unity:optimize:assets

FieldValue
Moduleoptimize
Version2.35.6
Effortmedium
Tools—

Keywords: asset-optimize, audio-import, build-size, editor-closed, import-preset, meta-scan, static-audit, texture-import

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

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.

  • Unity project root — the directory holding Assets/ and ProjectSettings/. 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 of references/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 is budgets.report.maxExampleRowsPrinted in references/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.

1. Scan.

bun scripts/scan.cjs <unityRoot> --tier <tier> [--target <BuildTarget>] \
--json-out .t1k/optimize-report.json

The 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. 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).

  1. 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.
  2. Smoke the smallest meaningful slice and surface the result — per-item wall clock, the values changed, anything unexpected.
  3. 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
  4. 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.

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.

The scripts/collect-*.cjs collectors and scripts/scan.cjs are read-only and deterministic:

StepAgent
Run scan.cjs and read the byte-ranked reportt1k-fact-fetcher
Tally bytes per asset class and tiert1k-metrics-reporter
Decide which import-setting changes to recommend or apply at scalereasoning tier — t1k-unity-base-optimizer; the skill itself writes nothing
GotchaWhat it means
Editor-closed by designThis 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 keySix 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 governsNot “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 keysBoth 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 driftA 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 vocabularyThe 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-sizeshipping: 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 skippedThey route to work orders carrying a remote URL. A skipped reason of “submodule” does not exist.
Orphans are a lower bound on livenessCode-built keys leave no static trace. Never delete on an orphan finding alone.
3D rules are fixture-validatedFixture-validated, not corpus-validated: the calibration corpus is 2D. Treat 3D output as a first draft.
--target is explicitEditorUserBuildSettings 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.