t1k:unity:tof:base-rename-migrate
| Field | Value |
|---|---|
| Module | tof |
| Version | 3.46.8 |
| Effort | medium |
| Tools | — |
Keywords: base train, company name rename, D19, Legacy.generated, migrate game, mixed version, package ids kept, rename migrate, TheOne rename, train x-1, x-rename map
How to invoke
Section titled “How to invoke”/t1k:unity:tof:base-rename-migrateMigrate a game onto the base train (rename-migrate)
Section titled “Migrate a game onto the base train (rename-migrate)”Migrates one game from the old TheOne base to train x-1. The package ids stay (D19):
the skill changes manifest dependency VERSIONS and the game’s own code, never a key, a scope
or a package id. scripts/migrate.cjs decides the facts and applies the plan; this file is
the judgment around it.
When to use
Section titled “When to use”- A game still pins the old train, and the submodules have been bumped to the train SHAs.
- The user asks to migrate a game to the renamed base, or a checklist (
t1k-unity-tof-registrationsubmodule-update-migration.md) routes a company-name rename here.
Not for: a fresh project (use the registration skills), a game that is already migrated, or
published-identity strings (bundle id, companyName, store ids, Firebase ids stay, contract section 3).
- Plan first, always.
bun <skill>/scripts/migrate.cjs plan --project <unityRoot> --train x-1 --json. It writes nothing. Read the facts:state(oldmeans proceed), the manifest edits withfile:line, whetherpackages-lock.jsonis deleted, and the tool’s dry-run counts (collisionsmust be 0). - Refusals are answers, not obstacles. Exit codes: 2 = precondition (read the message: dirty tree, protected branch, train not released, submodules not bumped, remote-catalog game, tool too old, lint missing); 3 = mixed-version game (never force it; the whole train or none); 1 = a verify failure. Do not work around any of them by editing the script or the map.
- Collisions stop the run. Any collision is resolved in
x-token-map.jsonoverrides[]in the kit (a kit PR), never by a suffix in the game. - Apply once the plan reads right:
migrate.cjs apply --project <unityRoot> --train x-1. It makes ONE commit of the exact changed paths and printsgit revert <sha>. - Batch compile and test once (judgment, not in the script): one
t1k unity testthrough the headless gate (EditMode). A user-owned open Editor gets the CLI, never a second Editor (unity-headless-by-default.md). A compile failure after a green verify means a missed by-name reference: fix it in one batch, then re-verify. - Report: the commit sha, the revert command, the Jenkins define line the apply printed
(
PARAM_UNITY_SCRIPTING_DEFINE_SYMBOLS, set it on the game’s job), and what was NOT run.
Delta port after the first rename
Section titled “Delta port after the first rename”When old-train work lands after a game’s first rename port, port only that delta. Do not re-run
apply on the game: it is idempotent against its own map and silently skips the late code.
- Make two scratch roots
AandB, each with anAssets/dir (plusPackages/andProjectSettings/when the delta touches them).Ais the old-train tree the first port started from;Bis that tree plus the late delta. Export withgit archive <sha> Assets | tar -x -C <root>. - Run the SAME rename on both, one map per root, both outside the scratch tree:
bun <gups>/scripts/rename-company/rename-assemblies.cjs apply --naming token --project <root> --map <root>-map.json --token-map <gups>/references/x-token-map.json --legacy-skip --generic-text(<gups>= thet1k-unity-base-gups-il-obfuscationskill dir). Identical move and name counts on both runs are the sanity check; a mismatch means the delta uses a rule the first port lacked: stop. - Diff the renamed trees with root-relative paths:
cd <scratch-parent> && git diff --no-index -- A/Assets B/Assets > delta.patch(addPackages/ProjectSettingsthe same way). - In the game repo, on its renamed branch:
git apply --3way -p2 --directory=<unity-root> delta.patch. A conflict stops the port; resolve it with the owner, never by keeping both sides. - Drop hunks that reach a submodule mount folder, a published id (
com.the1studio.renameme, bundle ids), or an Addressablesm_Addressmount path before applying. The token mapkeep[]already holds these. - Confirm each new
.metakeeps its old-train GUID (the rename moves files with their.meta). Lint the staged paths:bun <gups>/scripts/lint-company-name.cjs --project <unityRoot> --token-map <gups>/references/x-token-map.json --mode enforce --staged(--projectis required), then commit the explicit paths and run the batch compile and test.
What the script checks (all facts, none judged here)
Section titled “What the script checks (all facts, none judged here)”- Clean tree, feature branch (never switches), train
releasedand for this id, manifest and submodule pointers all old or all on the train (exit 3 otherwise). - Remote catalog: Addressables with
m_BuildRemoteCatalog: 1and a token in address data is refused (D8). - Tool present and new enough (
--keep-package-ids, D19); toolapply/verifyexit 0. - Package-id snapshot unchanged (dependency keys,
scopedRegistries,Packages/*/package.jsonnames). - Every persisted key recorded in the map has its
Compat/Legacy.generated.cson disk. - Residual token in the game’s
.cs/.asmdefoutside the keep list and the Legacy file: exit 1 withfile:line. A literal old key belongs in the Legacy file, nowhere else. ProjectSettingsscriptingDefineSymbols(every platform line) is rewritten with the token engine (D7, no alias in source). A company define left in that setting after the rewrite is exit 1. The printedPARAM_UNITY_SCRIPTING_DEFINE_SYMBOLSline is the new value for the game’s Jenkins job.- Naming lint (
--mode enforce) passes.
Hard rules
Section titled “Hard rules”- Mixed versions are silent in Unity. Old and new trains share the same ids, so the package manager cannot tell them apart. The skill refuses; do not rely on Unity to flag it.
--legacy-skipis never implied. Without aLegacyKeyRegistrythe tool refuses (exit 2, D18). The flag exists for rehearsal builds only; it prints a warning and is recorded in the result.- Rollback is
git revert <sha>. It restores every byte, including the committed map. The tool’s ownrevertrefuses in permanent mode by design. - Unity 6 keys define lists by platform name (
Android:,Nintendo Switch:), not1:/9:. The migrate reads and rewrites both forms; an emptydefineValuesinplan --jsonon a real game is a bug, not a clean game. packages-lock.jsonis deleted, not edited. Unity regenerates it on the next resolve.- A failed verify leaves the tree uncommitted (exit 1). Inspect it; the script never discards.
- Re-running is a no-op on a migrated game (
already migrated, exit 0). A map recording a different train refuses (exit 2): one train per game. - Late old-train work is a delta, not a re-rename. Port it with the “Delta port” recipe. The scratch
--legacy-skiprun leaves noLegacy.generated.csin the diff, so check any persisted key the delta adds against its shim before merge.
Executed by
Section titled “Executed by”The plan and verify runs are mechanical: migrate.cjs plan and the exit-code read-back carry no judgment, so a cheap-tier
agent (t1k-tester) runs them and reports the exit code and the fact lines. Reading the plan, the apply decision and the
batch compile stay with the caller (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”).
Related
Section titled “Related”contract.md(kit plan, section 6 CLI surface, section 7 Legacy file) andphase-6-migrate-skill.mdin the plan folder of theTheOneFeatureProjectrepo.t1k-unity-base-gups-il-obfuscation(the rename tool, the token map, the naming lint) — the sibling this skill calls.t1k-unity-tof-registrationsubmodule-update-migration.md— bump the submodules first.t1k-unity-tof-addressables— address and catalog behaviour behind the remote-catalog refusal.