t1k:unity:base:project-structure
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: _Game, asset placement, assets folder, file layout, folder structure, project structure, scaffold, scripts folder, where to put
How to invoke
Section titled “How to invoke”/t1k:unity:base:project-structureTheOne Unity Project Structure
Section titled “TheOne Unity Project Structure”Where every folder, asset, and script belongs in a TheOne Unity mobile-game project. Any contributor (or agent) can place a new asset/script without guessing, and scaffold a new game’s tree in one safe command.
The three layers
Section titled “The three layers”Assets/├── <Unity-required + third-party + framework> ← layer 1: leave at root, do NOT move├── Scripts/ ← layer 2: app composition root (bootstrap/DI)└── _Game/ ← layer 3: project-owned root ├── TheOne.<Feature>/ ← reusable feature CODE modules └── <GameName>/ ← game-specific ASSETS (the big tree)Layer 1 — Root folders (fixed, do not move)
Section titled “Layer 1 — Root folders (fixed, do not move)”| Group | Folders |
|---|---|
| Unity-required / engine | AddressableAssetsData/, Editor/, Plugins/, Resources/, Settings/, URP/, TextMesh Pro/, Scenes/ |
| Third-party SDKs | PlayFabSDK/, GoogleMobileAds/, ByteBrewSDK/, Importers/, LocalizationSetting/ |
| TheOne framework | UITemplate/, TheOneFeature/, TheOne.FTUE/, VContainer/, Packages/ |
| LiveOps data | Blueprints/ (Lives/Period/ProgressionReward CSV+JSON) |
Layer 2 — Assets/Scripts/ (composition root only)
Section titled “Layer 2 — Assets/Scripts/ (composition root only)”Bootstrap and DI wiring only — not gameplay:
Game.asmdef,GameLifetimeScope.cs(root VContainer scope)Scenes/— per-scene scopes;Adapters/— framework bridges;Services/— app serviceslink.xml— IL2CPP strip preservation
Layer 3 — Assets/_Game/ (project-owned)
Section titled “Layer 3 — Assets/_Game/ (project-owned)”a) Feature CODE modules — _Game/TheOne.<Feature>/Scripts/ + Scripts/DI/ + Tests/EditMode/ (one asmdef trio each)
The test asmdef is part of the module, not a follow-up.
Tests/EditMode/is created in the same phase asScripts/— a module shipped without its test assembly is incomplete, not “done, tests pending”. This is the Unity mechanism forcode-conventions.md§ “Modular Boundaries”; the cheap check it names applies verbatim here: deleting_Game/TheOne.<Feature>/should delete that feature’s tests with it, leaving no orphans in a sibling’s suite. A test for feature A living in feature B’s asmdef (or a project-global test bucket) means the pairing failed. Asmdef field requirements:t1k-unity-testing-workflow.
b) Game ASSET tree — _Game/<GameName>/ top-level skeleton (fixed org-wide convention):
Animations/ Art/2D/ Audio/ Blueprints/ Prefabs/ Scenes/ ScriptableObjects/ Scripts/ Settings/ Shaders/ VFX/ _Incoming/
Leaf folders under Art/2D/…, ScriptableObjects/…, and VFX/… are game-specific — see the game’s wiki Asset-Pipeline page.
“Where does this go?” — placement table
Section titled ““Where does this go?” — placement table”| You have… | Put it in |
|---|---|
| 2D sprite / texture / atlas | _Game/<Game>/Art/2D/<category>/ |
| Animation clip / controller | _Game/<Game>/Animations/Clips/ or Controllers/ |
| Audio file | _Game/<Game>/Audio/{BGM,SFX,Ambient,VO}/ |
| Prefab | _Game/<Game>/Prefabs/{UI,World,Cameras,VFX}/ |
| Scene | _Game/<Game>/Scenes/ |
| ScriptableObject asset | _Game/<Game>/ScriptableObjects/<family>/ |
| VFX / Shader | _Game/<Game>/VFX/ or Shaders/ |
| Gameplay script (Mono/DOTS) | _Game/<Game>/Scripts/{Runtime,Editor}/ |
| Reusable feature module | _Game/TheOne.<Feature>/Scripts/ (+ DI/, + Tests/EditMode/) |
| Test for a feature module | That module’s own Tests/EditMode/ — never a sibling module’s or a project-global bucket |
| App bootstrap / DI scope | Assets/Scripts/ |
| Game data table (SO/CSV) | _Game/<Game>/Blueprints/ |
| LiveOps data | Assets/Blueprints/ (root) |
| Raw artist drop | _Game/<Game>/_Incoming/ (gitignored) |
| DOTS gameplay engine code | Packages/unity-dots-library/… — NOT Assets/ |
| Third-party SDK | Assets/ root — leave untouched |
Scaffolding a new game’s tree
Section titled “Scaffolding a new game’s tree”Full zsh-safe recipe: references/scaffold-recipe.md
Quick note: set GAME="MyGame", run from Assets/_Game/, the recipe creates .gitkeep placeholders. Unity generates .meta on next open.
New project? Also set the fast-iteration defaults at creation (Enter Play Mode without domain reload, asmdef everywhere, noEngineReferences logic, Unity-free tests, texture Read/Write off): references/fast-iteration-defaults.md. New projects only.
Hard rules
Section titled “Hard rules”-
Don’t hand-write folder
.metafiles. Let Unity generate GUIDs. Commit.gitkeep; Unity meta-izes on next open. -
The
Assets/root tree is fixed. Asset-import validators reject assets outside the canonical tree. Scaffold first, then drop assets. -
DOTS code is NOT a
_Game/asset. ECS systems/components →Packages/unity-dots-library. Only game-specific adapters/authoring belong under_Game/<Game>/Scripts/. -
_Game/TheOne.<Feature>/≠_Game/<GameName>/. Do not nest feature modules under the game folder. -
Submodule and symlink prerequisites fail silently on a fresh clone, not loudly.
git submodule update --init --recursiveproduces empty submodule directories (and danglingfile:deps inmanifest.json) if skipped — nothing errors, packages just don’t resolve. On Windows,core.symlinks/core.longpathsoff checks out a symlinked package folder as a one-line text file, and deep asset paths silently truncate.rules/reproducible-on-every-machine-unity.mdRule 2 has the full prerequisite → symptom table. -
An asmdef needs the transitive BASE-TYPE chain of every type it touches, not just the types it names.
CS0012/CS0311fire on a base type that never appears anywhere in your source — auditing only the identifiers you wrote is not enough; walk each referenced type’s base chain and reference every assembly in it too. Real case: an assembly referencedMysteryDumpling.Runtimeand passedMainScreenPresenteras a generic type argument. That looks self-contained, but provingwhere TPresenter : IScreenPresenterrequires the compiler to walkMainScreenPresenter’s base chain up throughUITemplateBaseScreenPresenter<>— which lives inUITemplate.UI, an assembly the source never mentions and the asmdef never referenced. -
A
.asmreffile silently reassigns a folder to a different assembly than the nearest.asmdef. Namespace does not imply assembly, and directory position does not imply assembly — a type can live in an assembly whose name matches neither. Example:Packages/com.gdk.core/Scripts/DI/TheOne.DI.asmrefcontains{"reference": "TheOne.DI.VContainer"}, which putsTheOne.DI.IInitializableandDIExtensions.GetCurrentContainerin assemblyTheOne.DI.VContainer— notGameFoundation.Script(the nearest ancestor.asmdef, which directory position suggests), and not the identically-namedTheOne.DIpackage assembly (which holds onlyIDependencyContainer). Before assuming which assembly owns a type, check for a.asmrefin its folder and every ancestor folder up to the nearest.asmdef:Terminal window # which assembly really owns a file: walk up for .asmref FIRST, then .asmdeffind <dir> -maxdepth 1 \( -name "*.asmref" -o -name "*.asmdef" \)
Related
Section titled “Related”t1k-unity-base-asset-import— AssetImportProcessor that promotes_Incoming/dropst1k-unity-base-code-conventions— C# naming/style for scripts placed heret1k-unity-architecture-assembly-graph— asmdef layering across modulest1k-unity-testing-workflow— test asmdef fields, and where a module’s tests belongcode-conventions.md§ “Modular Boundaries” (core) — the universal rule the asmdef trio implements- Game wiki Asset-Pipeline → Folder Structure Standard — game-specific leaf folders