t1k:unity:editor:look-spec
| Field | Value |
|---|---|
| Module | editor |
| Version | 3.50.7 |
| Effort | medium |
| Tools | — |
Keywords: code-driven look, look spec, look-spec, palette spec, visual spec
How to invoke
Section titled “How to invoke”/t1k:unity:editor:look-spec[setup|apply|dump|list|capture]Look Spec: code-driven visual setup (POC)
Section titled “Look Spec: code-driven visual setup (POC)”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.
When to use
Section titled “When to use”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.
Setup (once per project)
Section titled “Setup (once per project)”-
Needs Newtonsoft Json (
com.unity.nuget.newtonsoft-json) and the Test Framework. Assets underAssets/Editor/only. -
Copy
assets/templates/intoAssets/Editor/LookSpec/, dropping the.txtsuffix from each*.cs.txtand*.asmdef.txt;Tests/goes toAssets/Editor/LookSpec/Tests/. The.txtsuffix only keeps the kit repo from treating templates as live C#.Terminal window T=<skill-dir>/assets/templates; D=Assets/Editor/LookSpecmkdir -p $D/Tests && for f in $T/*.asmdef.txt $T/*.cs.txt; do cp "$f" "$D/$(basename "${f%.txt}")"; donefor f in $T/Tests/*.asmdef.txt $T/Tests/*.cs.txt; do cp "$f" "$D/Tests/$(basename "${f%.txt}")"; done -
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 thelistcommand, never by guessing. -
Start
{ "preset": "default" }inlook-spec.json, set envLOOKSPEC_TRIGGERand launch the warm editor, thendumponce and keep the result asbaseline.json(restores the original look). -
Run the EditMode tests (
{"test":"LookSpec.Tests"}) and require 0 failures before the first apply.
Apply, read back, list
Section titled “Apply, read back, list”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.
Shared-material fork (MUST)
Section titled “Shared-material fork (MUST)”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
materialColormap entry MUST list itsowners. An emptyownersdisables the check. - On a write, the compiler scans
scanfolders for outside referencers. If found it copies the material to<name>_LookSpec.mat, repoints the owners at the copy, recolours only the copy, and logsLOOKSPEC_SHARED_FORK. - Do not “fix” the fork by editing the original. Verify the outside referencer still shows its original colour (
SharedMaterial_IsForked_OriginalStaysUntouchedtest; capture the other prefab).
Golden or screenshot verification
Section titled “Golden or screenshot verification”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 rule carve-out
Section titled “Prefab-only rule carve-out”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.
Hard rules
Section titled “Hard rules”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
roota component type that appears once the board is built. - Scripting defines that exist only for one build target: launch the editor with the right
-buildTargetor the game code does not compile. - Scene-changed-on-disk and Save-As modals freeze the editor: use
LookSpecScenesparking; never callNewSceneorSaveOpenScenes. - Never terminate or restart the Editor on your own initiative (
unity-forbidden-operations).
Template map (assets/templates/)
Section titled “Template map (assets/templates/)”| File | Role |
|---|---|
LookSpecCompiler.cs.txt | Resolve preset, validate, apply; ApplyFromCommandLine for batch |
LookSpecSession.cs.txt | Open files, read/write properties, shared-material fork |
LookSpecMap.cs.txt | Map file model and key matching |
LookSpecReadback.cs.txt | Dump current values in spec schema |
LookSpecScenes.cs.txt | Modal-free scene parking and reload |
LookSpecList.cs.txt | Hierarchy listing |
LookSpecTestRunner.cs.txt | EditMode runner writing a text result |
LookSpecPlayModeShot.cs.txt | Trigger-file hook: apply, dump, list, test, play-mode capture |
LookSpecHeadlessShot.cs.txt | Batchmode 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.