# 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 builds both editor binaries into the shared target directory,
shows the normal startup splash, avoids duplicate browser processes, and preserves the Wayland,
session-bus, graphics, and XDG environment required by the detached process.

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.