Skip to content

t1k:unity:base:template-bootstrap

FieldValue
Modulebase
Version5.116.6
Efforthigh
Tools—

Keywords: Addressables groups, BaseUnityTemplate, bootstrap, bundle id, define symbols, IL2CPP stripping, init project, Jenkins job, keystore, link.xml, meta GUID, new project, PackageNameUpdate, Preserve, puzzle template, PuzzleTemplate, scoped registry, setup-project, SetupProject.bat, SetupProject.sh, submodules, template bootstrap, template checklist, upm.the1studio.org, WebGL defines

/t1k:unity:base:template-bootstrap

Bootstrap a New Game From a Studio Template

Section titled “Bootstrap a New Game From a Studio Template”

Standing up a new title from a The1Studio Unity template, from clone to a build that boots on device. Scope is the bootstrap only. Once the project runs, the per-area skills own their areas: t1k:unity:base:boot-flow (scene scopes and handoff), t1k:unity:base:project-structure (folder layout), t1k:unity:base:upm-auth (registry credentials), t1k:unity:base:addressables, t1k:unity:base:code-conventions. Cite them; do not restate them.

Step 0 — Detect the template, then read its reference

Section titled “Step 0 — Detect the template, then read its reference”

Look at the repo root for the template’s setup script:

Root fileTemplateRead
SetupProject.sh and/or SetupProject.batBaseUnityTemplatereferences/base-unity-template.md
setup-project.sh (lowercase, kebab)PuzzleTemplatereferences/puzzle-template.md
neither (a script that deletes itself is already gone)a bootstrapped titleread UnityXxx/; detect in order. (1) Count .gitmodules entries: 3 = Base, references/base-unity-template.md. (2) 7 = Puzzle family: PuzzleTemplate and SgameTemplate list the identical 7 The1Studio/* paths, so URL/name cannot separate them. Read the branch = line of the Assets/TheOneFeature.PuzzleUI submodule in .gitmodules: branch = master-sexy-theme = SgameTemplate (sexygame module t1k-unity-sexygame-template-setup/references/pins.md row: “Assets/TheOneFeature.PuzzleUI … master-sexy-theme”); no branch = key = PuzzleTemplate (references/puzzle-template.md: “No branch = key in .gitmodules”).

Editor: a new title uses unityEditor.supported from .claude/t1k-config-unity.json (Hub install, Jenkins tool name unityEditor.jenkinsToolName); if the template pins another editor, bun .claude/scripts/detect-unity-editor-version.cjs <project-root> names both, and moving it is its own branch and PR. Do not copy the number into the project notes.

Read the matching reference BEFORE step 1. Steps 1, 2, 3 and 6 are template-specific and live ONLY in the reference; steps 4, 4b, 5, 7 to 13 are generic and stay here, with the template-specific figures in the reference. Do not mix facts across templates: a submodule list, define set or composition root that is right for one is wrong for the other.

Provenance — read before trusting a step

Section titled “Provenance — read before trusting a step”

Every step is marked:

  • [VERIFIED] — read off a shipped project’s tree or a template repo, or off a merged PR, cited inline in the reference.
  • [OPEN] — a real question nobody has settled. It is written as a question on purpose. Do not let a session answer it by guessing; answer it from the template repo and then update this skill.

Each step says what to do and what proves it worked. Do not move on from a step whose proof fails.

1. Repo, remote, template setup script — template-specific

Section titled “1. Repo, remote, template setup script — template-specific”

Clone the template, point origin at the new private repo (SSH, never HTTPS), then run the template’s setup script once from the repo root, as its reference says. Whether the script deletes itself, which submodules it re-adds, and which files it rewrites differ per template: read the reference, never assume.

Pre-condition: the imported template tree, submodule gitlinks included, is COMMITTED before the setup script runs (see the reference).

Proof: Unity<Title>/ exists, the template project folder name is gone, git remote -v is git@github.com:.

The project does NOT compile before submodules are initialised: the composition root references types from them. The list, and whether they pin commits or track a branch, is in the reference. Never edit submodule files in the game repo (rules/reproducible-on-every-machine-unity.md).

Proof: git submodule status shows the reference’s count of entries, none with a leading -.

3. UPM registry and package pins — template-specific

Section titled “3. UPM registry and package pins — template-specific”

Packages/manifest.json declares the scoped registry https://upm.the1studio.org/. Network access to it is required to resolve. Credentials: t1k:unity:base:upm-auth. Which com.theone.* packages the template pins, and whether those pins are stale, is in the reference.

Expect packages-lock.json to re-dirty itself: some transitive packages are pinned only there. Reverting it is futile.

Proof: Unity resolves packages with no console error, and packages-lock.json has no entry whose version is absent from the registry.

4. Commit the template’s .meta files ONCE — [VERIFIED: RockDeclutterer#13]

Section titled “4. Commit the template’s .meta files ONCE — [VERIFIED: RockDeclutterer#13]”

A fresh template clone can arrive with base .meta files missing (116 in that case). Unity then generates a different GUID on every machine, so prefab and scene references break per-developer in ways that look random.

Right after step 1, open the project once, let Unity import, then commit every generated .meta for template-owned assets in a single commit.

Proof: git status --porcelain --untracked-files=all -- Assets | grep '\.meta$' is empty, and a second machine cloning fresh reports the same.

4b. Git LFS for binaries — generic, runs on the NEW repo

Section titled “4b. Git LFS for binaries — generic, runs on the NEW repo”

PuzzleTemplate ships no .gitattributes and no LFS (checked 2026-10-16), and carrying LFS over via gh repo create --template is not verified. So, before the first commit of any binary asset: git lfs install --local, merge the LFS patterns into the root .gitattributes (append only the missing lines, ending with .claude/** -filter -diff -merge so kit-owned files stay plain), git add --renormalize -- . ':(exclude).claude', and commit it alone as chore: track binaries with Git LFS. Never git lfs migrate here. Patterns, merge snippet, gotchas (CI-read jar, pre-push hook): references/git-lfs.md.

Proof: git check-attr filter -- <a png> prints filter: lfs, git check-attr filter -- .claude/<a binary> does not; git lfs ls-files and git lfs status agree.

5. Identity, icons, signing, Firebase — [VERIFIED]

Section titled “5. Identity, icons, signing, Firebase — [VERIFIED]”

Set in ProjectSettings.asset: companyName, productName, and applicationIdentifier for BOTH Android and iPhone, with the same bundle id on both. The setup script’s rename is only a first pass, and the template’s productName is a folder name, not a store name. The reference says exactly which files the script rewrites and which template values it leaves behind (typically AndroidManifest.xml and the Android Firebase google-services.xml).

Android signing: the per-customer keystore lives at the Unity project ROOT and is referenced as AndroidKeystoreName: '{inproject}: <name>.keystore'. Firebase: Assets/google-services.json and Assets/GoogleService-Info.plist. Create the per-customer keystore with t1k:unity:mobile:keystore-create (module mobile; if it is not installed, create it in Unity’s Keystore Manager).

The per-customer keystore is committed with the project; its passwords are secrets. Never paste a password into a commit, a PR body, or a log (rules/security.md).

Proof: a Development build installs on a device with the intended bundle id.

Firebase linked. Every title is linked to a Firebase project, with both ids recorded in .claude/t1k-project-links.json and the google-services configs matching it. Steps, proof and the post-on-every-change duty: references/firebase-link.md.

Figma linked. Every title records its Figma design file: ask the user for the figma.com URL (AskUserQuestion, never invent one) and write figma.fileKey + figma.url (optional fileName, nodeId) to .claude/t1k-project-links.json; a title with no design file sets "figma":{"optOut":true}. Schema and URL parsing: docs/project-links-check.md § Figma (theonekit-core). Proof: the links file carries figma.fileKey and figma.url, or the opt-out.

Gotcha, worth a minute: the bundle id and product name in ProjectSettings.asset are the truth. A title’s own CLAUDE.md can describe the pre-rename template values and stay wrong for months. When auditing, read ProjectSettings.asset, never the doc.

6. Per-platform define symbols — template-specific

Section titled “6. Per-platform define symbols — template-specific”

scriptingDefineSymbols is per platform and the sets are NOT the same. The reference lists the template’s actual sets and what a shipped title adds. Never let a WebGL job reuse the Android set. And defines alone are not enough: Firebase asmdefs switch on through package versionDefines whatever the defines say, so Firebase asmdefs need excludePlatforms: ["WebGL"].

Proof: a WebGL player script compile passes with no Firebase assembly in the build.

7. IL2CPP stripping — [VERIFIED] + [VERIFIED: RockDeclutterer#16]

Section titled “7. IL2CPP stripping — [VERIFIED] + [VERIFIED: RockDeclutterer#16]”

A type only ever constructed by DI has no static reference, so the IL2CPP stripper removes its constructor and the container throws at boot — VContainerException naming a blueprint type, on device only, never in the editor.

Two defences, both needed:

  1. [Preserve] on the injected class AND its constructor (house convention).
  2. A link.xml preserving the assemblies that hold DI-only types. Check whether the template ships one at Assets/Scripts/link.xml (a stub, or absent) and add it; third-party link.xml files under plugins do not cover your own assemblies.

Proof: an IL2CPP build BOOTS on device. An editor run proves nothing here.

8. C# records — [VERIFIED: RockDeclutterer#11]

Section titled “8. C# records — [VERIFIED: RockDeclutterer#11]”

record and init setters need an IsExternalInit polyfill on this toolchain. Ship it as ONE internal copy per assembly that needs it; a public copy collides ambiguously with third-party copies.

Proof: assemblies using record compile with no CS0518/ambiguity error.

Assets/Scripts/GameLifetimeScope.cs is the single root scope, and it is a LIST OF CALLS: one builder.RegisterXxx() per feature module, each defined in that module’s own namespace. Add or remove a feature by adding or removing its line. The reference gives the template’s actual list.

Removing a feature is three edits, not one: the RegisterXxx() call, the assembly-definition reference, and its link.xml entry. Registering a feature whose provider is opt-in without its core call throws at container build.

Scene scopes and the loading-to-main handoff: t1k:unity:base:boot-flow.

Proof: the app reaches the main scene with no VContainerException.

Groups live under Assets/AddressableAssetsData/AssetGroups; the reference names the template’s starter groups. A key loaded by name with no group entry fails at RUNTIME only, never at compile. When adding an asset a feature loads by key, register it in the matching group in the same change.

Proof: the content build succeeds AND the level or screen that loads the key runs.

Both templates ship Jenkinsfile/Android, Jenkinsfile/IOS, Jenkinsfile/WebGL, delegating to shared library steps, with the logic in JenkinsScripts/Scripts/*.ps1. bundletool-all.jar at the repo root converts AAB to APKs. There is no local build script.

Create the jobs with t1k:jenkins-unity (Android: Develop / Release / Creative; iOS: Develop / Release), which asks for the Discord thread id per job.

“Green build” is not the done criterion. A WebGL build can go green and still black-screen on blueprint constructor stripping (step 7). The done criterion is “boots in a browser or on a device with a clean console”, never “the build succeeded”. The PuzzleTemplate history that proves it is in references/puzzle-template.md.

“It compiles” is not a WebGL gate. An editor-domain compile references editor-only plugins and gives false greens. The real gate is a player script compile (PlayerBuildInterface.CompilePlayerScripts) PLUS the Addressables content build.

12. Kit and tracking — [VERIFIED for kit, [OPEN] for Plane]

Section titled “12. Kit and tracking — [VERIFIED for kit, [OPEN] for Plane]”

Install the kit per project (t1k init), write the project CLAUDE.md, and keep it honest: re-read ProjectSettings.asset when identity changes, per the step 5 gotcha.

Backend: server/ in this repo, not a separate one. Bootstrap does not create it; say so in the project CLAUDE.md, and start it from the gamebackend kit’s gamebackend:game-server:template-bootstrap skill. Full rule: references/backend-and-tracking.md.

[OPEN] Plane binding at bootstrap. Some titles bind one, some do not. Never auto-create a Plane project (rules/plane-workitem-workflow.md).

A title that compiles can still carry zero library wiring (2026-10 post-mortem: 2161 game files, 0 library refs). Prove it once: bun .claude/skills/t1k-unity-base-template-bootstrap/scripts/wire-proof.cjs --project-root <Unity root> (source layout .claude/modules/base/skills/...); one JSON document on stdout, the exit code is the proof.

CheckRunsFails when
a submodulesgit submodule statusa line starts with - (step 2 left one uninitialised)
b librariescore wiringFacts over .claude/t1k-libraries-unity.json (assemblies field counts)no asmdef references a mapped library; append one with t1k:unity:tof:registration
c danglingt1k:unity:architecture:dep-reconciler dry run, never --applysummary.dangling > 0 or summary.missing > 0 (UNUSED is informational)
d healthcore unity-project-health (t1k:unity:base:preflight check 1)any FAIL finding: kit, engine bridge, gate, submodules

Exit 0 all pass, 1 a check failed, 3 none failed but one could not run (reconciler, Unity assemblies or core absent): unverified is not a pass. Never edit a check to turn it green. Proof: exit 0, JSON verdict is pass.

The weak-check versus holding-check table, and the headless -nographics caveat: references/verification-table.md.

Steps 1 to 12 are interactive and stay with the main session. Step 13 is mechanical: t1k-fact-fetcher may run scripts/wire-proof.cjs and report the JSON verbatim. Fixing a failed check stays on the reasoning tier.

  1. Should bootstrap bind the repo to Plane? (step 12) A studio policy call.
  2. Should each template fix its own stale manual-step values? (step 5) See the reference’s “left at template values” section for the concrete files.

Answer one from the template repo, then edit this skill or its reference and /t1k:sync-back. Do not answer one by inference from a project that was bootstrapped months ago.