Blacksite/docs/editor/project-launcher.md

Project Launcher And Sandboxes

Blacksite treats the project root as a pre-engine startup choice. The root must contain a valid assets/project.ron; its default level must be project-relative, exist, and pass the shared scene validator before the editor constructs AssetPlugin or loads project content.

Use an explicit root from the command line:

cargo run -p editor --features dev -- --project /path/to/project
cargo run -p editor --bin project_launcher --features dev

Omitting --project preserves direct-open behavior for the current working directory. Invalid or unknown arguments fail before GPU initialization with an actionable terminal error.

Manifest identity

New manifests include:

• project_id: stable UUID or repository-owned identifier;
• project_kind: Game or Sandbox;
• template_version: scaffold/template compatibility version;
• capabilities: forward-compatible feature tags;
• default_level: regular .scn.ron initial authored scene under assets/levels/.

New manifests include the audio capability, assets/audio asset root, and the validated Master, Music, and SFX bus graph. Bus references use the stable IDs master, music, and sfx; labels are presentation only.

Older manifests remain readable through serde defaults. The launcher uses a non-persisted legacy path identity when an old manifest has no project_id.

Sandbox contract

Sandbox creation only accepts a missing or empty destination. It creates the standard audio, levels, materials, meshes, models, rendering, shader, texture, registry, and trash directories; a schema-current empty assets/levels/main.scn.ron; a transactional sandbox manifest; and development, QA, and release profiles under assets/build_profiles/ targeting that scene. The project remains content-only: editor packaging runs from the installed engine workspace while passing this project root explicitly. Scaffolding never merges into a non-empty directory.

Recent projects remain user-local. Missing, invalid, and duplicate roots are removed from launcher presentation, and the last scene is shown only when it still exists under that project root.

Switching and desktop launch

File > Switch Project... writes a clean editor session, starts the Project Browser as an independent process, and exits. Opening a recent or browsed project performs the reverse handoff: the browser exits only after a new editor process has been accepted by the user's service manager. This keeps renderer, asset server, import registry, and project settings rooted consistently.

On the supported Linux workstation, the Blacksite Editor desktop entry provides an Open Project Browser action. Its wrapper launches the current managed development binary directly, shows the normal startup splash, avoids duplicate processes, and preserves the Wayland, session-bus, graphics, and XDG environment required by the detached process. A desktop click never invokes Cargo. An explicit ~/.local/bin/blacksite-editor --build-only rebuild uses the repository's managed Cargo lane; a missing binary produces an actionable splash error instead of starting an implicit build.

The browser's New Sandbox workflow requires a missing or empty folder and a non-empty name. Creation failures remain in the browser as status text; a successful scaffold is validated and opened through the same process handoff as an existing project.

See ADR 0025 for why project switching must cross a process boundary.