GDnD Wiki

GDnD Wiki

This site is for Ulster University students and staff. Enter the class access password to continue.

Unity Project Setup, Folder Structure and Naming

14 min read

Unity Project Setup, Folder Structure and Naming

Overview

A Unity project quickly fills with hundreds of scripts, sprites, sounds, scenes and prefabs. Project organisation is the set of decisions that keeps them findable: which template you start from, how the Assets folder is laid out, how files are named, and which of Unity’s reserved folder names you use on purpose. It matters most when more than one person works on a project, because a shared structure is what lets a teammate (or a marker, or you in three months’ time) find things without asking.

Unity’s own guidance is pragmatic: “Although there is no single way to organize your project”, it recommends that a team define and document its naming conventions and folder structure, then stick to them (Unity Technologies, Best practices for project organization and version control, Unity 6 edition, see source-unity-project-organisation-version-control). This page gathers that guidance with the Unity 6.3 Manual’s rules on script names, reserved folders and .meta files. Code naming (fields, methods, classes) is covered separately in csharp-code-style; committing the project to Git is covered in git-github-unity.

Setup

Create the project from a template

In the Unity Hub, open the Projects tab, select New project, choose an Editor version and a template, fill in the project name and location, then select Create project. For most student work in Unity 6, one of the Universal Render Pipeline templates is the sensible start (Unity Technologies, Create a new project that uses URP, Unity 6.3 Manual):

  • Universal 2D: “an empty project for 2D applications. URP is pre-configured with 2D renderer.”
  • Universal 3D: “an empty project for 3D applications. URP is pre-configured with 3D renderer.”

The list of templates depends on the Editor version you pick. Choose the version your team or course has agreed on, and record it in the project’s README, because opening a project in a different Editor version can upgrade its files.

Name the project without spaces (for example CoinCollector, not Coin Collector): Unity’s guide advises against spaces in file and folder names in general, and notes in its companion article that “Unity’s command line tools have issues with path names that include spaces” (Unity Technologies, Best practices for organizing your Unity project, unity.com).

First five minutes in a new project

  1. Set your code editor under Edit > Preferences > External Tools > External Script Editor (on macOS, Unity > Settings). See unity-debugging for the editor-specific packages.
  2. Add a Unity .gitignore before the first commit, so Library/, Temp/, Logs/ and similar generated folders are never committed (see git-github-unity).
  3. Leave Edit > Project Settings > Version Control > Mode on Visible Meta Files. This is the default, intended for version control systems Unity does not integrate with directly, such as Git (Unity Technologies, Version Control project settings reference, Unity 6.3 Manual).
  4. Create your top-level folders (below), then commit.

Usage

What is in a project folder

FolderContainsCommit to Git?
Assets/Everything you author or import: scripts, art, audio, scenes, prefabs, plus their .meta filesYes
Packages/The package manifest listing which packages the project usesYes
ProjectSettings/Project-wide settings (tags, layers, physics, input, quality)Yes
Library/, Temp/, Logs/, obj/, UserSettings/Caches and per-machine data that Unity regeneratesNo (see git-github-unity)

Unity’s guide also says to “avoid extra folders at the root level”: keep content inside Assets unless there is a real need (Unity Technologies, Best practices for project organization and version control).

Laying out Assets: by type or by feature

By type groups files by what they are: all scripts in Scripts, all sprites in Art/Sprites, all prefabs in Prefabs. Unity’s guide gives two example layouts, both “based on splitting up your project by asset type”, and notes that the Hub’s templates and Learn projects are organised the same way. One of its examples (Unity Technologies, Best practices for project organization and version control):

Assets
+---Art
|   +---Materials
|   +---Models
|   +---Textures
+---Audio
|   +---Music
|   \---Sound
+---Code
|   +---Scripts      # C# scripts
|   \---Shaders      # Shader files and shader graphs
+---Docs             # Wiki, concept art, marketing material
+---Level            # Anything related to game design in Unity
    +---Prefabs
    +---Scenes
    \---UI

By feature groups everything one gameplay feature needs in one place, for example Features/Player/ holding the player’s scripts, sprites, animations and prefab, and Features/Enemies/Bat/ holding the bat’s. Unity’s guide does not discuss this layout; the trade-offs below are this wiki’s interpretation.

By typeBy feature
Easy to learnYes; matches Unity’s templates and most tutorialsNeeds an agreed definition of “feature”
Finding all the parts of one thingSpread across several foldersOne folder
Deleting or reusing a featureHunt through every type folderDelete or copy one folder
Scales to large teamsFolders grow very longTeams can own feature folders, which tends to reduce conflicts
Shared assets (fonts, common materials)Natural homeNeed a Shared/ or Common/ folder anyway

Arguably, small first projects suit by type, because it matches what you will see in templates and tutorials; as a project grows past a handful of systems, a hybrid (by feature at the top, by type inside each feature) is a common compromise. Whichever you choose, Unity’s guide adds three rules that apply to both (Unity Technologies, Best practices for project organization and version control):

  • Keep your own work separate from third-party assets. Asset Store packages arrive with their own structure, which you may not be able to change. Unity’s folder-generator script creates a root folder named after the project inside Assets for exactly this reason, and its by-type table includes a ThirdParty folder.
  • Separate sandbox areas. Put experiments and non-production scenes in their own folder, optionally with a subfolder per team member, so they never get mistaken for the real game.
  • Decide early. Many version control systems treat a moved file as a deletion plus an addition, losing its history, so a structure agreed at the start avoids churn later.

A starter layout that follows these rules:

Assets
+---_Project          # the underscore sorts it first; everything you make lives here
|   +---Art
|   +---Audio
|   +---Prefabs
|   +---Scenes
|   +---Scripts
|   \---UI
+---Sandbox           # experiments, per-person test scenes
\---ThirdParty        # Asset Store and other imported packs, left as supplied

The name _Project is a widespread community convention, not a Unity rule; using your game’s name works equally well.

Naming conventions

Unity’s guide lists naming standards for GameObjects, prefabs and asset files (Unity Technologies, Best practices for project organization and version control):

StandardExample
Use descriptive names and do not abbreviateLargeButton, not lButton
Use PascalCase or camelCase; avoid spacesEnemySpawner, not enemy spawner
Use underscores (or hyphens) sparingly, for variantsEnterButton_Active, Foliage_Normalmap, Building_LOD0
Use number suffixes only for real sequencesNode0, Node1, Node2
Follow the design document’s namesIf the GDD says RedDragonLair, use that exact spelling

One workable convention built on those standards (a suggestion, not a Unity rule):

AssetPatternExample
ScriptPascalCase noun or role, same as the classPlayerController.cs, CoinPickup.cs
ScenePascalCase, number levels with two digitsMainMenu.unity, Level01_Forest.unity
PrefabPascalCase, variant after an underscoreCoin.prefab, Enemy_Bat.prefab
Sprite or sheetSubject, then statePlayer_Idle.png, Player_Run_Sheet.png
AudioCategory, then descriptionSFX_CoinPickup.wav, Music_Level01.ogg
MaterialName of the surfaceBrick_Red.mat

If you change a rule part-way through, Unity’s guide recommends renaming every affected asset at once, using a script when there are many, rather than leaving a mix.

Script file name must match the class name

When you create a script, the file name you type becomes the class name inside it. The Unity 6.3 Manual calls it good practice to keep the two the same. For MonoBehaviour and ScriptableObject scripts, Unity can still resolve a class whose file name differs, with limits: if a file defines several classes, Unity picks the one whose name matches the file, and wherever it cannot match a class to a file unambiguously, it shows a warning (Unity Technologies, Naming scripts and MonoBehaviour components, Unity 6.3 Manual). In practice, keep exactly one MonoBehaviour per file with an identical name, and when you rename one, rename both: the file in the Project window and the class in your code editor.

// File: Assets/_Project/Scripts/Player/PlayerController.cs
using UnityEngine;
 
namespace CoinCollector.Player
{
    public class PlayerController : MonoBehaviour   // matches PlayerController.cs
    {
        [SerializeField] private float moveSpeed = 5f;
    }
}

The namespace is optional but useful: the Manual recommends namespaces to avoid two classes with the same name (two people each writing a Controller) clashing, and Unity’s guide suggests matching your folder structure to your namespaces (Unity Technologies, Naming scripts; Best practices for project organization and version control). See csharp-code-style for naming inside the code.

Reserved folder names

Some folder names change how Unity treats their contents. The Unity 6.3 Manual lists them as follows (Unity Technologies, Reserved folder name reference, Unity 6.3 Manual):

FolderWhereWhat Unity does with it
EditorAny level under AssetsReserved for Editor scripts, which are excluded from builds. A MonoBehaviour in an Editor folder cannot be attached to a GameObject. Also affects script compilation order.
Editor Default ResourcesRoot of Assets onlyAssets that Editor scripts load on demand.
GizmosRoot of Assets onlyImage files used by Gizmos.DrawIcon in the Scene view.
ResourcesAny level under AssetsAssets loaded by name from scripts at runtime rather than referenced in a scene. Everything in it is included in builds, which increases build size.
PluginsSee the Manual’s plug-in pagesReserved for third-party plug-ins.
StreamingAssetsRoot of Assets onlyFiles copied to the build in their original format, for streaming at runtime.

During import Unity also ignores hidden folders, files and folders whose names start with . (except inside StreamingAssets) or end with ~, folders named cvs, and files with the .tmp extension. If you create a folder with a leading dot through the Editor’s create menu, Unity converts the dot into an underscore.

For beginners the practical rule is: do not name an ordinary folder Editor or Resources by accident (a gameplay script placed in an Editor folder will vanish from your build and cannot be added as a component), and prefer Inspector references over Resources for loading assets.

.meta files

When Unity imports an asset it assigns it a unique ID and creates a .meta file beside it containing that ID and the asset’s import settings. Other assets refer to it by that ID, which is how a prefab remembers which script or sprite it uses. If you move or rename an asset inside the Project window, Unity moves its .meta file too; if you do it in your operating system’s file browser, you must move the .meta file yourself. If an asset loses its .meta file, Unity generates a new one with a new ID, and every reference to the asset breaks: materials lose their textures, and GameObjects and prefabs show an unassigned script (Unity Technologies, Asset metadata, Unity 6.3 Manual).

Unity’s guide explains why these generated files belong in version control: import settings are written to the .meta file, not the asset, so committing them keeps everyone’s settings identical (Unity Technologies, Best practices for project organization and version control). The rule, repeated in git-github-unity, is always commit .meta files with their assets.

Empty folders are a related trap. Git ignores empty folders, but Unity creates a .meta file for every folder. A teammate can therefore pull a folder’s .meta file without the folder, and Unity will delete the orphaned .meta file. Unity’s guide suggests creating only the folders you need, or placing a .keep file in an empty folder so Git tracks it.

Other engines

Godot projects use res:// paths and keep import settings in .import files beside each asset; Godot’s documentation recommends snake_case for file and folder names, except C# scripts, which are named after their PascalCase class (Godot Engine documentation, Project organization). Unreal Engine stores assets as .uasset files and teams commonly use type prefixes (BP_, M_, T_). The underlying principles (agree a convention, keep third-party content separate, never break the engine’s asset IDs) carry over.

Gotchas

  • Renaming or moving assets outside Unity breaks references unless the .meta file moves with the asset. Do it in the Project window.
  • Renaming a script only in the code editor (class changed, file not) or only in the Project window (file changed, class not) leaves a mismatch; Unity warns, and components may show as missing.
  • A gameplay script inside an Editor folder compiles, but cannot be added as a component and is left out of builds.
  • Resources folders grow builds, because everything in them is included whether or not it is used.
  • Spaces in names cause problems for command-line tools and build scripts; avoid them from the start.
  • Committing empty folders with Git does not work; the folder’s .meta file arrives without it.
  • Reorganising late with Git loses file history for moved files unless Git detects the rename, and creates merge conflicts for anyone with open work. Agree the structure in week one.

Practice

Set up a team-ready project from scratch:

  1. In the Unity Hub, create a Universal 2D project called CoinCollector (no spaces).
  2. Create _Project (with Art, Audio, Prefabs, Scenes, Scripts), Sandbox and ThirdParty folders.
  3. Move SampleScene into _Project/Scenes using the Project window and rename it Level01.
  4. Create a script CoinPickup in _Project/Scripts, then a Coin prefab in _Project/Prefabs that uses it.
  5. Add a Unity .gitignore, initialise a Git repository and commit (see git-github-unity).

Success test:

  • the commit contains Assets/, Packages/ and ProjectSettings/ but not Library/ or Temp/
  • every asset and folder in the commit has a matching .meta file
  • CoinPickup.cs declares public class CoinPickup, and no file or folder name contains a space
  • after deleting Library/ and reopening the project, the Coin prefab still shows its CoinPickup component

Extension:

  • in a copy of the project, close Unity, move CoinPickup.cs to a different folder in your file browser without its .meta file, reopen Unity and observe what happens to the Coin prefab; then explain the result using the idea of asset IDs
  • write a one-page README.md for the repository that records your folder layout, naming rules and Unity version

Self-test

  1. Name two pieces of folder-structure advice from Unity’s own project organisation guide.
  2. What is one advantage of organising by feature rather than by type, and one advantage of organising by type?
  3. Why should a script’s file name match its class name?
  4. Which reserved folder name excludes its scripts from builds, and what else happens to a MonoBehaviour placed there?
  5. What does a .meta file contain, and what breaks if it is lost?
  6. Why should you move assets in the Project window rather than in your file browser?

Answers

  1. Any two of: define and document naming conventions and folder structure as a team; avoid spaces in file and folder names; keep internal assets separate from third-party ones; separate sandbox areas; avoid extra folders at the project root.
  2. By feature keeps all the parts of one feature in one folder, so it is easy to find, reuse or delete. By type matches Unity’s templates and tutorials and gives shared assets an obvious home.
  3. The file name becomes the class name when the script is created, and Unity uses the file name to find the class; it can resolve some mismatches but warns when it cannot match them unambiguously. Keeping them identical avoids missing components and confusion.
  4. Editor. A MonoBehaviour in an Editor folder cannot be attached to a GameObject as a component.
  5. The asset’s unique ID and its import settings. If it is lost, Unity generates a new ID and every reference to the asset breaks, for example materials lose textures and prefabs lose scripts.
  6. Unity moves or renames the .meta file with the asset automatically; in a file browser you must do it yourself, and forgetting breaks references.

External references

Graph View

Backlinks