# 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:

```bash
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. Before launch, the wrapper runs an
incremental build of both editor binaries through the persistent managed Cargo lane and its storage
pre/postflight. The splash reports exact resolved-crate progress, and any build or storage-preflight
failure remains visible with an actionable log instead of launching a stale executable. An explicit
`~/.local/bin/blacksite-editor --build-only` performs the same managed update without opening a GUI.
If an editor is already running, the wrapper still performs that update check before focusing it.
When Cargo replaced the executable, the running process is deliberately left untouched to protect
unsaved authored documents; the splash and desktop notification explicitly ask for a normal
close-and-reopen instead of implying that the old process already contains the rebuilt UI.

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](../adr/0025-project-root-is-a-startup-boundary.md) for why project switching must
cross a process boundary.