Skip to content

t1k:unity:web:optimize

FieldValue
Moduleweb
Version2.32.3
Efforthigh
Tools—

Keywords: browser, build-size, memory, performance, startup, wasm, web, webgl

/t1k:unity:web:optimize

Optimize only from measured evidence. Keep compatibility migration out of this command.

Route runtime/build optimization through t1k-unity-base-optimizer. Do not invoke the generic optimizer role unless the audit proves the affected code is DOTS/ECS; the kit-wide generic role currently resolves to the DOTS optimizer.

  • A representative Web build completes and reaches gameplay in the target browser.
  • Target scene, browser version, hardware/device, cache state, and sample window are recorded.
  • At least one explicit budget is supplied or agreed:
    • compressed download size,
    • peak memory,
    • time to first interaction,
    • average/p95 frame time.

If these preconditions fail, route to /t1k:unity:web:audit or /t1k:unity:web:convert.

  1. Inventory build artifacts:

    Terminal window
    bun .claude/skills/t1k-unity-web-optimize/scripts/analyze-web-build.cjs <build-dir> --size-mb 20 --encoding br

    When running from this source repo, use the module-local path under .claude/modules/web/skills/t1k-unity-web-optimize/.

    Match --encoding to deployment (identity, br, gzip, or unityweb for Unity’s decompression fallback artifacts). Use smallest only for theoretical comparison, not release sign-off. When both Brotli and gzip artifacts exist, budget evaluation requires an explicit encoding. A budget cannot pass unless loader, framework, Wasm, and data artifacts form a complete build. Symbols, source maps, screenshots, backups, and separately loaded content are inventoried but excluded from initial delivery size.

  2. Capture baseline metrics before changing settings.

  3. Rank bottlenecks by budget impact, confidence, risk, and verification cost.

  4. Change one coherent category at a time:

    • IL2CPP optimization and managed stripping/link preservation.
    • WebAssembly target, exception/debug settings, compression, and Data Caching.
    • texture/audio/mesh/data payload and Addressables delivery.
    • shader variants, post effects, draw calls, overdraw, and main-thread work.
    • allocations, heap growth, peak memory, and long-session stability.
  5. Rebuild and compare under the identical test protocol.

  6. Revert changes that do not produce a material improvement or cause compatibility regressions.

Read references/measurement-protocol.md before accepting a performance result.

  • Build artifact inventory: loader, framework, Wasm, data, symbols, other; raw and encoded totals.
  • Baseline and after values for every declared budget.
  • Applied/skipped recommendations with evidence and rollback notes.
  • Browser/device matrix and cache state.
  • Budget pass/fail and remaining bottlenecks.

The existing /t1k:unity:optimize:project-auditor may supplement this workflow when its module and report are available. It does not replace Web measurement.

Never optimize without a baseline. Never claim universal browser support from one desktop run.

Only the measurement step (scripts/analyze-web-build.cjs) is mechanical:

StepAgent
Run analyze-web-build.cjs on the build output and read the size/memory figurest1k-fact-fetcher
Choose and apply the optimization against the budgetreasoning tier — t1k-unity-base-optimizer (see Agent routing above)