Skip to content

t1k:unity:editor:look-spec

FieldValue
Moduleeditor
Version3.50.7
Effortmedium
Tools—

Keywords: code-driven look, look spec, look-spec, palette spec, visual spec

/t1k:unity:editor:look-spec
[setup|apply|dump|list|capture]

Change a game’s look by editing ONE JSON file, applying it with an Editor-only compiler, reading the project back, and viewing a screenshot. The compiler writes serialized state (scenes, prefabs, ScriptableObjects, materials); nothing is built in runtime code.

Measured on one game (6 trials per arm, Sonnet 5.5, raw Unity vs spec): median cost $0.73 vs $1.47 (about half), 157 s vs 314 s on unloaded tasks, pass 5/6 vs 3/6. Tokens only fell 22%, short of the 30% bar, so treat this as a POC and report friction. The correctness win is the shared-material fork below.

Palette colours, background/camera clear colour, ambient and fog, directional light, UI tint. A repeated “recolour, render, look” loop is where it pays. Not for gameplay, layout, new objects or VFX (not in v0). A one-off single-property tweak does not need the setup cost.

  1. Needs Newtonsoft Json (com.unity.nuget.newtonsoft-json) and the Test Framework. Assets under Assets/Editor/ only.

  2. Copy assets/templates/ into Assets/Editor/LookSpec/, dropping the .txt suffix from each *.cs.txt and *.asmdef.txt; Tests/ goes to Assets/Editor/LookSpec/Tests/. The .txt suffix only keeps the kit repo from treating templates as live C#.

    Terminal window
    T=<skill-dir>/assets/templates; D=Assets/Editor/LookSpec
    mkdir -p $D/Tests && for f in $T/*.asmdef.txt $T/*.cs.txt; do cp "$f" "$D/$(basename "${f%.txt}")"; done
    for f in $T/Tests/*.asmdef.txt $T/Tests/*.cs.txt; do cp "$f" "$D/Tests/$(basename "${f%.txt}")"; done
  3. Write Assets/Editor/LookSpec/look-spec.map.json: one entry per spec key, binding it to a file, object path, component and property. Format and the worked example: references/map-format.md. Find object paths with the list command, never by guessing.

  4. Start { "preset": "default" } in look-spec.json, set env LOOKSPEC_TRIGGER and launch the warm editor, then dump once and keep the result as baseline.json (restores the original look).

  5. Run the EditMode tests ({"test":"LookSpec.Tests"}) and require 0 failures before the first apply.

Commands go through the trigger file (details and JSON: references/capture-and-verify.md):

  • apply: validates every key first and writes nothing if any key is unknown or malformed (the error names the key); idempotent (a second apply reports 0 changes).
  • dump: current project values in spec schema; Apply(Dump()) changes nothing. Use it to prove state, not the screenshot.
  • list: hierarchy paths and component types of a scene or prefab, to write map entries.
  • capture: apply plus a play-mode PNG.

Workflow for a look task: read look-spec.json and the map, edit the spec (add a map entry if a key is missing), apply, dump and compare, capture, view the PNG. Do not hand-edit scenes or materials behind the spec; if one is unavoidable, dump afterwards and reconcile.

NEVER mutate a Material that anything other than the palette’s own owners references. Prefab-straight material references are the hidden trap: in the experiment raw edits silently recoloured a different prefab 2 of 6 times; the spec arm never did once the compiler forked.

  • Every materialColor map entry MUST list its owners. An empty owners disables the check.
  • On a write, the compiler scans scan folders for outside referencers. If found it copies the material to <name>_LookSpec.mat, repoints the owners at the copy, recolours only the copy, and logs LOOKSPEC_SHARED_FORK.
  • Do not “fix” the fork by editing the original. Verify the outside referencer still shows its original colour (SharedMaterial_IsForked_OriginalStaysUntouched test; capture the other prefab).

Capture before and after; judge the PNG against the intent and diff against the stored golden shot. Anything that changed outside the edited area is a side effect to investigate (usually a shared material). Procedure: references/capture-and-verify.md.

prefab-only-construction-unity forbids code-built GameObjects and scene wiring in runtime/gameplay code. It does not govern editor-only tooling. This compiler is allowed because it: lives in an Editor-only asmdef, runs at edit time, only sets serialized data on existing objects, creates no GameObjects and ships nothing into a build. Keep it that way: no runtime asmdef may reference LookSpec.Editor.

Full list in references/hard-rules.md. The ones that cost the most time:

  • Boards that exist only in play mode: capture in play mode and give root a component type that appears once the board is built.
  • Scripting defines that exist only for one build target: launch the editor with the right -buildTarget or the game code does not compile.
  • Scene-changed-on-disk and Save-As modals freeze the editor: use LookSpecScenes parking; never call NewScene or SaveOpenScenes.
  • Never terminate or restart the Editor on your own initiative (unity-forbidden-operations).
FileRole
LookSpecCompiler.cs.txtResolve preset, validate, apply; ApplyFromCommandLine for batch
LookSpecSession.cs.txtOpen files, read/write properties, shared-material fork
LookSpecMap.cs.txtMap file model and key matching
LookSpecReadback.cs.txtDump current values in spec schema
LookSpecScenes.cs.txtModal-free scene parking and reload
LookSpecList.cs.txtHierarchy listing
LookSpecTestRunner.cs.txtEditMode runner writing a text result
LookSpecPlayModeShot.cs.txtTrigger-file hook: apply, dump, list, test, play-mode capture
LookSpecHeadlessShot.cs.txtBatchmode capture of scenes whose content exists outside play mode
Tests/*EditMode tests: round trip, idempotence, fork, preset merge, error naming

Related: t1k-unity-editor-cli (Editor access), t1k-unity-rendering-urp, t1k-unity-rendering-light-baking.