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.

feat(editor): enforce field constraints at the write door (C1)

esenginef1d153cbe4bf
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 4041fa3cf..48a8781c5 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -15,6 +15,7 @@ import {
angleZToQuat,
hexToRgba,
prettyLabel,
+ clampFieldValue,
} from './schema';
import { normalizeFolder, folderParent, isFolderUnder, rebaseFolder } from '@/outliner/folders';
@@ -259,7 +260,7 @@ export class SceneCommandsImpl {
const firstTouch = !this.gesture || !this.gesture.touched.has(k);
const before = firstTouch ? structuredClone(cur[key]) : undefined;
- const after = toModelValue(cur, type, key, value);
+ const after = clampFieldValue(compName, key, toModelValue(cur, type, key, value));
this.model.setField(sourceId, compName, key, after);
if (this.gesture) {
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 774577570..0f1e6c9ea 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -341,6 +341,18 @@ export function fieldMetaFor(compType: string, key: string): UserFieldMeta | nul
return userSchema(compType)?.fields?.[key] ?? null;
}
+/**
+ * Clamp a scalar field value to its declared min/max (if any). Applied at the single
+ * write door (SceneCommands.setField) so EVERY writer — the inspector, PlayInspect and
+ * material edits — is range-bounded, not just the Details UI's own clamp.
+ */
+export function clampFieldValue(compType: string, key: string, value: unknown): unknown {
+ if (typeof value !== 'number') return value;
+ const meta = fieldMetaFor(compType, key);
+ if (!meta || (meta.min === undefined && meta.max === undefined)) return value;
+ return Math.max(meta.min ?? -Infinity, Math.min(meta.max ?? Infinity, value));
+}
+
/** The dropdown options for an enum field, or null if the field isn't an enum. */
export function enumFieldOptions(compType: string, key: string): EnumOption[] | null {
const e = fieldMetaFor(compType, key)?.enum;
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 0f849533e..2d0e868b8 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -680,6 +680,12 @@ export function AssetControl({
const empty = assetType === 'spine-skeleton' || assetType === 'spine-atlas' ? '' : 0;
const setRefFromPath = (path: string) => {
+ // Reject a wrong-typed drop (the picker popover already filters; this guards the
+ // drag-drop hole so a font can't land in a texture slot).
+ if (!ProjectStore.assetTypeAllowed(assetType, path)) {
+ Toasts.push(`This field only accepts ${assetType} assets`, 'error');
+ return;
+ }
onBegin?.();
void ProjectStore.assetRefForPath(path, assetType).then((ref) => {
if (ref) onChange(ref);
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index fd5404199..0d643ecb8 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1045,6 +1045,14 @@ class ProjectStoreImpl {
return out.sort((a, b) => a.name.localeCompare(b.name));
}
+ /** Whether the asset at `path` is a valid pick for a `fieldType` slot — the same rule
+ * the picker popover filters by, exposed so drag-drop can reject a wrong-typed asset. */
+ assetTypeAllowed(fieldType: string | undefined, path: string): boolean {
+ if (!fieldType) return true;
+ const name = path.split('/').pop() ?? path;
+ return assetMatchesSlot(assetTypeOf(name), path, fieldType);
+ }
+
/**
* Turn a Content-Browser drag (a project-relative path) into a portable
* `@uuid:` ref, preloading the asset so the Reconciler's synchronous projection
diff --git a/desktop/tests/field-constraints.test.ts b/desktop/tests/field-constraints.test.ts
new file mode 100644
index 000000000..74a38e535
--- /dev/null
+++ b/desktop/tests/field-constraints.test.ts
@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Field constraints C1 — range enforcement lowered to the single write door,
+ * and asset-type restriction on drag-drop. clampFieldValue is what makes EVERY
+ * writer (inspector, PlayInspect, material) range-bounded, not just the Details
+ * UI; assetTypeAllowed is the drag-drop type guard. Pure TS.
+ */
+import { describe, it, expect } from 'vitest';
+import { clampFieldValue, setUserSchemas } from '@/engine/schema';
+import { ProjectStore } from '@/project/ProjectStore';
+
+describe('field constraints (C1: write-gate clamp + asset-type guard)', () => {
+ it('clampFieldValue bounds a scalar to its declared min/max; passes everything else through', () => {
+ setUserSchemas([{ name: 'Ranged', fields: { hp: { min: 0, max: 100 } } }] as never);
+ expect(clampFieldValue('Ranged', 'hp', 150)).toBe(100);
+ expect(clampFieldValue('Ranged', 'hp', -5)).toBe(0);
+ expect(clampFieldValue('Ranged', 'hp', 42)).toBe(42);
+ expect(clampFieldValue('Ranged', 'hp', 'str')).toBe('str'); // non-number → passthrough
+ expect(clampFieldValue('Ranged', 'unbounded', 9999)).toBe(9999); // no meta → unchanged
+ setUserSchemas([]);
+ });
+
+ it('assetTypeAllowed enforces the slot type by extension (the drag-drop guard)', () => {
+ expect(ProjectStore.assetTypeAllowed('texture', 'assets/hero.png')).toBe(true);
+ expect(ProjectStore.assetTypeAllowed('texture', 'assets/thing.esprefab')).toBe(false);
+ expect(ProjectStore.assetTypeAllowed(undefined, 'assets/anything.xyz')).toBe(true); // unconstrained slot
+ });
+});