Unity Project Structure

Retrieval Sources

Key Guidelines

Folder Layout & Special Folders

Unity reserves a fixed set of subfolder names directly under Assets/ (or nested anywhere below it, per-folder rules vary) that change how their contents are treated at import and build time — this is not convention, it is enforced behavior:

• Editor — any folder named exactly Editor, anywhere under Assets/, unlimited count. Scripts inside compile into an editor-only assembly, are stripped from Player builds, and MonoBehaviours inside cannot be attached to GameObjects as components. The exact location of an Editor folder affects which of the four default compile phases its contents land in (see Assembly Definitions below) — prefer an .asmdef with no platform restrictions plus "includePlatforms": ["Editor"] over relying on folder name/location if you need editor code that isn't at the top level.
• Editor Default Resources — root of Assets/ only, max 1 per project. Assets loaded on demand via EditorGUIUtility.Load; always include the subfolder path in the load call if assets are nested.
• Resources — unlimited count, any location under Assets/. Everything inside is loadable via Resources.Load and is always included in the build, whether referenced by a scene or not. Overuse directly bloats build size and startup/load time — prefer Addressables or direct scene references for anything not needed for truly dynamic runtime lookup.
• Plugins — reserved for native/managed third-party plugin binaries; exact subfolder naming (e.g. Plugins/Android, Plugins/x86_64) determines platform targeting — see the platform plugin import docs, not covered here.
• Gizmos — root of Assets/ only, max 1 per project. Icon/texture files consumed by Gizmos.DrawIcon in the Scene view; not shipped in Player builds.
• StreamingAssets — root of Assets/ only, max 1 per project. Files copied byte-for-byte into the build output and read at runtime through Application.streamingAssetsPath rather than the AssetDatabase — the one place dot-prefixed files are not ignored during import.

Hidden/ignored during import (any of these anywhere under Assets/ are skipped by the importer, StreamingAssets dot-files excepted): hidden OS folders, files/folders starting with ., files/folders ending with ~, anything named cvs, files with a .tmp extension. Note the Editor auto-converts a leading . typed in its Create menu into a leading _ to avoid crashes — to genuinely get a dot-prefixed folder (e.g. .git, .github) you must create it outside the Editor, directly on disk.

Beyond the reserved names, organize Assets/ by feature/domain, not by asset type for anything beyond a small prototype (avoid a top-level Scripts/, Prefabs/, Materials/ split once the project grows) — this keeps each feature's .asmdef-scoped code physically co-located with the art/data it owns, which is what makes assembly boundaries and ownership legible at a glance. A typical mid-size layout:

Assets/
  _Project/
    Characters/
      Player/
        Scripts/ (has its own Player.asmdef)
        Prefabs/
        Art/
      Enemies/
    Systems/
      Combat/
      Inventory/
    Editor/                 (project-wide editor tooling)
    Resources/              (kept small and audited)
    Tests/
      EditMode/
      PlayMode/
  Plugins/
  StreamingAssets/
Packages/
  manifest.json
  packages-lock.json
ProjectSettings/

A leading underscore folder (e.g. _Project) is a common convention (not a reserved name) to sort first-party content above Unity's own Packages/imported asset folders in the Project window's alphabetical sort.

Assembly Definitions

Unity's default compilation model, absent any .asmdef files, splits all scripts into exactly four predefined assemblies based purely on folder location and name (Manual/script-compile-order-folders.html):

A script can only reference types compiled in its own phase or an earlier one — never a later phase. This is the root cause of "why can't my Editor script see my runtime class" style errors when folder placement crosses a phase boundary unexpectedly.

Creating your own .asmdef files (Assets > Create > Scripting > Assembly Definition) opts a folder subtree out of this default scheme entirely: the new assembly contains every script in that folder and its subfolders except subfolders that have their own .asmdef/.asmref. Two benefits compound as a project grows: (1) editing a script only triggers a recompile of assemblies whose dependency graph includes it, not the whole project; (2) the references array makes cross-feature dependencies explicit and enforced by the compiler, rather than implicit through global visibility. Use .asmref (Assets > Create > Scripting > Assembly Definition Reference) to fold an additional folder into an existing assembly without creating a second .asmdef — useful for splitting a feature's implementation and its Editor/ subfolder into different physical locations that still compile as one logical assembly, or the reverse.

The full .asmdef JSON schema (Manual/assembly-definition-file-format.html):

Real worked example from the docs (assembly-name form, platform-included, with precompiled DLL overrides):

{
  "name": "BeeAssembly",
  "references": [
    "Unity.CollabProxy.Editor",
    "AssemblyB",
    "UnityEngine.UI",
    "UnityEngine.TestRunner",
    "UnityEditor.TestRunner"
  ],
  "includePlatforms": ["Android", "LinuxStandalone64", "WebGL"],
  "excludePlatforms": [],
  "overrideReferences": true,
  "precompiledReferences": ["Newtonsoft.Json.dll", "nunit.framework.dll"],
  "autoReferenced": false,
  "defineConstraints": ["UNITY_2019", "UNITY_INCLUDE_TESTS"],
  "versionDefines": [
    { "name": "com.unity.ide.vscode", "expression": "[1.7,2.4.1]", "define": "MY_SYMBOL" },
    { "name": "com.unity.test-framework", "expression": "[2.7.2-preview.8]", "define": "TESTS" }
  ],
  "noEngineReferences": false
}

Prefer GUID references over name references for .asmdef-to-.asmdef links in shared/team projects — a name reference silently breaks if you ever rename the referenced assembly, while a GUID (resolvable/settable via AssetDatabase.AssetPathToGUID/GUIDToAssetPath) survives renames. Whichever form you pick, use it consistently across the whole references array (mixing forms within one file is not supported).

Package Manager & manifest.json

Packages/manifest.json is the project manifest — it declares only direct dependencies; the transitive graph is resolved automatically and (with lock files enabled) pinned in Packages/packages-lock.json. This is distinct from a package.json inside any individual package (the package manifest, Manual/upm-manifestPkg.html) — don't confuse the two when editing by hand.

Project manifest top-level keys (Manual/upm-manifestPrj.html):

Example combining a scoped registry with direct, registry-resolved dependencies:

{
  "scopedRegistries": [
    {
      "name": "My internal registry",
      "url": "https://my.internal.registry.com",
      "scopes": ["com.company"]
    }
  ],
  "dependencies": {
    "com.unity.package-1": "1.0.0",
    "com.unity.package-2": "2.0.0",
    "com.company.my-tools": "1.4.0"
  }
}

A dependency's source is encoded directly in its value string, not a separate field:

• Registry: a plain version string, e.g. "1.3.1" — resolved from the default registry or a matching scoped registry.
• Local (Manual/upm-localpath.html): "file:../SharedPackages/my-package" or a tarball path — forward slashes always work; on Windows, escaped backslashes work but aren't recommended. Good for local offline iteration on a package before publishing it.
• Git (Manual/upm-git.html): "https://github.com/org/repo.git", optionally with #<revision> and ?path=/sub/folder for a subfolder package. Requires a local Git client >= 2.14.0 on every machine and CI runner that resolves the project (and the Git LFS client too, if the repo uses LFS). Git dependencies can only be declared in the project manifest — packages cannot depend on each other via Git URLs.
• Embedded (Manual/upm-embed.html): no manifest entry needed at all — any folder physically present under Packages/ is auto-detected and always wins over a same-named registry/version entry in dependencies, even if that entry's version differs. If the project is under source control, the embedded package's full contents must be committed too, since nothing about it is reproducible from the manifest alone.

Always commit Packages/packages-lock.json alongside manifest.json — it is the resolved, deterministic dependency graph (direct + transitive, with exact versions), and without it different machines/CI runs can resolve slightly different transitive versions even from an identical manifest.

The global UPM package cache (Manual/upm-cache.html) lives outside the project entirely and must never be added to a repo:

Version Control Setup

Two Editor settings under Edit > Project Settings control how cleanly a Unity project behaves under source control, and both should be set before the first commit:

1. Version Control category → Mode (Manual/class-VersionControlSettings.html): Visible Meta Files (default, correct choice for Git/any VCS Unity doesn't natively integrate with), Hidden Meta Files (hides .meta from the OS file browser — avoid, it makes .meta files easy to forget to commit), or Perforce (enables native Perforce integration fields: Username/Password/Workspace/Server/Host/Log Level/Automatic Add/Work Offline/Async Update).
2. Editor category → Asset Serialization → Mode (Manual/class-EditorManager.html): Force Text is the documented default and is what you want for Git — it stores scenes/prefabs/assets as diffable, mergeable YAML. Mixed leaves existing binary assets binary while defaulting new ones to Binary; Force Binary converts everything to a non-diffable binary format. The adjacent "Reduce version control noise" checkbox forces the Editor to keep YAML references on one line (splitting only past 80 characters), which measurably shrinks diff noise on scene/prefab changes — enable it for any team repo.

Every asset's .meta file must be committed alongside the asset it describes — it carries the asset's GUID, which is what every other asset's reference (material slot, prefab link, scene object reference, .asmdef GUID reference) actually points at internally. Deleting, regenerating, or failing to commit a .meta silently breaks every inbound reference, and Unity will not warn you at commit time — only when something shows up "Missing" in the Editor.

.gitignore for a Unity project (only ever ignore regenerable, machine-local output; everything else — including ProjectSettings/, source Assets/, and Packages/, is source of truth):

# Unity-generated, regenerable
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Uu]serSettings/
[Mm]emoryCaptures/
.vs/
.vscode/
.idea/
*.csproj
*.sln
*.user
*.userprefs
*.unityproj
*.tmp
*.pidb
*.svd
sysinfo.txt
crashlytics-build.properties

ProjectSettings/ must be committed — it holds build target settings, tag/layer definitions, physics/quality/graphics/input settings, and more, serialized as text; treat it exactly like Assets/.

For merge conflicts in scenes and prefabs (which are YAML but still semantically structured, so a naive text merge frequently produces a corrupt file), configure UnityYAMLMerge as git's merge driver (Manual/SmartMerge.html). The tool ships inside the Editor install:

• Windows: C:\Program Files\Unity\Editor\Data\Tools\UnityYAMLMerge.exe
• macOS: /Applications/Unity/Unity.app/Contents/Helpers/UnityYAMLMerge (right-click the .app → Show Package Contents to browse there)

Its fallback behavior for unresolved conflicts/unknown file types is controlled by mergespecfile.txt next to the binary, and in the Version Control project settings its Smart Merge mode (visible once Mode is set to Perforce/UVCS) can be Off, Premerge (auto-resolve clean merges, produce base/theirs/mine files for the rest), or Ask (default — prompt on conflict).

If the project is managed through Unity's own native integrations rather than a generic VCS, use Perforce (Manual/perForceIntegration.html) or Unity Version Control (UVCS) — both are configured from the same Version Control settings page, switching Mode away from the Git-friendly "Visible Meta Files" default.

Git LFS

Git handles large or frequently-changing binary files (textures, audio, video, FBX/model files, .psd, baked lighting data) poorly — every version is stored in full in history, bloating clone size and slowing every operation. Git LFS replaces the binary blob in the repo with a small pointer file and stores the actual content in LFS-backed storage, fetched on demand. Configure via .gitattributes at the project root:

# Images
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.tga filter=lfs diff=lfs merge=lfs -text
*.tif filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text
*.hdr filter=lfs diff=lfs merge=lfs -text

# Audio / video
*.wav filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

# 3D / animation
*.fbx filter=lfs diff=lfs merge=lfs -text
*.blend filter=lfs diff=lfs merge=lfs -text

# Build artifacts occasionally checked in deliberately (installers, etc.)
*.apk filter=lfs diff=lfs merge=lfs -text
*.unitypackage filter=lfs diff=lfs merge=lfs -text

Do not LFS-track .meta files or any text-serialized asset (scenes/prefabs/.asset files in Force Text mode) — those need to stay diffable/mergeable as plain text; LFS pointer-ifying them defeats Smart Merge entirely. If the project also consumes a package as a Git dependency (Manual/upm-git.html) from a repo that itself uses Git LFS, every machine resolving that dependency — including CI — needs the Git LFS client installed, not just Git itself, or resolution silently fails to fetch the actual LFS-backed content.

Common Mistakes

Quick Reference

Advanced Notes

Large-project scaling. Once a project passes roughly a few dozen .asmdefs, the assembly graph itself becomes a maintenance surface: a tangled or overly-deep reference chain reintroduces the "everything recompiles" problem one level up, because changing a low-level shared assembly still invalidates everything above it. Keep a strict layering discipline (e.g. Core → Systems → Features → Game, references only pointing downward) and forbid cyclic references between feature assemblies — Unity's compiler rejects true cycles, but near-cycles through a shared "utility" assembly that itself references feature code produce the same recompile blowup indirectly. Use Compilation.CompilationPipeline (ScriptReference/Compilation.CompilationPipeline.html) from an Editor-only tooling script to programmatically dump the current assembly graph and its dependency edges for CI-side auditing (e.g. failing a PR that introduces a new cross-layer reference).

Monorepo / multi-project package sharing. For multiple Unity projects sharing internal code (a company with several titles, or a game plus a companion tool), there are three realistic strategies, in increasing order of process overhead but decreasing coupling risk:

1. Git-URL package dependency (Manual/upm-git.html) pointing every consuming project's manifest.json at a shared package repo, pinned to a revision — simplest to adopt, but every consumer must bump the pinned revision manually to pick up changes, and Git dependencies can't nest (a package can't itself declare a Git dependency).
2. Scoped registry (Manual/upm-scoped.html, upm-scoped-use.html, upm-scoped-host.html) hosting real semver-versioned releases of shared packages — the correct choice once more than a couple of projects consume the same code, since it gives proper version negotiation, resolutionStrategy, and pinnedPackages semantics that a raw Git URL can't.
3. Embedded package via a git submodule or symlink into each consuming project's Packages/ folder — fastest local iteration loop (edits are immediately visible with no publish step) but requires every contributor to correctly manage the submodule/symlink, and since embedded packages must have their full contents committed if the project is under source control, a naive submodule setup can end up duplicating the shared code's history into every consumer repo.

For a true single-repo monorepo containing multiple Unity projects, keep shared code as one or more packages under a top-level Packages/ (or a dedicated shared-packages/ directory referenced by file: path) rather than duplicating an Assets/ subtree across projects — this is the only structure where a single .asmdef edit is instantly visible to every consuming project's compiler without any explicit publish/update step, at the cost of every consumer needing an identical relative path layout for file:-based manifest entries to resolve.

Package Manager caches at scale. On CI fleets or shared build farms, redirect the global UPM cache (Manual/upm-cache.html, Manual/package-manager-caches.html) to a persistent, shared volume across ephemeral runners rather than accepting the per-user default — this turns every cold-cache full package re-download into a cache hit and is one of the largest easy wins for CI build-time variance on package-heavy projects.