Project Folder Structure

A workspace is the whole project folder: the Unity project, the assets around it, the builds, the documents. Everything for one game, in one place.

The one idea

Raw, Source and Exported mirror each other on purpose. The same asset keeps the same place
at every stage, so finding the source of an exported file is never a search. It is the same path
with one word changed.

Assets/Source/Meshes/Prop/Furniture/SM_Prop_Furniture_Table_01.blend
             └──────────┬─────────┘
Assets/Exported/Meshes/Prop/Furniture/SM_Prop_Furniture_Table_01.fbx
Stage Holds Who edits it In version control?
Raw Unprocessed captures: field recordings, gameplay footage, screen recordings Whoever recorded it No, use Q-Dex / Bubbly Backup
Source The working files you open and edit: .blend, .psd, .flp, InstaMat and Substance graphs The asset's owner Yes, via LFS
Exported What the game loads: .fbx, .png, .wav Nobody, it is generated Yes, but never hand-edited

Where does my file go?

The practical question. The name answers it. See The name decides the folder below for why.

File Goes in
SM_Prop_Furniture_Table_01.blend Assets/Source/Meshes/Prop/Furniture/
SM_Prop_Furniture_Table_01.fbx Assets/Exported/Meshes/Prop/Furniture/
SM_Kit_AbandonedTavern_01_Door_01.blend Assets/Source/Meshes/Kit/AbandonedTavern/
T_Surface_Wallpaper_01_Albedo.png Assets/Exported/Textures/Surface/Wallpaper_01/
T_Trim_AbandonedTavern_01_Albedo.png Assets/Exported/Textures/Trim/AbandonedTavern_01/
T_Sprite_Menu_Btn_01.png Assets/Exported/Images/UI/, not Textures
AU_SFX_Wpn_Shotgun_01_Fire_01.wav Assets/Exported/Audio/
M_Surface_Wallpaper_01 The Unity project, under the game's own Materials → Materials > Where they live
The number: meshes drop it, textures keep it

A kit's mesh folder is the Set alone: Kit/AbandonedTavern. A texture set's folder is the
Set and its number: Trim/AbandonedTavern_01.

Not a typo in either direction. A mesh subfolder groups a whole kit; a texture subfolder groups one
texture set, and a kit can have several. This is the single most common thing people get backwards.

The tree

Read the markers:
● Required. Missing it reports WSP001.
folders only No loose files at this level (WSP003).
closed No folders beyond those listed (WSP002).

The root

[WORKSPACE]/                    the folder is yours to name
├── Unity/                    ● folders only
├── Assets/                   ● folders only · closed
├── Builds/                     folders only, ignored by version control
├── Documents/                ●
├── Asset Bundles/            ●
└── Outreach/                   folders only

Builds/
└── [VERSION]/
    └── [PLATFORM]/

Outreach/
├── Kickstarter Campaign/
├── Steam Page/
└── E-Mail Campaign/

Unity

One folder per Unity project, named after the project.

Unity/
└── [PROJECT NAME]/
    └── Assets/               ●
        ├── Bubbly Games/     ●   our shared code, tools and scene templates
        └── Games/            ● folders only
            └── [GAME NAME]/
                ├── Scenes/       ●
                └── Resources/    ●
                    └── [GAME NAME]/

M_ materials live in here too, under the game's own Materials folder, not under Assets/.
→ Materials > Where they live

Assets / Raw

Captures, before anyone has touched them. Not in version control. This is the one branch of the
tree that lives elsewhere.

Raw/                          ● folders only · closed
├── Audio/
│   └── Sounds/
│       └── Field Recording 12_05_26 - Cucumber/
└── Videos/
    ├── Gameplay Footage/
    ├── Screenrecordings/
    └── Behind the scenes/

Field recordings belong in Q-Dex so they are searchable; large media in Bubbly Backup.

Assets / Source

The files you actually open and edit.

Source/                       ● folders only · closed
├── Audio/
│   ├── Music/
│   ├── SFX/
│   ├── Ambience/
│   ├── UI/
│   └── Voice Over/
├── Materials/                    InstaMat and Substance Designer graphs
│   ├── InstaMat/
│   └── Substance Designer/
├── Meshes/                     folders only · closed
│   ├── Character/              folders only
│   ├── Effect/                 folders only
│   ├── Kit/                    folders only, one folder per SET
│   │   └── AbandonedTavern/
│   │       ├── SM_Kit_AbandonedTavern_01_Door_01.blend      ← active
│   │       ├── SM_Kit_AbandonedTavern_01_Door_01_V1.blend
│   │       └── SM_Kit_AbandonedTavern_01_Door_01_V2.blend
│   └── Prop/                   folders only, one folder per SubCategory
│       └── Furniture/
│           └── SM_Prop_Furniture_Table_01.blend
└── Videos/
Source/Materials keeps its name on purpose

It holds the InstaMat and Substance Designer graphs, the source files that generate a texture
set. That is material authoring, which is what the folder says. It is not the same thing as
Exported/Materials, which was a misnomer and is now Exported/Textures.

Assets / Exported

What the game loads. Generated, never hand-edited.

Exported/                     ● folders only · closed
├── Audio/
├── Images/
│   ├── Icons/
│   ├── Paintings/
│   └── UI/
│       ├── Shared/
│       └── Specific/
│           ├── Main Menu/
│           └── Health Bar/
├── Textures/                   folders only · closed, one folder per texture CATEGORY
│   ├── Surface/
│   │   ├── Wallpaper_01/
│   │   │   ├── T_Surface_Wallpaper_01_Albedo.png
│   │   │   ├── T_Surface_Wallpaper_01_Normal.png
│   │   │   └── T_Surface_Wallpaper_01_Roughness.png
│   │   └── OldChair_01/
│   ├── Cutout/
│   │   └── Leaf_01/
│   ├── Trim/
│   │   └── AbandonedTavern_01/
│   ├── Mask/
│   │   └── OldChair_01/
│   └── Effect/
│       └── Smoke_01/
├── Meshes/                     folders only · closed, mirrors Source/Meshes exactly
│   ├── Character/
│   ├── Effect/
│   ├── Kit/
│   │   └── AbandonedTavern/
│   │       └── SM_Kit_AbandonedTavern_01_Door_01.fbx
│   └── Prop/
│       └── Furniture/
│           └── SM_Prop_Furniture_Table_01.fbx
└── Videos/
Sprite is missing from Textures/ on purpose

It is a perfectly legal texture category, but UI art has its own pipeline and lives under
Exported/Images/UI, split Shared and Specific. A sprite filed under Textures/ is a
misfile even though Sprite is a valid category. The placement rule leaves it
out on purpose, so the check does not report every sprite in the project.

The name decides the folder

There is no lookup table in between

Under Meshes and Textures, the Category token in a name IS the folder name. That is why the
folders are Kit and Surface rather than Kits and Surfaces. The token and the folder are one
string, so there is nothing in the middle to drift.

Then one level down:

Root Folder below the category comes from
Source/Meshes, Exported/Meshes the SubCategory, or the Set for a kit
Exported/Textures the Set + SetNum, or Descriptor + Num if there is no Set

Only the first folder below the category is checked. What you do below that is open, because
nothing in the rules can judge whether Furniture wants a Tables folder inside it.

WSP005 checks the pair, and it is the one check that needs two facts to disagree before it says
anything: a legal name, a legal folder, and the two still wrong.
SM_Prop_Furniture_Table_01.blend sitting in Meshes/Kit is nobody's typo, and nothing else
catches it.

What the checker enforces

rules

Key Value
WSP001 title: Required folder is missing; severity: warning
WSP002 title: Folder is not part of the defined structure; severity: warning
WSP003 title: Loose file where the structure expects only folders; severity: warning
WSP004 title: Manual version file is not the _V1 form; severity: warning
WSP005 title: Asset is not in the folder its name requires; severity: warning
WSP006 title: Asset name carries nothing to place it by; severity: warning

In plain terms:

Rule Fires when What to do
WSP001 A required folder does not exist Workspace Check can create the empty folders for you
WSP002 A folder exists that the structure does not list Rename it to one that is listed, or propose adding it to the rules
WSP003 A loose file where only folders belong Put it in the subfolder its name calls for
WSP004 A _V2 with no unsuffixed active file beside it The active file is the one without a suffix (see below)
WSP005 The file's name says it belongs somewhere else Move it, or fix the name. Decide which one is actually wrong first.
WSP006 The name carries nothing to place the file by A rename, not a move. The name needs a SubCategory or a Set.

Everything is a warning today. They report; they do not block. They harden to errors once the
existing backlog is cleared, so a warning now is a build failure later.

Why the closed levels are closed

Meshes allows exactly four folders and no loose files, and those are two halves of one rule. A
fifth folder there is either a category the studio now has (which belongs in the rules, where every
project gets it) or a misspelling of one of these four. Props sitting beside Prop went
unreported for as long as that level stayed open.

Where these checks apply

fileChecks

Key Value
nameRoots Assets/Source, Assets/Exported, Unity/*/Assets/Games
metaRoots Unity/*/Assets
extensions .fbx, .blend, .obj, .png, .tga, .exr, .psd, .psb, .jpg, .jpeg, .tif, .tiff, .wav, .mp3, .ogg, .aiff, .mat, .prefab, .unity, .anim, .controller, .asset, .vfx, .shadergraph, .shader, .sbs, .sbsar, .spp
ignore *.blend1, *.blend2, readme*, *.lnk, thumbs.db, desktop.ini

Not everywhere. Blanket-checking every file under a Unity project would bury one real finding under
ten thousand names from a third-party package nobody here wrote. So the roots are named rather than
assumed.

Files that never count as clutter

structureIgnore

Key Value
files *.blend1, *.blend2, thumbs.db, desktop.ini

A .blend1 is Blender's autosave of the .blend beside it. It appears and disappears on its own,
nobody chose to put it there, and there is exactly one per real file. On a folder of 30 meshes it
would double the report with rows nobody can act on. That is how a check gets ignored.

A readme is excused from the naming grammar, because it is not an asset. But a readme sitting
among the category folders is still a structural mistake and still reports.

Manual file versioning

Optional, and not needed. Version control keeps a full history and you can always go back or pull an
old version. If you do keep manual copies (which costs some disk and nothing else), there is one
rule:

The active file is always the one with no suffix.

SM_Kit_AbandonedTavern_01_Door_01.blend      ← active, always
SM_Kit_AbandonedTavern_01_Door_01_V1.blend
SM_Kit_AbandonedTavern_01_Door_01_V2.blend

versionSuffix

Key Value
activeHasNoSuffix true

Pattern: _V\d+$

That way nothing has to be renamed when you make a new version, and every link, reference and
importer keeps pointing at the right file. WSP004 reports a _V2 with no active file beside it.

What changed on 2026-09-12

Folders were renamed and removed
  • Meshes/Environment, Meshes/Tools, Meshes/Characters and Meshes/Effects are gone. The
    category folders are now exactly Character, Effect, Kit, Prop: singular, matching the
    tokens.
  • Exported/Materials is now Exported/Textures, with one folder per texture category. It
    never held materials; the misnamed folder was most of the reason nobody could say where a material
    goes. Real M_ materials live in the Unity project (see Materials).
  • Source/Materials keeps its name. It holds the InstaMat and Substance Designer graphs.

Old names still fail, and the error message names the replacement.
→ Naming Conventions > Which category is it

See also