Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(editor): a field's declared constraints bind every way of writing it

yhha849f7fc8f69
diff --git a/desktop/src/components/NumField.tsx b/desktop/src/components/NumField.tsx
index 8f373c02d..cac684947 100644
--- a/desktop/src/components/NumField.tsx
+++ b/desktop/src/components/NumField.tsx
@@ -138,7 +138,14 @@ export function NumField({
onChange={(e) => {
setText(e.target.value);
const n = parseFloat(e.target.value);
- if (!Number.isNaN(n)) onCommit(n);
+ if (Number.isNaN(n)) return;
+ // Typed values clamp like every other way into this field. They used not
+ // to, so dragging a slider stopped at its max while typing into the box
+ // beside it wrote straight past — the same field, two different rules.
+ let next = n;
+ if (min != null) next = Math.max(min, next);
+ if (max != null) next = Math.min(max, next);
+ onCommit(next);
}}
/>
</span>
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index c72c17906..9e715d2c3 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -127,19 +127,34 @@ export function patchFieldMember(
return obj as InspectorFieldValue;
}
+/**
+ * What a field will accept, as the inspector already describes it — structurally
+ * a subset of InspectorField, so the write door hands its field straight in.
+ *
+ * Taken whole rather than as loose parameters because the constraints kept being
+ * enforced one at a time: the control clamped to a range the automation door
+ * never read, and each new rule meant another argument that existing callers
+ * silently didn't pass.
+ */
+export interface FieldConstraints {
+ /** An enum's options — a NAME-valued set ("walk", "Dragon") says whether a
+ * string is a legal value or a typo; a numeric one lists the ordinals. */
+ options?: readonly EnumOption[];
+ /** `InspectorField.open` — options are suggestions and a value outside them is
+ * legal. From the enum source's declaration, which the control reads too. */
+ open?: boolean;
+ /** A numeric field's declared range (ES_PROPERTY min/max). */
+ min?: number;
+ max?: number;
+}
+
export function coerceFieldValue(
declared: InspectorFieldType,
key: string,
value: InspectorFieldValue,
- /** The field's own options, when it has them — an enum whose options are NAMES
- * ("walk", "Dragon", see EnumOption) stores the name, so the option set is what
- * says whether a string is a legal value or a typo. */
- options?: readonly EnumOption[],
- /** `InspectorField.open` — the options are suggestions and a value outside them
- * is legal. Comes from the enum source's own declaration (EnumSourceOptions),
- * which is also what the inspector control reads. */
- open?: boolean,
+ field?: FieldConstraints,
): InspectorFieldValue {
+ const { options, open, min, max } = field ?? {};
const fail = (expected: string): never => {
throw new Error(`field "${key}" (${declared}) expects ${expected}, got ${JSON.stringify(value)}`);
};
@@ -170,10 +185,30 @@ export function coerceFieldValue(
: `one of: ${options.map((o) => (o.label === String(o.value) ? o.label : `${o.value} (${o.label})`)).join(', ')}`,
);
}
- case 'number':
- case 'flags':
+ case 'number': {
+ const n = Number(value);
+ if (!Number.isFinite(n)) return fail('a number');
+ // The declared range binds every writer. The control clamps a drag and a
+ // keystroke to it; this door REFUSES instead of clamping, because a caller
+ // that asked for 5 on a 0..1 field wants to hear so, not to find 1 stored.
+ if (min != null && n < min) return fail(`at least ${min}`);
+ if (max != null && n > max) return fail(`at most ${max}`);
+ return n;
+ }
+ case 'flags': {
+ const n = Number(value);
+ if (!Number.isFinite(n) || !Number.isInteger(n)) return fail('a whole number of bits');
+ // A flag IS a bit, and the options are the bits that exist. The control can
+ // only ever toggle those; this door used to take any number at all, so a
+ // mask with bits nothing declares went straight into the component.
+ const declaredBits = (options ?? []).reduce((m, o) => m | (Number(o.value) || 0), 0);
+ if (declaredBits !== 0 && (n & ~declaredBits) !== 0) {
+ return fail(`only the declared bits (mask ${declaredBits})`);
+ }
+ return n;
+ }
case 'entity': {
- // 'entity' is a source-id reference to another entity — a plain number.
+ // A source-id reference to another entity — a plain number.
const n = Number(value);
return Number.isFinite(n) ? n : fail('a number');
}
@@ -404,7 +439,7 @@ export class EditorControlSurfaceImpl {
const keys = [...comp.fields.map((f) => f.key), ...(comp.enable ? [comp.enable.key] : [])];
throw new Error(`"${component}" has no field "${key}" (fields: ${keys.join(', ')})`);
}
- this.s.commands.setField(entity, component, key, declared, coerceFieldValue(declared, key, value, field?.options, field?.open));
+ this.s.commands.setField(entity, component, key, declared, coerceFieldValue(declared, key, value, field));
}
/**
* Add a component (by schema name) to an entity — the Details "Add Component" door.
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 4a325ccbf..cb887670f 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -692,7 +692,7 @@ export function SliderControl({
<span className="thumb" style={{ left: `${pct * 100}%` }} />
</div>
<span className="snum">
- <NumField value={value} suffix={unit} mixed={mixed} onBegin={onBegin} onEnd={onEnd} onCommit={onChange} />
+ <NumField value={value} suffix={unit} mixed={mixed} step={step} min={min} max={max} onBegin={onBegin} onEnd={onEnd} onCommit={onChange} />
</span>
</>
);
diff --git a/desktop/tests/inspector-write-values.test.ts b/desktop/tests/inspector-write-values.test.ts
index db52d04ae..285adc75b 100644
--- a/desktop/tests/inspector-write-values.test.ts
+++ b/desktop/tests/inspector-write-values.test.ts
@@ -47,16 +47,16 @@ describe('coerceFieldValue (the automation door)', () => {
];
it('accepts a name for an enum whose options are names', () => {
- expect(coerceFieldValue('enum', 'animation', 'walk', ANIMS)).toBe('walk');
+ expect(coerceFieldValue('enum', 'animation', 'walk', { options: ANIMS })).toBe('walk');
});
it('refuses a name the field cannot hold, naming what it can', () => {
- expect(() => coerceFieldValue('enum', 'animation', 'sprint', ANIMS))
+ expect(() => coerceFieldValue('enum', 'animation', 'sprint', { options: ANIMS }))
.toThrow(/stand, walk/);
});
it('leaves an ordinal enum coercing to a number', () => {
- expect(coerceFieldValue('enum', 'projectionType', '1', [{ label: 'Ortho', value: 1 }])).toBe(1);
+ expect(coerceFieldValue('enum', 'projectionType', '1', { options: [{ label: 'Ortho', value: 1 }] })).toBe(1);
expect(coerceFieldValue('enum', 'projectionType', 2)).toBe(2);
});
@@ -65,16 +65,16 @@ describe('coerceFieldValue (the automation door)', () => {
// BlendMode 99 is the ordinal version of writing animation "sprint".
it('refuses an ordinal the enum does not define, naming what it does', () => {
const MODES = [{ label: 'Alpha', value: 0 }, { label: 'Additive', value: 1 }];
- expect(coerceFieldValue('enum', 'blendMode', 1, MODES)).toBe(1);
- expect(() => coerceFieldValue('enum', 'blendMode', 99, MODES)).toThrow(/Additive/);
+ expect(coerceFieldValue('enum', 'blendMode', 1, { options: MODES })).toBe(1);
+ expect(() => coerceFieldValue('enum', 'blendMode', 99, { options: MODES })).toThrow(/Additive/);
});
// An open numeric enum takes any LAYER, and a layer is a whole number — the
// control refused 7.5 while this door wrote it.
it('takes an unnamed layer but not a fractional one', () => {
const LAYERS = [{ label: 'back', value: 0 }];
- expect(coerceFieldValue('enum', 'layer', 7, LAYERS, true)).toBe(7);
- expect(() => coerceFieldValue('enum', 'layer', 7.5, LAYERS, true)).toThrow(/whole number/);
+ expect(coerceFieldValue('enum', 'layer', 7, { options: LAYERS, open: true })).toBe(7);
+ expect(() => coerceFieldValue('enum', 'layer', 7.5, { options: LAYERS, open: true })).toThrow(/whole number/);
});
// An OPEN source offers suggestions, not a closed set: a locale key with no
@@ -84,8 +84,33 @@ describe('coerceFieldValue (the automation door)', () => {
// refused a perfectly good new key.
it('accepts a name outside the options when the source is open', () => {
const KEYS = [{ label: 'menu.play', value: 'menu.play' }];
- expect(coerceFieldValue('enum', 'i18nKey', 'menu.quit', KEYS, true)).toBe('menu.quit');
- expect(() => coerceFieldValue('enum', 'i18nKey', 'menu.quit', KEYS, false)).toThrow(/menu\.play/);
+ expect(coerceFieldValue('enum', 'i18nKey', 'menu.quit', { options: KEYS, open: true })).toBe('menu.quit');
+ expect(() => coerceFieldValue('enum', 'i18nKey', 'menu.quit', { options: KEYS })).toThrow(/menu\.play/);
+ });
+
+ // The declared range is a property of the FIELD, so it has to bind whoever
+ // writes it. The control clamps a drag and a keystroke to it; this door
+ // refuses, because a caller that asked for 5 wants to hear that it can't have
+ // it rather than discover 1 stored later.
+ it('holds a numeric field to its declared range', () => {
+ expect(coerceFieldValue('number', 'opacity', 0.5, { min: 0, max: 1 })).toBe(0.5);
+ expect(() => coerceFieldValue('number', 'opacity', 5, { min: 0, max: 1 })).toThrow(/at most 1/);
+ expect(() => coerceFieldValue('number', 'opacity', -1, { min: 0, max: 1 })).toThrow(/at least 0/);
+ // An unranged field is unchanged — most fields declare no bounds at all.
+ expect(coerceFieldValue('number', 'x', 1e6)).toBe(1e6);
+ });
+
+ // A flag IS a bit, and the options ARE the bits that exist. The control can
+ // only toggle those; this door took any number, so a mask with bits nothing
+ // declares went into the component and no layer ever matched it.
+ it('holds a bitmask to the bits its options declare', () => {
+ const BITS = [{ label: 'Default', value: 1 }, { label: 'Player', value: 2 }];
+ expect(coerceFieldValue('flags', 'categoryBits', 3, { options: BITS })).toBe(3);
+ expect(() => coerceFieldValue('flags', 'categoryBits', 8, { options: BITS })).toThrow(/declared bits/);
+ expect(() => coerceFieldValue('flags', 'categoryBits', 1.5, { options: BITS })).toThrow(/whole number/);
+ // With no options to go on, any mask passes — the same "nothing knowable
+ // here" fallback the enum branch takes.
+ expect(coerceFieldValue('flags', 'categoryBits', 0xffff)).toBe(0xffff);
});
});