pub enum FieldLife {
Live,
ReadOnlyDead(&'static str),
WriteOnlyDead(&'static str),
}Expand description
What the engine does with a label, in each direction.
A schema answers “what can a legitimate file contain”, which is a wider question than “what does the engine read”. Labels the engine never reads still appear in files the toolset wrote and in files the engine itself wrote, so they belong in the schema; leaving them out would make an unrecognized-field check fire once per shipped resource.
Keeping them in without saying they are dead is not much better. A diagnostic can then only say the field is unrecognized, when the useful message is that setting it does nothing and here is what the engine reads instead. This is the axis that carries the difference.
Variants§
Live
The engine reads this label at this path.
ReadOnlyDead(&'static str)
Legitimate file content the engine never reads, with why.
A modder trap: the label looks settable and has no effect. The canonical case is a value that lives on a blueprint, where the copy on an instance placement loses to the blueprint’s with no overlay.
The payload is the reason, phrased to finish the sentence “setting it has no effect, because …”, and it is a payload rather than an optional note so that no marking can exist without one. A diagnostic that can only say “this field is dead” tells an author less than the schema already knows; what makes it worth reading is “the engine takes a door’s tag from the blueprint and ignores this”.
Two entries sharing a leaf label can carry different reasons, which is why the reason takes part in how diagnostics are grouped rather than only in how they read.
WriteOnlyDead(&'static str)
The engine writes this label and never reads it back, with why.
Distinct from Self::ReadOnlyDead in who put it there. Editing one
of these is equally pointless, but a file missing it is not a file
anyone authored wrong, so a diagnostic should not treat the two the
same way.