t1k:unity:base:hub-launch
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
Keywords: add project from disk, editor version, launch editor, open project, projects-v1.json, unity hub, unityhub cli
How to invoke
Section titled “How to invoke”/t1k:unity:base:hub-launchUnity Hub — Launch & Register a Project from the CLI
Section titled “Unity Hub — Launch & Register a Project from the CLI”Opening a project is a direct editor launch. Registering it in Hub is a separate, unsupported-by-CLI step. Treat them as two problems; conflating them is why this looks harder than it is.
The one-line answer
Section titled “The one-line answer”"$HOME/Unity/Hub/Editor/<VERSION>/Editor/Unity" -projectPath "/abs/path/to/UnityProjectRoot"-projectPath takes the Unity project root (the folder holding Assets/, Packages/, ProjectSettings/) — NOT the git repo root. In TheOneStudio template projects these differ: the repo root holds Unity<GameName>/, and that subfolder is the project root.
Pre-flight — verify BEFORE launching
Section titled “Pre-flight — verify BEFORE launching”Run all four. Skipping the version check is the common failure: launching with the wrong editor silently triggers an API-upgrade prompt or a full reimport.
| Check | Command | Why |
|---|---|---|
| Required version | cat <proj>/ProjectSettings/ProjectVersion.txt | Source of truth. Gives version and changeset. |
| Installed versions | unityhub --headless editors -i | Confirms the required version exists on disk. |
| Submodules present | git submodule status — a leading - means uninitialized | Unity compiles against submodule code; missing ones produce hundreds of CS0246 errors that look like real breakage. |
Library/ present | du -sh <proj>/Library | Present → incremental import. Absent → full import, potentially 30+ min. Set expectations before launching. |
unityhub --headless editors -i prints installed editors as <version> installed at <path>. Build that path directly rather than guessing; the default root is ~/Unity/Hub/Editor/, but unityhub --headless install-path -g returns the configured one.
Launching
Section titled “Launching”Launch in the background — the editor runs for the whole session and a foreground call blocks until the user quits it.
Startup order in ~/.config/unity3d/Editor.log (Linux — note there is no Logs/Editor.log inside the project on Linux Unity 6):
[Licensing::Client] Successfully updated license- package resolution +
will not be compiled because it exists outside the Assets folder(benign PackageCache noise, not an error) [MODES] Loading mode Default (0) for mode-current-id-<ProjectName>— confirms the correct project[LAYOUT] About to load UserSettings/Layouts/default-6000.dwlt— final stage; window appears next
Monitor with a filter covering both outcomes — a success-only grep stays silent through a crash and silence is indistinguishable from “still loading”:
tail -f ~/.config/unity3d/Editor.log | grep -E --line-buffered \ "Refresh completed|\[LAYOUT\] Loaded|error CS[0-9]+|Fatal|Aborted|Segmentation|licens"Registering in Hub — the CLI cannot do this
Section titled “Registering in Hub — the CLI cannot do this”unityhub --headless help exposes exactly five commands: editors, install-path, install, install-modules, help. There is no add-project. editors --add <path> adds an editor, not a project — do not reach for it here.
Two things follow, and both are counter-intuitive:
- Launching the editor directly does NOT register the project in Hub. Verified: the project ran under the correct editor while Hub’s list stayed unchanged. Registration flows Hub → editor, never editor → Hub. Opening a project therefore never implies it is listed — check, or say plainly that it is not.
- The project list is a plain JSON file at
~/.config/unityhub/projects-v1.json:
{ "schema_version": "v1", "data": { "/abs/path/to/UnityProjectRoot": { "title": "UnityProjectRoot", "lastModified": 1755271234567, "isCustomEditor": false, "path": "/abs/path/to/UnityProjectRoot", "containingFolderPath": "/abs/path/to", "version": "<m_EditorVersion from ProjectVersion.txt>", "architecture": "x86_64", "changeset": "1c726e1fb402", "isFavorite": false } }}version and changeset both come from ProjectVersion.txt — a mismatched changeset makes Hub offer to install an editor that is already present. Which editor a NEW project should use is unityEditor.supported in .claude/t1k-config-unity.json; bun .claude/scripts/detect-unity-editor-version.cjs <project-root> prints an advisory when a project differs.
[!WARNING] Do NOT edit this file while Hub is running — the edit will be lost immediately, not merely on Hub’s next exit. Hub owns the list in memory and rewrites the file on its own schedule; it does not re-read it after startup. The write appears to succeed and survives a spot-check minutes later, which makes this look like it worked right up until the user reports an empty list. Measured incident:
references/hub-project-list-persistence-incident.md.
When Hub is running — the only reliable route. Tell the user to click Add ⌄ → Add project from disk in the Hub GUI and select the project root. One click, no state-file risk. There is no CLI equivalent; do not spend turns looking for one.
When Hub is NOT running, writing the JSON entry works and Hub picks it up at next launch. Verify Hub is actually stopped first (pgrep -f "unityhub-bin" | grep -v "type=" — empty), and never stop it yourself.
Point the user at the project root, not the repo root. Hub rejects a folder with no Assets/. In TheOneStudio template projects the repo root (VoxelColor/) and the project root (VoxelColor/UnityVoxelColor/) differ, and the repo root is the intuitive wrong answer.
Constraints
Section titled “Constraints”- Never terminate Unity Hub or the Unity Editor to force a state refresh —
kill,pkill -f Unity,pkill -f UnityHub,File/Quit.rules/unity-forbidden-operations.mdhard-bans this and aunity-process-guard.cjshook blocks it. Unsaved scenes, prefab edits, and console history are unrecoverable. Ask the user to close it. - Verify process identity before concluding Hub restarted.
pgrep -f unityhub-bin | head -1may return a short-lived renderer child, making a healthy Hub look like it was replaced. Confirm withps -p <pid> -o lstart,cmdand filter out--type=children. - A running Hub is not a blocker for launching — the editor starts fine alongside it.
Hard rules
Section titled “Hard rules”Curl error 35: Recv failureduring startup is benign — a licensing/analytics call, not a project error.Script '...' will not be compiled because it exists outside the Assets folderforLibrary/PackageCache/**asmdefs is normal package-resolution noise.- An editor-version bump forces a partial reimport even with
Library/intact. After changingProjectVersion.txt, expect a long first open and do not read the delay as a hang. - Hub’s own config lives in two directories with different casing:
~/.config/unityhub/(Electron state, project list) and~/.config/UnityHub/(a near-emptySettings). The project list is in the lowercase one. - Paths with spaces are common in this org’s layout (
~/Unity Projects/...). Quote every path; an unquoted-projectPathsilently opens the wrong folder or the Hub project picker.
Related
Section titled “Related”rules/unity-forbidden-operations.md— never kill/quit the editor; neverAssets/Reimport Allrules/ai-velocity-batch-compile-unity.md— compile verification, console--sincereads, DLL-mtime pollingt1k:unity:editor:cli— driving an already-open editor witht1k unity <verb>references/hub-project-list-persistence-incident.md— measured evidence for the persistence-loss claim