72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
# 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.
|