Project folder layout proposal: Resources, Assets, Docs, Sources, GameData

[miogds]

I would like to propose a new folder structure for the projects the editor (and untoldengine create) generate. The short version: today a project mixes the artist's sources, the engine's assets and generated files in one tree, three levels inside the code, surrounds them with empty folders, and ships files in the app that the engine never reads. I propose four folders at the root, each with one owner. GameData keeps its name and its content and moves to the root; the runtime does not change.

Why

This is what a project looks like today, as the BuildSystem creates it and the editor completes it on open:

MyGame/
├── Package.swift                  (macOS only)
├── README.md
├── project.yml
├── MyGame.xcodeproj/
└── Sources/
    ├── MyGame/
    │   ├── AppDelegate.swift, GameScene.swift, GameSceneUtils.swift, Info.plist, ...
    │   └── GameData/
    │       ├── Animations/  Gaussians/  HDR/  LUT/  Materials/  Models/
    │       ├── Scenes/  Scripts/  Shaders/  StreamModels/  Textures/
    └── MyGamePlugins/

What I run into with it, measured on my own project (one model pack of 375 models, visionOS):

• Noise. Eleven category folders under GameData, ten of them empty. An artist or a designer opening the project has no idea where their files belong, and the one folder that matters is three levels deep inside the code tree.
• Sources live next to outputs. When I import a .blend, the editor copies it into GameData/Models/<Name>/ and the cook writes the .untoldpack beside it. The .blend is 96 MB. Since project.yml bundles the whole GameData folder, that .blend ships inside the app, together with every other working file I drop there. The browser hides the source folder now ([Patch] Hide cook-source folders in asset browser #154), but the files are still bundled.
• No home for the rest of the project. Reference images, high-poly meshes, PSDs, design documents, notes about the implementation: none of them has a place. They either end up in GameData (and get bundled) or outside the repository.
• Nothing says what is generated. No .gitignore is written, so the Xcode project, .build/, DerivedData/ and the bundled copies all look like they belong in version control. The generated README documents main.swift, GameRuntime.swift and .json scenes, which the template does not produce.
• The layout is written down in five places. The category list exists in the engine's BuildSystem, in the editor's open code, in the asset browser, in the asset pack browser and in the docs (which miss LUT). The chain Sources/<Name>/GameData is repeated in both repos, and the project root is found by walking three levels up from it.

Proposal

MyGame/
├── .gitignore                MyGame.xcodeproj/, .build/, DerivedData/, xcuserdata/, .DS_Store, *.blend1
├── README.md                 describes these folders
├── project.yml
├── MyGame.xcodeproj/         generated from project.yml; ignored
├── Docs/                     everything written about the game: design, implementation notes, decisions
├── GameData/                 what the engine reads; the editor's asset root; bundled as it is
│   ├── Models/               Tower.untoldpack + Tower/ (payload .untold files, Textures/, HDR/)
│   ├── Scenes/               .untoldscene
│   ├── Scripts/              .uscript
│   └── ...                   the same categories as today, created when the first file goes in
├── Resources/                what the tools work from: .blend, .usd, PSDs, high-poly meshes, references; never bundled
│   └── Models/Tower/Tower.blend     where the editor's import puts a source; free below Resources/
└── Sources/
    ├── MyGame/               the app target: App.swift or AppDelegate, GameScene.swift, Info.plist, ...
    └── MyGamePlugins/        code components

Folder	Holds	Written by	Read by
Resources/	Files that produce assets but are not assets. Never bundled.	Artists, designers	Blender, the exporter, the editor's cook
GameData/	Every file the engine can load. Same name, same categories, same content as today.	The editor	The editor, the app
Docs/	Documentation of the game.	Everyone	People
Sources/	Code only.	Developers	Xcode

Compiled output stays where Xcode and SwiftPM put it. There is no build folder in the project.

My project after the change: the .blend in Resources/Models/EDIFICIO_COMPLETO_BLOCKING/, tracked and never bundled; the pack and its payload folder in GameData/Models/; GameData/Scenes/ once a scene is saved; no other category folder on disk. The app bundle is the same as today, minus the .blend.

What stays the same

• The runtime. project.yml bundles GameData as a folder reference and the app looks it up by name, exactly as today. assetBasePath points at the same folder in the editor, scene references stay relative to it, the category names are the same. Every doc page that says GameData stays true; only the path prefix changes.
• The cook. A cook still writes the result into the category folder and the payload folder beside it, so the .untoldpack convention and the browser rule from [Patch] Hide cook-source folders in asset browser #154 are untouched.
• Re-cooking finds its source. [Bugfix] Asset Browser shows cluttered/confusing source folders alongside .untoldpack files #152 called the source-beside-pack convention intentional for that reason. Here the source has a deterministic place (the mirrored path under Resources/), and the pack manifest already carries a sourceAsset field, today a bare file name that nothing reads. Written as a path relative to the pack, it points at the source wherever it is. Resources/ would show in the browser as a second root, so cooking from a source stays one click.
• Existing projects. A project whose GameData is still under Sources/<Name>/ is treated as the current layout and works as it does now. Moving to the new one would be an explicit command (Convert Project Layout… in the editor, untoldengine convert on the CLI) that moves the folder and the sources, rewrites project.yml and the pack manifests, writes the .gitignore and logs every move.

What would change

1. Engine: the templates and the XcodeGen spec (bundle GameData from the root), a ProjectLayout type that both repos use instead of the five lists, .gitignore and a correct README at creation, update and assets install finding the root GameData, the convert command, the path prefixes in the docs. The SwiftPM variant needs its target at the project root so it can bundle GameData from there (to verify), otherwise it would go, since only macOS ever had it.
2. Editor: open and create through ProjectLayout, imports of sources into Resources/, cooks into GameData/, re-cook through sourceAsset, the convert command, and the script package the editor generates for USC scripts moved out of the asset tree (today it is bundled with its own .build/).
3. Exporter: sourceAsset as a relative path (one line; the reader accepts both forms).

Three PRs, engine first since the editor pins the engine's develop. I estimate three to four days in all.

Open points

• Category folders created on demand, or all of them at creation as today. On demand is what removes the noise; Finder users lose the preview of the categories, the browser keeps it.
• The generated .xcodeproj ignored (it is regenerated by xcodegen and by the editor on open; the engine's own sample project ships without one) or tracked.
• Whether a project needs the engine's metallibs in a Shaders/ folder at all; my project runs with that folder empty, since the runtime falls back to the engine's own bundle.
• Whether untoldengine update keeps a role for new projects (pulling assets from an external folder into GameData) or serves existing ones only.

If this direction makes sense, I would prepare the engine PR first (templates, layout type, docs), then the editor one.

[untoldengine]

📦 New project layout: Resources vs. GameData — now testable

We've reworked how projects are organized and how the Asset Browser handles imports. Here's what's changing and how to try it.

The big idea

Projects now have two clearly separated folders at the root:

• Resources/ — where your source files live: .blend, .usd*, .ply, .spz. These are never shipped in the final app. Organize this folder however you like — it's free-form, no required structure.
• GameData/ — cooked, ready-to-run assets: .untold, .untoldanim, .untoldgs, scenes, scripts, etc. This is what the game actually loads at runtime.

Previously these lived mixed together. Now the split is explicit, both on disk and in the editor.

How the new workflow feels

1. Import a .blend or .ply file (there's a single "Import…" button at the top of the Asset Browser sidebar now) — it lands in Resources/, staged but not cooked yet.
2. Right-click it and choose how to cook it: Model, Animation, or Tiled Stream Model for a .blend/USD source; .untoldgs for a .ply/.spz capture.
3. The cooked result shows up automatically in the matching GameData category.

If you already have a cooked file (say, a .untold someone shared with you), the same Import button recognizes it and drops it straight into GameData — no staging needed, since there's nothing left to cook.

The first time you import a single file, you'll see a one-time reminder that it landed in Resources and how to cook it, with a "don't show again" option.

Asset Browser sidebar changes

The sidebar now groups things under two destinations — Resources and a collapsible GameData (holding the same categories as before: Models, Animations, Scripts, etc.). Empty folders show a short hint about what belongs there instead of a blank panel, and a breadcrumb above the file list tells you which tree you're browsing, since Resources and GameData can have same-named folders.

Converting an existing project

If you have a project from before this change, convert it in place from the terminal:

untoldengine convert /path/to/YourProject

This restructures it into the new layout without touching your assets. You don't have to convert immediately — older projects keep working as-is, they just won't have a Resources/ folder until you do.

Want to try it now?

This is still in testing before merging to develop:

• Engine PR: [Project Layout] Root-level GameData/Resources/Docs project layout UntoldEngine#1345
• Editor PR: [Project Layout] Resources/GameData workflow in the Asset Browser #175

Feedback welcome — especially anything that feels confusing about where things land or how to organize Resources/.

[miogds]

Maybe, we can add another tab to the editor, the resources tab which you can see and search for the sources, the blend file for example, and in the asset tab we keep everything organized. ( the GameData folder )