t1k:unity:blind-edit:assets
| Field | Value |
|---|---|
| Module | blind-edit |
| Version | 1.27.4 |
| Effort | medium |
| Tools | — |
Keywords: addressables orphan, blind edit, confirm round, edit meta without unity, edit prefab without unity, FormerlySerializedAs, guid, headless asset edit, k__BackingField, lost serialized values after package update, migrate renamed field, regenerate scenes, renamed serialized field, run menus
How to invoke
Section titled “How to invoke”/t1k:unity:blind-edit:assets[preflight|edit|batch|validate|confirm|run-menus|diff-classify|migrate-renamed-field|stats]Blind edit: edit -> validate -> ONE confirm -> adopt
Section titled “Blind edit: edit -> validate -> ONE confirm -> adopt”Edit Unity serialized files (prefab, scene, material, ScriptableObject, .meta) from Node with the Editor closed. A static validator proves the edit is self-consistent; ONE batchmode round proves Unity accepted it. Measured on VoxelColor: blind compile 0.3-4.8 s, validate 0.1-2.7 s, one confirm 80-110 s, versus at least 55 s for every editor launch. It replaces one launch per EDIT with one launch per BATCH; it does not remove Unity time.
CLI: bun <skill-dir>/scripts/blind-edit.cjs <preflight|edit|batch|validate|confirm|run-menus|diff-classify|migrate-renamed-field|stats|corpus> --project <root> ... (JSON on stdout; exit 0 ran, 1 refused or bad input, 2 bad args, 5 / 6 migrate-renamed-field only (below), 3 confirm broken, 4 confirm infra: Unity stalled and was killed, or exited by itself without writing a result (reason unity-compile-error / unity-exited-without-result, with the log tail; the run stays unconfirmed, fix the cause and retry)). Schemas: references/contract.md. Ids and fixtures: references/hazards.md. Lessons: references/incident-history.md.
Engine-neutral core. The run journal, the atomic apply with byte-exact rollback, symlink-safe confinement, the refusal codes, the lesson-marker builder and the edit sequencing are NOT in this skill: they are skill t1k-gamedev-blindedit-blind-edit of theonekit-gamedev (module blindedit, a dependency of this module), reached through scripts/lib/core.cjs and bound to Unity by the slot scripts/blind-edit-slot.cjs (roots, Library/T1K/blind-edit, <name>.<runId>.tmp, the .meta sidecar, the YAML parser, the validator rule ids, the batchmode confirm). The neutral contract and what a slot is: the contract and slot-contract reference files of that skill; this kit declares it as the x-blind-edit capability of gamedev-adapter.json (find it with bun .claude/scripts/gamedev-adapter.cjs resolve --capability x-blind-edit). If blind-edit.cjs fails with “blind-edit core not found”, run t1k modules update.
Mindset: blind first, finish everything, ONE confirm
Section titled “Mindset: blind first, finish everything, ONE confirm”Unity is the expensive step, so the work is shaped around it (rules/ai-velocity-batch-compile-unity.md):
- Write the WHOLE deliverable blind first: every file, every lane, every foreseeable fix. Do not confirm between files.
batch --manifestapplies every valid op in one call and reportsapplied[],refused[]andfails[]together; it never stops at the first refusal.- Read the whole failure set (
failSummary: by file, a hint per rule) and fix it in ONE batch; re-runbatchfor the refused ops. - Only then ONE
confirm; collect-all again, fix in one batch, confirm once more (at most 2 Unity rounds per deliverable). - Step by step is right only for a NEW shape or an unknown API: one smoke on N=1, then the batch.
Compile the C# offline before any Unity round
Section titled “Compile the C# offline before any Unity round”A fan-out that wrote .cs files is gated by an offline Roslyn compile of Unity’s own Bee response files (Library/Bee/artifacts/*/*.rsp), per assembly group in dependency order: errors in seconds, no Editor lock, no queue (one NUnit Does.Contains typo otherwise costs a whole queued Unity pass). Recipe, fresh-deps mode, red-probe check and what it does not cover (platform #if, runtime, asset wiring, IL2CPP/Burst): references/offline-compile-gate.md. Run hazards (empty submodule dirs that must be linked and unlinked around git, csc exit 137 as an OOM kill, reading file:line lines not counts, load-dependent timing, disk space): the “Run hazards” section of the same file.
Blind or editor?
Section titled “Blind or editor?”- Blind is the default for batched edits (N >= 2 edits, or any iterative loop) and whenever no Unity Editor is running. Reason: iteration costs Node time (compile 0.25-5.2 s, validate 0.14-2.7 s); Unity runs once per batch (60 changes confirmed in 81.9 s); the validator and read-back catch the wrong-field errors the live arm made in both A/B runs.
- The editor compiler (
t1k-unity-editor-look-spec) is the fallback for: a single edit while a warm Editor is already open (a livet1k unitycall is ~1 s, a blind round is 82-96 s); anyneeds-editorrefusal (baked lighting / SH ambient / reflection probes, GameObject add or remove, an importer without a template, an unlistedserializedVersion); a cold or unmeasured project, until a warm Library exists. - Routing table (blind-edit vs the live Editor path, one place):
t1k-unity-editor-cli. - Limit, stated openly: the editor compiler can also batch specs into one launch, so “faster than a batched editor apply” is NOT claimed. The claim is “no launch while iterating, one launch to confirm”.
Review a regenerated asset diff (diff-classify)
Section titled “Review a regenerated asset diff (diff-classify)”diff-classify --project P [--base REF] [--table] [paths...] sorts each changed .unity / .prefab / .asset against a git base (default HEAD, working tree included) before anyone reads a diff: fileid-churn-only (only local fileIDs were renumbered or documents reordered; proved by a verified bijection, so it is safe to skip), semantic (a per-object list: GameObject path, component class, property path, old -> new), schema-only (only fields added/removed or a serializedVersion bump, no existing value changed: a script gaining fields or an engine re-serialize; fields still listed, schema rows trail the real ones in a semantic file), volatile-only (only fields matching blindEdit.diffClassify.volatileFields / --volatile changed; no built-in patterns), format-change (binary <-> text; text -> binary is flagged), a non-default field removal beside an added field stays real with possibleRename (a rename without FormerlySerializedAs loses data; the row carries a remedy: migrate-renamed-field), binary (binary on both sides), added, deleted (both win over binary). Fields that only moved position and a component row already reported as an added/removed object are dropped; the kit’s own .claude/ is ignored unless named; identical change sets share a groupId and print once in --table. Read the semantic rows first, then skim schema-only. It never guesses: a remap that is not a consistent bijection is semantic; exit 255 means it could not judge. Detail: references/contract.md “diff-classify”.
Migrate a renamed serialized field (migrate-renamed-field)
Section titled “Migrate a renamed serialized field (migrate-renamed-field)”When: a package or C# type renamed a serialized field WITHOUT [FormerlySerializedAs]; values silently reset to defaults after a package bump (diff-classify possibleRename, confirm lostReferences[]). Preferred fix is upstream: add [FormerlySerializedAs("<old>")] to the renamed field. This command is the data-side fix when the type cannot be changed.
migrate-renamed-field --project P (--preset NAME | --map F.json | --rename old=new ...) [--files a,b] [--write] rewrites mapping keys and propertyPath: segments only. Dry-run by default; --write is a journalled edit (unconfirmed, then validate --run and ONE confirm). A name-normalized equality proof runs before any write. Scope is data (parentKey, listItem, requireAll, onlyKeys, script), so a look-alike class with its own Key auto-property is reported out-of-scope, never renamed. Exit 0 clean/noop, 5 ambiguous/unmatched, 6 proof-failed. Preset theone-extensions-6 (<Key>k__BackingField -> item1 …). Run it on PRE-resave files. Schema, presets, report, exit codes: references/contract.md “migrate-renamed-field”; incident: references/incident-history.md.
Preflight: binary assets
Section titled “Preflight: binary assets”preflight WARNS binary-asset for a .unity / .prefab / .asset without the %YAML header (target files and the whole project; binaryAssets has the count, warnings[].remedy the fix) and serialization-mode-not-text when ProjectSettings/EditorSettings.asset m_SerializationMode is not 2. edit on a binary file fails with the same remedy: set Force Text, re-save the asset in the Editor, never Reimport All.
Look spec (palette, background, ambient, fog, light, UI tint)
Section titled “Look spec (palette, background, ambient, fog, light, UI tint)”The SAME look-spec.json and look-spec.map.json the editor skill reads (format: references/map-format.md, a mirror). edit --shape look-spec --spec S --map M --dry-run prints the op list and the footprint and writes nothing; without --dry-run it writes, journals unconfirmed, and a second identical run reports noop. readback --map M [--spec S] prints the spec JSON the project holds now. A material that anything outside the entry’s owners also references is forked to <name>_LookSpec.mat (the shared-material trap); a map entry may declare authoritativeWriters so a C# assignment to the same member shows as a shadowed-field warning (references/shadowed-fields.md).
Level B: prove it renders (opt-in)
Section titled “Level B: prove it renders (opt-in)”confirm --run <id> --unity <bin> --render --probes probes.json adds one step after the Level A round: under xvfb-run the Editor renders the camera of ONE scene in edit mode (no play mode, no domain reload) and samples the declared pixels. probes.json is {scene, width?, height?, points: [{x, y, rgb, tol?}]} (origin top-left; rgb is #rrggbb or [r,g,b]; tol per channel, default 8); it is a separate file so the spec JSON still loads in the editor compiler. A probe outside its tolerance, or no render at all, makes the confirm broken. Default stays Level A. A blind change to something the player sees owes this check: Level A proves the bytes, not the picture. Until a render has run, the PR says render owed and names the probe file that will prove it; verified is never written for a visual claim that only Level A has seen. Limits: it proves the scene’s serialized look, not runtime code that overrides it; a camera that clears to a Skybox shows no background colour (the golden task’s first Level B run caught exactly that: task/render-record.json); warm Library only; measured wall in the same record.
After a Unity ended (killed by this CLI: stall watchdog, --timeout-s, a reaped leftover; or dead on its own: a compile error, a crash) the CLI removes Temp/UnityLockfile itself, only when no live process names this project and nothing holds the file open. An Editor the user opened keeps its lock.
Run Editor menus in one launch (run-menus)
Section titled “Run Editor menus in one launch (run-menus)”run-menus --project P --unity BIN --menu "Tools/A/Setup Scene" --menu ... [--menus-file f] [--memory-max 16G] runs every menu in ONE batchmode launch: it installs a runner, uses confirm’s launch discipline (reap, lockfile, watchdog), removes the runner, and prints a JSON report (per-menu OK|NOMENU|FAIL, scene, duration, compileErrors, changedFiles from git status before/after, addressables). Exit 0 ok, 3 failed, 4 infra. Never hand-write a temp menu-looping editor script. After a regen it also runs addressables-orphan (below). Details: references/run-menus.md.
Audit: an Addressables entry lost in a regen
Section titled “Audit: an Addressables entry lost in a regen”validate (and every run-menus) FAILS addressables-orphan when an asset that was in an Addressables group before (git HEAD, or the run’s own snapshot) is in none now and the run touched it: the delete-then-recreate of a prefab (AssetDatabase.DeleteAsset then SaveAsPrefabAsset mints a new guid and drops the entry) or a changed scene’s AssetReference that now dangles. Re-register and re-point, and edit prefabs in place. --no-addressables-check skips it. No Unity needed.
Batch: a whole manifest in one call
Section titled “Batch: a whole manifest in one call”batch --project P --manifest ops.json [--dry-run]: ONE manifest of ops across many files and shapes; each valid op is applied (one journalled run), each refused op is listed with its code, then validate runs once. Output {applied[], refused[], fails[], failSummary, runId}; exit 0 only when nothing was refused or failed, else 1 (the applied ops stay written, unconfirmed). Detail, and why confirm over several runs is not built: references/contract.md, “batch and the whole failure set”.
The contract (MUST)
Section titled “The contract (MUST)”preflightthe target files. Refuse when a live Editor holds the project (Temp/UnityLockfile): close it first, never kill it.editwith an ops file. The run is journalledunconfirmed. A refused op leaves the tree untouched.validate --run <id>. Fix everyfails[]entry;info[](problems that were already there) is reported, never rewritten.confirm --run <id> --unity <bin>: ONE batchmode round (import, resave probe, read-back, missing-ref scan, minted-GUID check). Verdictok,canonicalized(Unity’s bytes adopted) orbroken(nothing adopted).- Never report the edit done while the journal state is
unconfirmedorbroken. Paste everylessonLines[]entry the confirm prints into your reply (the collector reads assistant text only).
The loop: a miss is not fixed until it ships three things
Section titled “The loop: a miss is not fixed until it ships three things”A confirm that prints lessonLines[] also prints a PASTE VERBATIM block (pasteVerbatim): paste it into your reply, unedited, so the core collector queues it (kit="theonekit-unity" skill="t1k-unity-blind-edit-assets" fragment="scripts/lib/<file>#<rule>" reason="blind-miss class=<class> shape=<shape> id=miss:<id>"). Every miss is also in Library/T1K/blind-edit/misses.jsonl, and stats counts it, pasted or not. The fix ships together: a validator/serializer rule id (scripts/lib/rules.cjs), a fixture corpus/misses/<id>/ and a gotcha ## miss:<id> in references/incident-history.md; tests/miss-identity.test.cjs keeps the three equal and replays each miss.
Practice corpus: corpus --tier 1 (CI, pure node: ops applied to shapes/<shape>/task/before/ must give expected-after/ byte for byte, the footprint, a clean validate, and the independent checks of verify.json) and corpus --tier 2 (ONE batchmode Unity over every task, nightly on the workstation by assets/systemd/ units, installed only by corpus --install-timer --apply). A shape is a corpus TASK only when its task/ carries verify.json (its independent checks); a pack without one (look-spec, new-asset, asset-move, set-field, swap-ref) is judged by its own suite and listed under shapesWithoutTask. To add a task: shapes/<shape>/{op.json,shape.md,task/{before,ops.json,expected-after,verify.json}} (and registerRunner in lib/corpus.cjs for a spec.json task), then corpus --reseal; the pack hash and task/confirm-record.json are lib/shape-pack.cjs’s, shared by every shape. stats also prints the speed ratio per shape and the tier-2 last run.
What it will not do (refuses with a hazard id)
Section titled “What it will not do (refuses with a hazard id)”A stripped document (Unity-managed: never edited, created or removed), a value inside a multi-line flow map, anything in a references: / rid: block, a line over 4096 chars, a binary file behind a text extension, a bare leaf path (paths are rooted and indent-anchored: Material.m_SavedProperties.m_Colors[3]._BaseColor.r); a key that holds spaces is double-quoted: Camera."orthographic size", Camera."field of view", inserting a m_Modifications entry anywhere but the END (set-field appends there), a swap that needs a different layout than the old reference (rewrap-needed), a swap whose target class or script differs from the slot’s (type-mismatch) or cannot be established (type-unknown), a swap of a prefab instance’s identity (m_SourcePrefab, an override target, a stripped document), a light edit in a scene with baked lighting (needs-editor), a new asset whose importer has no .meta template (needs-editor). For those use the Editor (t1k-unity-editor-cli).
Shapes (edit --shape <name>)
Section titled “Shapes (edit --shape <name>)”set-field (one field of one object, a variant’s override value appended at the END when absent), swap-ref (retarget {fileID, guid, type}, type- and resolution-checked, --scope file|dir), new-asset (from a copy or authored YAML), asset-move (the .meta travels), add-component (a built-in, script-less component, AudioListener first, on an existing GameObject of a scene or prefab: --file F --object <GameObject name|fileID> --class AudioListener; refuses a GameObject inside a prefab instance, a class with no template in assets/component-templates/, and a second [DisallowMultipleComponent]). Each is a data pack under shapes/<name>/ with a real-Unity confirm record: when to use it, what it refuses and which hazard id, in its shape.md; the index and the Unity binding in references/shapes-index.md. --dry-run prints the footprint and writes nothing.
Contributing a shape. stats prints SHAPE-CANDIDATE lines when one hand-written edit (no --shape) recurs 3 times in 30 days: paste them into your reply. The route is a data pack, never a skill: shape new <name>, one real confirm round, fill the record, shape attest, shape publish, then /t1k:sync-back: it carries the pack; the snapshot trees travel with it on installs at or above t1k-kit-feedback 1.46.2 (core#3691), and on older installs shape publish lists them for a manual add (references/contract.md, “Contributing a shape”).
Audit: a silent scene
Section titled “Audit: a silent scene”validate (any mode; --all is the audit) WARNS per .unity file, never fails: audio-listener-missing (an enabled Camera tagged MainCamera and no usable AudioListener: every SFX is silent) and audio-listener-multiple (more than one enabled AudioListener). A listener inside a prefab instance is invisible blind, so the message says when the scene holds instances. The fix for a missing one is the add-component shape. Relay these warnings in the reply; a review that only reads the files it edits cannot see a component that is not there (references/incident-history.md, “add-component lessons”).
New assets and GUIDs
Section titled “New assets and GUIDs”new-asset / new-folder mint the .meta GUID (md5-derived, collision-checked) and write the .meta from assets/meta-templates/; the confirm round proves the GUID survived import. Moves carry the .meta and keep the GUID. A committed asset without its .meta is a validate failure.
A .cs file written by hand needs a .meta that Unity would have written: fileFormatVersion: 2, then guid:, and no trailing newline. A hand-rolled file with extra keys or a blank last line is rewritten on the next import and shows up as churn in an unrelated diff. Keep the guid when you rewrite one.
No template for the importer (a new PNG, WAV, font, any non-.cs asset): copy a sibling .meta
Section titled “No template for the importer (a new PNG, WAV, font, any non-.cs asset): copy a sibling .meta”assets/meta-templates/ holds only asset, cs, folder, mat, prefab and unity. A new texture (TextureImporter), audio clip (AudioImporter) or font has no template, and new-asset would fall back to the generic asset.meta, which is the wrong importer. Do NOT ship the file without its .meta (Unity then mints one on import, the GUID drifts between machines and every reference to it breaks), and do NOT stall because hand-writing one feels unsafe. The documented path:
- Pick a committed same-kind sibling (another
.pngin the same folder, with the same sprite/texture settings you want). - Copy its
<sibling>.metato<new-file>.meta. - Replace ONLY the
guid:line with a fresh 32-hex GUID (new-asset’s md5-derived mint, oruuidgen | tr -d -), collision-checked againstgrep -r "guid: <new>" --include=*.meta. - Reset any per-file state the sibling carried (a sprite sheet’s
internalIDToNameTable/sprites:entries,spriteID,externalObjects); a plain single-image sibling has none. - The confirm round proves Unity kept the GUID and the import settings.
Missing template = a gap in this skill: add assets/meta-templates/<ext>.meta.txt for the importer when you can read one from a real Unity-written .meta.
Confirm run: baseline drift and lost references
Section titled “Confirm run: baseline drift and lost references”A scene saved by an older Unity (or before a C# field was renamed) is rewritten by Unity on ANY resave. The confirm therefore resaves a CONTROL (the pre-edit bytes) in the same round: a resave hunk the control shows too, outside the edit’s own lines, is preexisting-drift (counted, ONE warning “regenerate the scene or adopt Unity’s resave in its own commit”), never a miss, never broken; that file keeps OUR minimal bytes (keptOurs). Only drift absent from the control is a miss. A removed non-null field: {fileID: N} with no moved twin is a lostReferences[] warning (a renamed/removed C# field silently dropped the wiring): relay it, it is a real game bug (a rename: see migrate-renamed-field). --no-baseline skips the control (memory-bound hosts). After a kit update re-copy the Editor template, the control needs its new members. A stale Temp/UnityLockfile (Unity SIGKILLed by the OOM killer) is cleared by the next preflight / confirm. Contract: references/contract.md, “baseline control”.
Confirm run
Section titled “Confirm run”assets/templates/BlindEditConfirm.cs.txt is the Editor method T1K.BlindEdit.Confirm.Run. On first use copy it to Assets/Editor/T1K/BlindEdit/BlindEditConfirm.cs (drop the .txt; the suffix only keeps the kit repo from compiling it). The template must compile on the project’s Editor version (it branches on UNITY_6000_5_OR_NEWER); a compile error there makes every round broken with no confirm-result.json, so after a kit update re-copy it and read the compile log first (references/incident-history.md). Launch is admitted through .claude/scripts/unity-batch-gate.sh; a watchdog reaps a Unity that hangs after finishing (reaped: true). Never Reimport All, never -runTests with -quit, never -nographics for a render claim.
Related
Section titled “Related”t1k-unity-base-static-ref-check (GUID resolution, called by validate), t1k-unity-editor-look-spec (editor-side compiler, kept as the fallback), t1k-unity-editor-cli (Editor access). No-Editor verification traps: references/verification-and-strip-lessons.md.
Executed by
Section titled “Executed by”The CLI steps are mechanical and emit JSON; only choosing the ops and judging a failure stay on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Step | Agent |
|---|---|
Run preflight / validate and read fails[] and info[] off the JSON | t1k-fact-fetcher |
Summarize stats per shape (runs, median blind wall, ratio) | t1k-metrics-reporter |
Decide the ops, fix a validate failure, judge a canonicalized or broken confirm | reasoning tier: a write to the user’s assets, not a label |