45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
# ADR 0028: Authoritative project content validation
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
Scene, prefab, and imported-asset checks were distributed across editor loading, hydration, and the
|
|
`validate-levels` task. A project could therefore pass headless scene validation while still
|
|
containing a missing model, texture, material, shader, generated mesh manifest, post effect, or
|
|
rendering profile reference. Editor-only validation would also risk disagreeing with CI and release
|
|
tooling.
|
|
|
|
## Decision
|
|
|
|
The Bevy-free `scene` crate owns `validate_project` and the structured
|
|
`ProjectValidationReport`. The report contains a deterministic dependency manifest and findings
|
|
with severity, stable code, source document, owning `ActorId` where available, referenced path,
|
|
message, and repair action.
|
|
|
|
Both the editor Diagnostics window and the `cargo validate-levels` headless command call this same
|
|
entry point. The command supports `--project <path>` and `--json`; the editor can select the live
|
|
owning actor for an attributed finding. Blocking errors produce a nonzero headless exit status.
|
|
|
|
Project validation covers the project manifest and asset roots, registry IDs/sources/dependencies,
|
|
generated static mesh manifests, material and shader documents, post effects, scene and prefab
|
|
graphs, authored model/material/texture/brush/collider references, rendering profiles, and
|
|
unhydrated Git LFS pointer files. The validator owns the runtime-packageability predicate consumed by
|
|
the packager: editor/hidden trees, source-authoring formats, symlinks, and unreadable traversal are
|
|
blocking rather than being accepted and later omitted. The project default must be a regular
|
|
`.scn.ron` file under `assets/levels/`, which guarantees the full document dependency pass audits the
|
|
startup entrypoint. Unknown newer scene schemas are rejected rather than down-stamped. Platform
|
|
requirements are explicit findings; for example, Solari projects record the required forward-path
|
|
fallback QA when ray tracing is unavailable.
|
|
|
|
## Consequences
|
|
|
|
- Headless and editor validation share result semantics and finding ownership.
|
|
- Missing references are visible before Bevy hydration attempts to load them.
|
|
- Release packaging invokes this report before and after compilation and refuses blocking errors;
|
|
Gitea #44 acceptance verifies the shared gate against real development output.
|
|
- Asset formats added later must register their dependencies with this validator and extend the
|
|
valid, missing, cyclic, and incompatible project-fixture matrix.
|