Proposal: Project Folder Structure + Project Description File

[miogds]

Now that we are close to having a functional editor, I believe it’s time to define how the project structure and description file should work. The goal is to make the editor independent, organized, and capable of handling projects in a consistent way across macOS and VisionOS.

---

🔑 Motivation

• Previously, the asset folder needed to be configured even in play mode, which made sense when the editor was part of the game project. But now that the editor is its own entity, we should rethink the system.
• A clear project structure will allow us to test and preview games directly in the editor before deployment or build.
• Introducing a project configuration file and structured folders ensures consistency, portability, and extensibility.

---

📂 Proposed Changes

1. Project File (JSON format, initially)

• When a folder is opened, the editor will look for a project.json file.
• This file will include configuration and engine/project-related metadata.
• Scene file format remains as is, but supports multiple scene files (e.g., portals, multi-area loading, level transitions).

2. Flattened Standardized Folder Structure

All resources are tied to the root project folder. The asset browser always points to this root.

Proposed folder layout:

/<ProjectRoot>
  /Models       → 3D models
  /Textures     → Images, textures, materials
  /Audio        → Music, SFX, voice
  /Scenes       → Scene files
  /Scripts      → Game logic (events, bindings, entity behavior; testing without Xcode)
  /Plugins      → Components, extensions, editor/runtime plugins
  project.json  → Project configuration & metadata

• External assets must be imported → they are copied into the correct folder (e.g., Models, Textures).
• Scenes are grouped in /Scenes and can be organized for multi-scene setups.

3. Editor Behavior

• The editor should be able to preview and run the game directly from the project folder before build/deploy.
• Plugin system (components, extensions, behaviors) will be supported via the /Plugins folder.
• For now: only one project open at a time. (Multi-project support can come later.)

4. Deployment & Release Workflow

• When preparing to deploy or create a release version, the editor will:
  • Generate an Xcode project.
  • Bundle all resources and code from the project folder.
  • Inject necessary glue code for the engine/runtime.
  • Strip out editor-related files (keeping only what’s needed for the final game).
• The generated Xcode project can then be used to publish directly to the App Store or distribute via TestFlight.

---

✅ Benefits

• Consistency: All resources and metadata are tied to the project root.
• Portability: Projects are self-contained and easy to move/share.
• Extensibility: Plugins and scripts can be dropped into their respective folders and loaded by the editor.
• Cross-platform readiness: Ensures parity for macOS and VisionOS development/testing.
• App Store integration: Smooth path from project → Xcode → release, without manual restructuring.

---

📌 Next Steps

• Define the project.json schema (minimum fields to support editor + runtime + deployment metadata).
• Finalize conventions for asset importing (e.g., file type detection → place in Models, Textures, etc.).
• Separate discussions for:
  • Plugin/component system
  • Script/code integration
  • Release workflow details (entitlements, signing, App Store packaging)

---

👉 What do you think?

[untoldengine]

Love this!!!

I want to give a bit of context on why I originally added the external folder option.

Back then, I mainly wanted to test runtime asset importing inside the editor. The way I set it up was honestly a bit crude — it worked, but it also meant that before shipping, devs would still need to manually copy everything into the app’s main bundle. It wasn’t an ideal workflow, just a quick way to validate that runtime importing could work.

That’s why I really like your proposal with the project root + project.json setup — it feels much cleaner and more future-proof. 👍

Just to make sure we’re on the same page, could you help me confirm two things?

• Runtime importing – With the project root as the source of truth, will we still be able to drag in/import assets at runtime and have them copied into the right folders (e.g., Models/, Textures/) and re-indexed by the editor?
• No manual copying – For shipped builds, will the runtime asset resolver look first in a writable user data directory and then fall back to the bundled assets, so game devs don’t need to manually copy resources into the main bundle anymore?

If both of those are covered, then this basically solves the pain point I was trying to hack around in the first place. Really excited about where this is heading!

[miogds]

The answer is yes to both questions.

[miogds]

Project File & Folder Structure Proposal (First Draft)

This is my first draft proposal for how we should organize project files and folders.
It can evolve as the engine grows and as new features are needed, but I think it’s important to start with a strong foundation and a clean structure.

---

Goals

• Keep a tight and consistent project structure.
• Make it easy to work collaboratively in the editor, through version control, and when resolving conflicts.
• Separate editor workflow from runtime/deploy workflow.
• Allow flexibility to grow into future needs while keeping things simple at the start.

---

Two Types of Resource Storage

I propose supporting two complementary ways of handling resources (models, scripts, etc.):

1. Editor-Friendly Format

• Text-based whenever possible (scenes, models, configs).
• Binary only when unavoidable (textures, images).
• Editor extracts imported assets into structured folders (Scenes/, Models/, Textures/, etc.).
• Uses .usda (text USD) for human-readable version-control-friendly files.

2. Runtime / Deploy Format

• Bundled and optimized for speed.
• Entire scenes packaged into .usdz (binary USD bundle).
• Assets converted to engine-optimized formats (e.g. PNG).
• Scripts compiled into runtime code.

---

Example Folder Structure

ProjectRoot/
│
├── Scenes/
│   └── car_scene.usda
│
├── Models/
│   └── car_scene/
│       ├── car.usda
│       └── player.usda
│
├── Textures/
│   └── car_scene/
│       ├── car_diffuse.png
│       └── player_diffuse.png
│
├── Scripts/
│   └── car_scene/
│       ├── car_behavior.script
│       └── player_ai.script
│
├── Project.json        # Main project file, references main scene & bindings
└── /EditorResources    # Editor-only bundles, metadata (not shipped in runtime)

---

File Formats Overview

• Editor:

  • .usda for scenes and models.
  • JSON for project definitions.

• Runtime / Deploy:

  • .usdz for complete scenes.
  • Optimized binary assets.
  • Compiled scripts.

---

Benefits

• Team collaboration: Modular entities prevent merge conflicts.
• Clarity: Every asset lives in a predictable location.
• Performance: Runtime bundles are optimized for speed.
• Scalability: The format adapts to future engine features.

---

Closing Note

This is only the first draft — it will evolve as we experiment and discover new needs.
But this dual-path approach (editor vs runtime) gives us both collaboration-friendly workflows and optimized builds for deployment.

---

@untoldengine What do you think?

[untoldengine]

Love this.

A couple of ideas, why don't we plan for the future and also add:

Audio
Shaders

Also, why don't we include a Resources or Assets folder? It keeps the project clean and separates engine/editor internals from game data, e.g.:

ProjectRoot/
├── Assets/
│ ├── Scenes/
│ ├── Models/
│ ├── Textures/
│ └── Scripts/
├── Project.json
└── EditorResources/

Overall, I like the proposal.

[untoldengine]

I thought about it. Disregard my Assets/Resources suggestion. I like the structure you have better.