Refuses a malformed mask (§85), naming the field it came from.
§85 asks builds to detect "NaN and infinite values"; a mask is the case where
detection earns its check, because a NaN mask fails every& test
silently — the scene simply stops drawing, with no error and nothing in the
frame to point at. A fractional or out-of-range mask is the same mistake
arriving through a parsed document.
Unconditional, not gated on DEV — deliberately, and for two reasons.
§85 lets production disable expensive validation "while preserving
essential safety checks", and this is three comparisons at an entry point,
not a scan: a build that skipped it would trade a named error for an empty
screen. And @fourjs/scene is a simulation package under §33, which
tests/integration/dev-build-mode.test.ts holds to a blunt rule — nothing
here may branch on the build mode at all, so that a replay cannot depend on
which build ran it (see @fourjs/core's dev.ts for the "unconditional throw
vs. devAssert" rule this follows).
Call it once per operation — at the entry point that accepts an author's
mask — never per node in a traversal.
Parameters
mask: number
field: string
Returns void
Throws
FourError INVALID_SCENE_GRAPH when mask is not a well-formed
LayerMask.
Refuses a malformed mask (§85), naming the field it came from.
§85 asks builds to detect "NaN and infinite values"; a mask is the case where detection earns its check, because a
NaNmask fails every&test silently — the scene simply stops drawing, with no error and nothing in the frame to point at. A fractional or out-of-range mask is the same mistake arriving through a parsed document.Unconditional, not gated on
DEV— deliberately, and for two reasons. §85 lets production disable expensive validation "while preserving essential safety checks", and this is three comparisons at an entry point, not a scan: a build that skipped it would trade a named error for an empty screen. And@fourjs/sceneis a simulation package under §33, whichtests/integration/dev-build-mode.test.tsholds to a blunt rule — nothing here may branch on the build mode at all, so that a replay cannot depend on which build ran it (see@fourjs/core'sdev.tsfor the "unconditional throw vs.devAssert" rule this follows).Call it once per operation — at the entry point that accepts an author's mask — never per node in a traversal.