unity-new-project
Start a new Unity 6 project: pin the editor, git and LFS, pinned UPM packages, asmdef layout.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- unity-new-project
- description
- Start a new Unity 6 project: pin the editor, git and LFS, pinned UPM packages, asmdef layout.
02 资源文件 7
- 参考文档reference/generated-assets.md5.0 KB
- 参考文档reference/package-bootstrap.md12.4 KB
- 参考文档reference/package-selection.md8.5 KB
- 参考文档reference/project-structure.md3.2 KB
- 参考文档reference/pure-test-lane.md4.3 KB
- 参考文档reference/version-control-setup.md8.3 KB
- 脚本scripts/pure_tests.py26.5 KB
03 SKILL.md 正文
unity-new-project — day-one decisions for a Unity 6 project
Everything here is cheap now and expensive later. None of it is urgent on day one, which is exactly why it gets skipped — and every item is something that, once a team and a history exist, costs a migration rather than a setting.
Request → where to look
| Request or symptom | Go to |
|---|---|
| Starting a Unity project; which editor version; render pipeline at creation | §1 |
| A freshly created template project does not compile | §1, then reference/package-bootstrap.md |
Onboarding a repo to version control: .meta, ignores, LFS from day one |
§2, reference/version-control-setup.md |
| Publishing an existing project to a git remote | reference/version-control-setup.md §4 |
| Adding a UPM git dependency; pinning it to an annotated tag | §3 |
| Mobile is even "maybe": IL2CPP / Android baseline | §4 |
| Installing packages; which packages a starting project needs | §4b, reference/package-selection.md |
| Reviewing early project structure: asmdef module boundaries, the single input funnel, Boot scene | reference/project-structure.md |
| Tests for pure assemblies without opening the Editor | reference/pure-test-lane.md |
| A scaffolder that wipes Inspector values; generated ScriptableObjects | reference/generated-assets.md |
1. Pin the editor, first commit
- Record the exact editor version (e.g.
6000.0.47f1) and install via Unity Hub;ProjectSettings/ProjectVersion.txtis the SoT and is committed. A teammate (or CI) on a different patch version silently reserializes assets — diffs become noise and prefabs drift. - Decide the render pipeline (URP for mobile/2.5D) at creation — swapping pipelines later touches every material.
- Once the target platforms are known, put the editor install in the background and keep asking
—
unity install <version> --module <modules> --yes --accept-eularuns for minutes, none of the remaining decisions depend on it, andunity editors --installedis the confirmation that it landed before you create the project. An install that died halfway looks exactly like one still running. Both flags are what makes it backgroundable: without them the install stops on a prompt nobody is watching, and a job blocked on stdin is indistinguishable from a slow download. - A template is not a working configuration. Creating from
universal-2don Unity 6000.4 gives project-wide compile errors from the template's own stale package locks. When a fresh project will not compile, suspectPackages/manifest.jsonbefore the code —reference/package-bootstrap.md.
2. Version control (Unity's own layout fights git)
.metafiles ARE committed (they carry GUIDs — a missing .meta = broken references for everyone else); enableVisible Meta Files+Asset Serialization: Force Text; caches (Library/etc.) stay ignored.- Large binaries → git LFS from day one — retrofitting LFS rewrites history. Write
.gitattributesin the first commit, then prove the first binary commit used it:git lfs ls-files | wc -landgit show HEAD:<path> | head -c 60(an LFS blob startsversion https://git-lfs.github.com/spec/v1).git lfs ls-files --cacheddoes not exist — it exits withError: unknown flag: --cached, which is easy to miss inside a chained command. Full file, the text-YAML exception that grows (a dynamic CJK TMP font asset can grow from ~202 KB to 1.3–1.6 MB over a day of Editor sessions), and publishing an already-large repo to a remote:reference/version-control-setup.md. - Keep an LFS ledger: each binary commit states what it adds against the plan's quota, a
push of several hundred MB or of purchased assets waits for the person, and when agents share
a checkout, check
git log origin/main..HEADbefore pushing →reference/version-control-setup.md§5–§7. - Three hosting shapes, and the choice is the user's, not a default: GitHub/GitLab + LFS;
UVCS, which handles large binaries natively and needs no LFS at all; or plain local
git. - Push the first commit after packages are installed and the Editor has generated
.metafiles — an initial commit of an empty project is a commit you will have to amend. If you are scripting creation, that is what--no-initial-commitis for. If creation already committed — a--vcsrun without that flag publishes the bare project as commit one — add a follow-up commit for the packages and.metafiles rather than amending or re-committing the same tree twice; the history is already public by then, and two initial commits are worse than one empty one. - Credentials go in on stdin, never in
argv(--git-token-stdin). A token expanded from an environment variable is still visible in the process list and in shell history; CI must mask it in logs too.
3. UPM git dependencies — the pinning iron law
Add private packages by git URL pinned to an annotated tag, never a branch:
"com.<vendor>.<pkg>": "https://github.com/<org>/<repo>.git?path=unity-package#vX.Y.Z"
Tracking master means builds change under you; a pinned tag makes every
upgrade a deliberate ref bump. Keep NDK/AGP versions aligned with what the
native packages were built against — don't bump blindly, and expect a native
SDK to pin those deliberately rather than take automated dependency bumps.
Note the ?path= form when the package lives in a subfolder — the usual
shape for a native SDK, whose Unity package sits one folder inside the repo
that also carries the native sources.
Three consequences of it being a git URL:
- Credentials, not Unity, decide whether it resolves. A machine can reach a private dependency
non-interactively over https (an osxkeychain helper, say) and not over SSH. Run
git ls-remote <that exact URL>before the installer on any new machine or CI box; without it the project simply fails to compile, and the symptom you actually see is "no test results file", not a package error. manifest.jsonis the request;packages-lock.jsonis what you compiled. The lockfile carries the resolved commithash— check it against the tag, and checkLibrary/PackageCachefor the directory that was really unpacked.- A tag bump touches three places together: the version constant in your installer script,
manifest.json, andpackages-lock.json.
4. Android/IL2CPP baseline (if mobile is even "maybe")
Set in Player Settings on day one: IL2CPP + ARM64, minSdk to what your
plugins demand now, and a real package name (com.<org>.<app> — renaming
later touches keystore/store identity, same trap as Flutter's --org).
Build/release mechanics: unity-android-release.
The minSdk you ask for is not necessarily the minSdk you ship. Unity 6000.4 clamps minSdk up to its own floor of 25: ask for 23 and you get
AndroidApiLevel25back, so the build ships minSdk 25 whatever the plugin's documented floor says. Treat a plugin's number as a lower bound, not the answer: set it in the setup method below, readPlayerSettings.Android.minSdkVersionback, and ship that value — it is the one for the release notes. Check the floor on your own editor version (26 from 6000.5).
Put these in a re-runnable [MenuItem] + -executeMethod method rather than clicking them,
and set EditorSettings.serializationMode = ForceText and
VersionControlSettings.mode = "Visible Meta Files" in the same method — §2 depends on both,
and both vanish when someone recreates the project from a template.
→ reference/generated-assets.md
4b. Packages: install them through the API, never by hand
Install only what the concept actually needs, prefer what the template already ships (a URP
template already has the render pipeline and Input System), and do not pin a version unless
there is a stated minimum. Concept → need → id, and the subtraction step that shrinks the list:
reference/package-selection.md. Two rules that decide whether
it works at all:
- Never edit
Packages/manifest.jsonby hand, and never guess an id. List it withClient.SearchAll()— one call is cheaper than one wrong guess. The single exception is the template whose own locks do not compile (§1): there you replace the manifest wholesale with a set known good on this editor version, reopen the Editor, and let UPM rewrite the lockfile. - A headless install that returns exit 0 and installs nothing is the normal failure mode, not an
unusual one. →
reference/package-bootstrap.md
If you are driving this as a guided flow, start the editor install in the background while you
are still asking the concept questions, then join on unity editors --installed --format json
before doing anything downstream. Parallelism only pays when there is conversation to overlap it
with — with nothing left to ask, just wait.
Ask one step at a time, and the concept interview is not this skill's. What the game is belongs to
unity-game-brief; what arrives here is a settled proposal. Even for the questions this skill does own — target platforms, hosting shape, editor version — put one on the table, wait for the answer, then move: platform and monetisation answers change which modules install and which packages go in the list, so a batch of questions collected up front produces a setup that has to be redone. Nothing is scaffolded before those answers exist.
5. Structure that survives growth → reference/project-structure.md
asmdef per module, a noEngineReferences assembly and its pure test lane, injected clock and
seed, one input funnel, a Boot scene, the art pipeline, generated assets as build output.
Scope — what this skill does NOT do
This skill owns the decisions; the unity commands that execute them are unity-cli.
No gameplay scaffolding. A generic genre skeleton produces throwaway mock primitives that have to be deleted before real work starts, so this skill stops at a clean, correctly-configured project. Building the actual game is every other skill in this plugin.
What the game is — the brief, the constraints, the architecture proposal, the first interaction —
is unity-game-brief; this skill starts when that proposal names the assemblies.
Also not here: which packages a given genre needs beyond the starting point in §4b and
reference/package-selection.md — that table is something to subtract from once the concept is
known, never a list to install whole. Nor anything about shipping — unity-android-release,
unity-web-release.
Nor the font pipeline: this skill owns only the version-control consequence that TMP font assets
live in the text (non-LFS) half of the repo and grow there. Atlases, fallback chains and
locales are unity-localization.
Related skills
The terminal: unity-cli. Verifying a change: unity-debug.
Gameplay: unity-gameplay (routes by perspective).
3C: unity-input · unity-camera · unity-animation.
2D runtime: unity-2d-controller · unity-physics-2d · unity-2d-rendering ·
unity-2d-level · unity-2d-grid · unity-2d-animation.
UI: unity-game-ui (routes) → unity-ui-ugui · unity-ui-toolkit.
Assets: unity-3d-models · unity-2d-sprites · unity-rigged-character.
Runtime domains: unity-physics-3d · unity-navigation · unity-render-urp ·
unity-audio · unity-localization.
Shipping: unity-android-release · unity-web-release.
Backend & commerce: unity-live-services (routes) → unity-ugs ·
unity-multiplayer-services · unity-vivox · unity-iap · unity-ads-levelplay.
Consistent AI art: codex-visual.
04 同仓库更多 Skills
unity-web-release
Ship a WebGL/WebGPU build: shrink the download, Brotli server headers, Safari and iPhone memory.
unity-vivox
Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.
unity-urp-migration
Migrate a Built-in project to URP, or fix a half-moved one: pink materials, PPv2, old shaders.
unity-ui-ugui
Canvas UI (uGUI): CanvasScaler, RectTransform anchors, Layout Groups, ScrollView, UI built from C#.
unity-ui-toolkit
UI Toolkit (UXML, USS, UIDocument): flex layout, binding, custom elements, editor windows.
unity-ugs
Unity Gaming Services API: which package, init and sign-in order, Cloud Save, Cloud Code, Remote Config.