Skip to content

t1k:unity:base:project-structure

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: _Game, asset placement, assets folder, file layout, folder structure, project structure, scaffold, scripts folder, where to put

/t1k:unity:base: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.

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)”
GroupFolders
Unity-required / engineAddressableAssetsData/, Editor/, Plugins/, Resources/, Settings/, URP/, TextMesh Pro/, Scenes/
Third-party SDKsPlayFabSDK/, GoogleMobileAds/, ByteBrewSDK/, Importers/, LocalizationSetting/
TheOne frameworkUITemplate/, TheOneFeature/, TheOne.FTUE/, VContainer/, Packages/
LiveOps dataBlueprints/ (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 services
  • link.xml — IL2CPP strip preservation

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 as Scripts/ — a module shipped without its test assembly is incomplete, not “done, tests pending”. This is the Unity mechanism for code-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 moduleThat module’s own Tests/EditMode/ — never a sibling module’s or a project-global bucket
App bootstrap / DI scopeAssets/Scripts/
Game data table (SO/CSV)_Game/<Game>/Blueprints/
LiveOps dataAssets/Blueprints/ (root)
Raw artist drop_Game/<Game>/_Incoming/ (gitignored)
DOTS gameplay engine codePackages/unity-dots-library/… — NOT Assets/
Third-party SDKAssets/ root — leave untouched

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.

  • Don’t hand-write folder .meta files. 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 --recursive produces empty submodule directories (and dangling file: deps in manifest.json) if skipped — nothing errors, packages just don’t resolve. On Windows, core.symlinks/core.longpaths off checks out a symlinked package folder as a one-line text file, and deep asset paths silently truncate. rules/reproducible-on-every-machine-unity.md Rule 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/CS0311 fire 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 referenced MysteryDumpling.Runtime and passed MainScreenPresenter as a generic type argument. That looks self-contained, but proving where TPresenter : IScreenPresenter requires the compiler to walk MainScreenPresenter’s base chain up through UITemplateBaseScreenPresenter<> — which lives in UITemplate.UI, an assembly the source never mentions and the asmdef never referenced.

  • A .asmref file 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.asmref contains {"reference": "TheOne.DI.VContainer"}, which puts TheOne.DI.IInitializable and DIExtensions.GetCurrentContainer in assembly TheOne.DI.VContainer — not GameFoundation.Script (the nearest ancestor .asmdef, which directory position suggests), and not the identically-named TheOne.DI package assembly (which holds only IDependencyContainer). Before assuming which assembly owns a type, check for a .asmref in 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 .asmdef
    find <dir> -maxdepth 1 \( -name "*.asmref" -o -name "*.asmdef" \)
  • t1k-unity-base-asset-import — AssetImportProcessor that promotes _Incoming/ drops
  • t1k-unity-base-code-conventions — C# naming/style for scripts placed here
  • t1k-unity-architecture-assembly-graph — asmdef layering across modules
  • t1k-unity-testing-workflow — test asmdef fields, and where a module’s tests belong
  • code-conventions.md § “Modular Boundaries” (core) — the universal rule the asmdef trio implements
  • Game wiki Asset-Pipeline → Folder Structure Standard — game-specific leaf folders