Crucible · Beginner · Tutorial 1 of 3
Four things wrong with your manifest,
and it still passes.
Crucible validates a mod every time a scene loads, and produces a wall of findings that looks like a verdict. It is not one. A pass means no errors, errors are rare, and almost everything the validators can tell you is advice you are free to ignore — which makes knowing the difference the first thing worth learning.
What Crucible is
The testing lab. It loads a mod profile, renders its scenes in 3D, validates everything it can check statically, and runs scenarios and sandboxes against it.
This first tutorial is about the validation pass, because it runs automatically on every scene load and is the first thing you will see the tool say about your work.
Before you start
You want a mod profile with a manifest and at least one scene. Anything will do — the lessons here are about what the checks say, not about having a good mod.
Read the severity column before the message. The list mixes three severities and only one of them means anything failed.
A pass means no errors. Warnings do not fail anything.
Verified: a manifest with a malformed id, no display name, a non-semantic version and no scenes
declared produced PASS — 0 error(s), 4 warning(s). If you are treating a green
result as "this mod is fine", you are reading a much narrower statement than you think.
The verdict
Three severities, one verdict
Every finding carries one of three severities, and they are deliberately ordered so you can filter for "this level and above".
| Severity | Value | Effect on the verdict |
|---|---|---|
| Info | 0 | None. |
| Warning | 1 | None. |
| Error | 2 | Fails the pass. |
A pass is defined as zero errors. Nothing else enters into it, so a report reading
0 errors, 40 warnings is a pass, and one reading 1 error, 0 warnings
is not.
Each finding also carries a stable code like MANIFEST_NO_ID alongside its
human message. The message is for reading and the code is for filtering — if you build
anything on top of these findings, build it on the codes.
Errors are rare
What actually fails
Take the manifest validator, which has seven checks. Exactly two of them produce errors.
| Problem | Severity |
|---|---|
No machine id at all | Error |
| Format version newer than this build supports | Error |
| Id is not lower_snake_case | Warning |
| No display name | Warning |
| Version is not semantic | Warning |
| Format version below 1 | Warning |
| No scenes declared | Warning |
The pattern is consistent and sensible: an error means Crucible cannot proceed — it has nothing to identify the mod by, or the profile was written by a newer build than this one understands. Everything else is a quality opinion.
Verified end to end: a manifest carrying four of those warnings at once still passed, and each of the two error cases failed on its own.
Coverage
Four validators
The default pass runs four validators, each owning a domain and its own family of codes.
| Validator | Checks | Codes look like |
|---|---|---|
| Manifest | Required fields, id and version format, format compatibility. | MANIFEST_NO_ID |
| Scene | Empty scenes, missing names, duplicate ids, unnamed objects. | SCENE_DUP_ID |
| Dependency | Unresolved, duplicated, self-referencing and empty dependencies. | DEP_UNRESOLVED |
| Asset integrity | Missing files, non-glTF models, zero scales, non-finite numbers, bad colours. | ASSET_MISSING |
Adding a check is adding a validator, and the set is injectable — the engine takes whatever list it is given, which is how this page's harness runs its own. That also means the four are not special: they are just the default registration.
Robustness
When a validator breaks
A validator that throws an exception does not take the pass down with it.
Verified by registering a validator that always throws, followed by one that records that it
ran. The crash was caught, turned into a VALIDATOR_CRASH error filed under
that validator's own name — and the validator after it still ran.
That is a small thing that matters a lot. It means the order validators are registered in can never silently cost you coverage: one broken check is one finding, not a lost run. And because the crash is recorded as an error, it also fails the pass — you are told loudly rather than quietly given a partial result.
VALIDATOR_CRASH finding is a bug in Crucible, not in your mod. Everything
else in that report is still valid — the other validators ran normally.| Symptom | What it means | Fix |
|---|---|---|
| Green pass but the mod misbehaves | Passing means no errors, not no problems. | Read the warnings — that is where the detail is. |
| Dozens of findings, still a pass | All warnings. Working as designed. | Treat them as a to-do list. |
Fails with MANIFEST_FORMAT_TOO_NEW | The profile targets a newer Crucible. | Update Crucible, or lower the format version. |
A VALIDATOR_CRASH appears | A validator threw. Not your mod's fault. | Report it; the rest of the pass is still good. |
Tier one complete
What you now know
Check yourself
- Validation runs automatically on scene load and produces findings at three severities.
- A pass is zero errors. Warnings and info never affect the verdict.
- Of the manifest validator's seven checks, only two are errors — no id, and a format version from the future.
- A manifest with four warnings at once still passes.
- Four validators run by default — Manifest, Scene, Dependency, Asset integrity — across 23 codes, and the set is injectable.
- Every finding carries a stable code; build on codes, read messages.
- A validator that crashes becomes one error finding and the rest of the pass still runs.
Next, at intermediate: making the mod actually do something. Scenarios and sandboxes, what a spawned agent is, and what the event log records while a run is happening.