Skip to content

t1k:unity:tof:base-rename-migrate

FieldValue
Moduletof
Version3.46.8
Effortmedium
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

/t1k:unity:tof:base-rename-migrate

Migrate 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.

  • 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-registration submodule-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).

  1. Plan first, always. bun <skill>/scripts/migrate.cjs plan --project <unityRoot> --train x-1 --json. It writes nothing. Read the facts: state (old means proceed), the manifest edits with file:line, whether packages-lock.json is deleted, and the tool’s dry-run counts (collisions must be 0).
  2. 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.
  3. Collisions stop the run. Any collision is resolved in x-token-map.json overrides[] in the kit (a kit PR), never by a suffix in the game.
  4. Apply once the plan reads right: migrate.cjs apply --project <unityRoot> --train x-1. It makes ONE commit of the exact changed paths and prints git revert <sha>.
  5. Batch compile and test once (judgment, not in the script): one t1k unity test through 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.
  6. 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.

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.

  1. Make two scratch roots A and B, each with an Assets/ dir (plus Packages/ and ProjectSettings/ when the delta touches them). A is the old-train tree the first port started from; B is that tree plus the late delta. Export with git archive <sha> Assets | tar -x -C <root>.
  2. 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> = the t1k-unity-base-gups-il-obfuscation skill 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.
  3. Diff the renamed trees with root-relative paths: cd <scratch-parent> && git diff --no-index -- A/Assets B/Assets > delta.patch (add Packages/ProjectSettings the same way).
  4. 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.
  5. Drop hunks that reach a submodule mount folder, a published id (com.the1studio.renameme, bundle ids), or an Addressables m_Address mount path before applying. The token map keep[] already holds these.
  6. Confirm each new .meta keeps 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 (--project is 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 released and for this id, manifest and submodule pointers all old or all on the train (exit 3 otherwise).
  • Remote catalog: Addressables with m_BuildRemoteCatalog: 1 and a token in address data is refused (D8).
  • Tool present and new enough (--keep-package-ids, D19); tool apply/verify exit 0.
  • Package-id snapshot unchanged (dependency keys, scopedRegistries, Packages/*/package.json names).
  • Every persisted key recorded in the map has its Compat/Legacy.generated.cs on disk.
  • Residual token in the game’s .cs/.asmdef outside the keep list and the Legacy file: exit 1 with file:line. A literal old key belongs in the Legacy file, nowhere else.
  • ProjectSettings scriptingDefineSymbols (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 printed PARAM_UNITY_SCRIPTING_DEFINE_SYMBOLS line is the new value for the game’s Jenkins job.
  • Naming lint (--mode enforce) passes.
  • 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-skip is never implied. Without a LegacyKeyRegistry the 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 own revert refuses in permanent mode by design.
  • Unity 6 keys define lists by platform name (Android:, Nintendo Switch:), not 1:/9:. The migrate reads and rewrites both forms; an empty defineValues in plan --json on a real game is a bug, not a clean game.
  • packages-lock.json is 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-skip run leaves no Legacy.generated.cs in the diff, so check any persisted key the delta adds against its shim before merge.

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”).

  • contract.md (kit plan, section 6 CLI surface, section 7 Legacy file) and phase-6-migrate-skill.md in the plan folder of the TheOneFeatureProject repo.
  • t1k-unity-base-gups-il-obfuscation (the rename tool, the token map, the naming lint) — the sibling this skill calls.
  • t1k-unity-tof-registration submodule-update-migration.md — bump the submodules first.
  • t1k-unity-tof-addressables — address and catalog behaviour behind the remote-catalog refusal.