Project Workflow¶

A Doriax project is the editable source for a game. It organizes scenes, resources, scripts, bundles, and export configuration into a single directory that the editor understands. The editor keeps visual authoring, code, and build settings clearly separated so teams can iterate and collaborate effectively.

Creating a project¶

Doriax does not display a startup dialog. When the editor launches, it reopens the last saved project if that project is still available. Otherwise, it opens a temporary project named MyDoriaxProject with a new 3D scene so you can begin editing immediately. File → New Project also replaces the current project with a fresh temporary project.

To keep a temporary project:

1. Choose File → Save Project.
2. Enter the project name, click Browse, and select an empty directory.
3. Click Save. The editor moves the temporary project into that directory and writes its project.yaml file.
4. Save the initial scene separately with File → Save or Ctrl+S, choosing a location inside the project directory.

Temporary projects are stored in the operating system's temporary directory. Save the project to another directory before relying on it as permanent work.

New projects begin with a 3D scene. To add a different scene type, choose File → New Scene → 2D Scene or File → New Scene → UI Scene. Doriax does not use project templates.

Project anatomy¶

Folder names may differ by project. The structure is a convention, not a strict requirement — you can reorganize asset folders and update resource paths accordingly.

Scene files¶

Scene files are serialized as YAML. They store the full scene hierarchy: entities, component data, transform values, camera settings, child scene references, and editor viewport state.

Keep scene files focused. For large games, split gameplay areas into separate scenes and compose them with child scene references. This keeps individual YAML files small and merge-friendly in version control.

Scene types¶

The editor offers three scene workflows:

All three share the same Scene class at runtime — the type mainly affects editor defaults and authoring tools. A 3D scene can contain UI entities, and a UI scene can reference 2D or 3D child scenes.

Child scenes¶

Child scenes let one scene reference and load another. This is useful for:

• Persistent UI layers — load a HUD scene as a child of the gameplay scene.
• Shared environment — a common lighting rig or skybox loaded by all levels.
• Level assembly — large worlds assembled from smaller room or chunk scenes.
• Streaming — load and unload sections independently at runtime.

To add a child scene reference, use the Structure panel's Add Child Scene option and point it to a saved scene file.

Bundles¶

Bundles are prefab-like reusable entity hierarchies. A bundle can represent an enemy, an interactive prop, a UI card, or any repeated arrangement of entities and components. They are defined visually in the editor and stored as YAML bundle files.

Why bundles?¶

Creating a bundle¶

1. Build the entity hierarchy you want to reuse in any scene.
2. In the Resources Browser, open the folder the bundle should be saved to.
3. Select the root entity in the Structure panel, right-click it and choose Save as Bundle — or simply drag the entity onto the Resources Browser.

Either way the editor writes <EntityName>.bundle into the open folder and replaces the hierarchy in the scene with an instance of the new bundle. Rename the file in the Resources Browser if you want a different name. A .bundle file can live in any project folder, so bundles/ is a convention rather than a requirement.

Placing bundles¶

Drag a .bundle file from the Resources Browser onto the Structure panel — drop it on the scene root, or on an entity with a Transform to parent the instance there.

Runtime bundle usage¶

Bundle registration is generated automatically by the export step. At runtime you call createBundle (bundle name first, then scene) and destroyBundle. Entity IDs are scene-local, so parent under an existing entity with createBundle(name, scene, "parentName") or pass an object that already carries its scene:

-- Create a bundle instance at runtime
local root = BundleManager.createBundle("enemy_grunt", scene)
-- Parent the new instance under a named entity in that scene
BundleManager.createBundle("enemy_grunt", scene, "spawn")

-- Destroy it later
BundleManager.destroyBundle(scene, root)

// Registration is normally emitted by export:
BundleManager::registerBundle(1, "enemy_grunt", [](Scene* scene, Entity parent) -> bool {
    // bundle factory body
    return true;
});

Entity root = BundleManager::createBundle("enemy_grunt", &scene);
BundleManager::createBundle("enemy_grunt", &scene, "spawn");

A bundle no scene instantiates is only built and registered while it is listed in Project → Bundles — see Bundles in the build.

See BundleManager for the complete API.

Settings¶

Shaders have no directory setting: each fork picks its own location when you create it, and compiled .sdat output always goes to the project's shaders folder. See Custom Shaders.

Assets and Lua directories¶

Project → Project Settings → Directories picks the two folders the running game reads from. Both default to <Project root>, which keeps the whole project as the root.

References are stored relative to these roots, not to the project. With the assets directory set to assets, a texture in assets/textures/hero.png is stored as textures/hero.png, which is exactly what the exported game finds next to its executable.

Changing either directory migrates the project in one step:

• referenced files that would fall outside the new root are moved into it, keeping their folder layout so a model still finds its .bin and textures;
• every reference is rewritten in scenes, bundles and .material files — scenes that are not open are loaded for the rewrite and closed again;
• if any file cannot be moved, every move is undone and the directories are left unchanged, so the project is never half-migrated.

Because a reference cannot leave its root, the editor only accepts assets from inside the assets directory: dropping a file from elsewhere previews it but shows a warning instead of assigning it. Maps painted in the Terrain editor and assets downloaded by the AI assistant are created under the assets root for the same reason. Moving a referenced file out of the assets directory clears the references to it, exactly like deleting it.

Script directories¶

The same Directories tab has a Script Directories list, which is about the C++ build rather than what the running game reads. Each folder you add is both an include root and a compile root: headers under it are included by the path below the folder, and every .cpp under it is compiled even when no entity references it.

The list starts empty, and only the folders you add are affected — a project without script directories builds exactly as before. Use Add to pick a folder and the trash icon to remove one. Keep them inside the project: an outside folder builds in the editor but is skipped when exporting.

See C++ Build Setup → Script directories for the full behaviour, and Customizing the build for ProjectBuild.cmake, which covers what this setting does not — linking libraries and other CMake of your own.

VSync¶

Open Project → Project Settings and use VSync to choose whether Play mode and supported desktop builds synchronize frames to the display refresh rate. It is enabled by default. Disable it when profiling the maximum frame rate; leave it enabled for normal use to avoid tearing and unnecessary GPU load.

The value is saved as vsync in project.yaml and travels with the project. Older projects without the field default to enabled.

Window¶

Open Project → Project Settings to control the OS window that desktop builds create at startup:

The values are saved as windowMode, windowWidth, windowHeight, windowResizable, and windowTitle in project.yaml and travel with the project. Projects saved before these fields existed start windowed at their canvas size.

Fullscreen starts the game on the primary monitor at the current desktop video mode (borderless-style, no display mode switch) and falls back to windowed when no monitor is available. Scripts can still toggle fullscreen at runtime with requestFullscreen / exitFullscreen; leaving fullscreen restores the configured window size.

Save strategy¶

• Save scenes after structural edits (Ctrl+S).
• Save project settings after changing export configuration.
• Keep generated export output outside the source project folder.
• Commit human-authored files (scenes, scripts, assets) to version control; ignore local build folders and generated C++ glue.