In planning my reusable game dev library, BF Tools (more on that in a future article), I learned a new trick. Unity has a naming convention for excluding folders from asset import entirely: a ~ at the end of a folder name.
How It Works
If a folder name ends in ~, starts with ., or is wrapped in (), Unity’s AssetDatabase ignores it. The folder still exists on disk inside your project directory. Unity just never scans it, never generates .meta files for it, and never shows it in the Project window.
The ~ only works on folder names, and only at the end. Docs~ gets excluded. File~Name.cs does not. Unity imports that file normally, ~ and all.
What It Actually Excludes
The ~ trick skips one specific step: AssetDatabase import.
The AssetDatabase processes every file in your Assets folder. This turns a raw file on disk into something Unity can actually use. A .png becomes a Texture2D. A .cs file gets compiled into a script Unity can attach to a GameObject. A .fbx becomes a mesh with importable settings.
Part of that process is generating a .meta file for every asset. The .meta file holds a GUID, a unique ID Unity uses to track that asset internally. That GUID is how references stay linked even if you rename a file. Scene references and prefab references point to the GUID, rather than the file path.
The Project window is a live view of everything the AssetDatabase has imported. If a file was never imported, it never shows up there. Unity generates no GUID for it. As far as Unity is concerned, the file doesn’t exist.
That’s the mechanism a ~ folder skips. Unity never scans, converts, GUID-tags, or lists anything inside it. It sits on disk as plain files and nothing more.
Not a Build Exclusion
Unity’s Player build doesn’t scan your whole Assets folder to decide what to include. It includes whatever is referenced by your scenes, placed in a Resources folder, or pulled in through Addressables. A ~ folder is invisible to the AssetDatabase, so nothing inside it can be referenced by a scene in the first place. The exclusion happens a step earlier than the build even runs.
Not a Domain Reload Exclusion
Domain reload during Enter Play Mode recompiles and reloads C# assemblies. It has nothing to do with asset import. A ~ folder doesn’t speed up or change domain reload, because domain reload never touches it either way.
Where This Is Actually Used
UPM Packages
If you’ve looked inside a Unity package, you’ve probably seen Documentation~ or Samples~ folders. Package authors use these to ship markdown docs, screenshots, or example scenes without Unity reserializing those files as assets when you add the package to a project. Samples~ is a documented Unity convention specifically. Content in there won’t auto-import, but the Package Manager can still copy it into a project when a user clicks “Import” on a sample.
Scratch or Tool-Output Folders
If an external tool dumps intermediate files into your project directory (build logs, generated code, cache files), putting that output folder under a ~ name keeps Unity from trying to import and reserialize all of it every time the tool runs.
Work-in-Progress Content
Anything you’re actively editing that you don’t want Unity re-importing on every save can sit in a ~ folder. It stays inside the project directory, your repo still tracks it, and it’s still easy to find, without the import overhead.
Example
Assets/
MyPackage/
Runtime/
Editor/
Documentation~/
GettingStarted.md
screenshot1.png
Samples~/
BasicExample/
Unity imports Runtime and Editor. They show up in the Project window. Documentation~ and Samples~ don’t. They’re on disk, they’re in source control, but Unity doesn’t know they exist until you rename them.
Where I’m Using This
I am leaning on this convention for development of BF Tools. This way I can keep documentation and sample scenes packaged alongside each system without cluttering the AssetDatabase.
I’m still finding these Unity conventions after years of using the engine. That either says something about Unity’s documentation or something about how much I still have to learn. Probably both. If you’ve got other obscure Unity tricks worth knowing, I’d like to hear them. Drop them in the comments.
0 Comments