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(sdk): asset-ref fields validate leniently (string ref vs numeric handle)

esengineb7fe780ee303
diff --git a/sdk/src/ecs/BuiltinBridge.ts b/sdk/src/ecs/BuiltinBridge.ts
index 794f59813..a93286854 100644
--- a/sdk/src/ecs/BuiltinBridge.ts
+++ b/sdk/src/ecs/BuiltinBridge.ts
@@ -8,7 +8,7 @@
import { Entity } from '../types';
import type { BuiltinComponentDef } from '../component';
import type { CppRegistry, ESEngineModule } from '../wasm';
-import { validateComponentData, formatValidationErrors } from '../validation';
+import { validateComponentData, formatValidationErrors, assetFieldNames } from '../validation';
import { handleWasmError } from '../wasmError';
import { installAbortGuard, throwIfModuleAborted, isModuleAborted, WasmModuleAborted } from '../moduleHealth';
import { COMPONENT_META, ABI_LAYOUT_HASH } from '../component.generated';
@@ -531,7 +531,8 @@ export class BuiltinBridge {
const errors = validateComponentData(
component._name,
defaults,
- filtered
+ filtered,
+ assetFieldNames(component)
);
if (errors.length > 0) {
throw new Error(formatValidationErrors(component._name, errors));
diff --git a/sdk/src/ecs/ScriptStorage.ts b/sdk/src/ecs/ScriptStorage.ts
index 33c4787c1..6bf290bd7 100644
--- a/sdk/src/ecs/ScriptStorage.ts
+++ b/sdk/src/ecs/ScriptStorage.ts
@@ -7,7 +7,7 @@
import { Entity } from '../types';
import { ComponentDef } from '../component';
-import { validateComponentData, formatValidationErrors } from '../validation';
+import { validateComponentData, formatValidationErrors, assetFieldNames } from '../validation';
import { log } from '../logger';
export interface InsertResult<T> {
@@ -31,7 +31,8 @@ export class ScriptStorage {
const errors = validateComponentData(
component._name,
component._default as Record<string, unknown>,
- clean
+ clean,
+ assetFieldNames(component)
);
if (errors.length > 0) {
throw new Error(formatValidationErrors(component._name, errors));
@@ -80,6 +81,7 @@ export class ScriptStorage {
component._name,
component._default as Record<string, unknown>,
data as Record<string, unknown>,
+ assetFieldNames(component)
);
if (errors.length > 0) {
log.warn('ecs', formatValidationErrors(component._name, errors));
diff --git a/sdk/src/scene.ts b/sdk/src/scene.ts
index 91ed7bae5..023e1a1fb 100644
--- a/sdk/src/scene.ts
+++ b/sdk/src/scene.ts
@@ -10,7 +10,7 @@ import { Entity, INVALID_ENTITY } from './types';
import { getComponent, Name, Camera, RuntimeOnly } from './component';
import { discoverSceneAssets } from './asset/discoverAssets';
import { requireResourceManager } from './resourceManager';
-import { validateComponentData, formatValidationErrors } from './validation';
+import { validateComponentData, formatValidationErrors, assetFieldNames } from './validation';
import { log } from './logger';
import { ESTELLA_SCENE_GENERATOR } from './provenance';
import {
@@ -506,7 +506,9 @@ export function loadComponent(world: World, entity: Entity, compData: SceneCompo
}
}
- const errors = validateComponentData(compData.type, comp._default as Record<string, unknown>, compData.data);
+ // Asset-ref fields validate leniently: their serialized string ref and runtime
+ // numeric handle are both legal (a Tiled-imported Tilemap's `source: 0` == "none").
+ const errors = validateComponentData(compData.type, comp._default as Record<string, unknown>, compData.data, assetFieldNames(comp));
if (errors.length > 0) {
const context = entityName ? ` (entity "${entityName}")` : '';
log.warn('scene', formatValidationErrors(compData.type + context, errors));
diff --git a/sdk/src/validation.ts b/sdk/src/validation.ts
index a93aed91d..507bd19a9 100644
--- a/sdk/src/validation.ts
+++ b/sdk/src/validation.ts
@@ -15,7 +15,8 @@ export type ValidationError = {
export function validateComponentData(
componentName: string,
defaults: Record<string, unknown>,
- data: Record<string, unknown>
+ data: Record<string, unknown>,
+ assetFields?: ReadonlySet<string>
): ValidationError[] {
const errors: ValidationError[] = [];
@@ -38,6 +39,17 @@ export function validateComponentData(
if (expectedType === 'null' || expectedType === 'undefined') continue;
if (expectedType !== actualType && value !== null && value !== undefined) {
+ // Asset-ref fields carry two legal shapes: a portable string ref
+ // ("@uuid:…", or "" for none) in serialized/model data, and a numeric
+ // runtime handle (0 for none). A string↔number mismatch on one denotes
+ // the same asset (or its absence), so it is not an error.
+ if (
+ assetFields?.has(field) &&
+ ((expectedType === 'string' && actualType === 'number') ||
+ (expectedType === 'number' && actualType === 'string'))
+ ) {
+ continue;
+ }
errors.push({
field,
expected: expectedType,
@@ -50,6 +62,13 @@ export function validateComponentData(
return errors;
}
+/** A component's asset-ref field names — pass to {@link validateComponentData} so
+ * those fields validate leniently: a portable string ref ("@uuid:…"/"") and a
+ * numeric runtime handle (0) both denote the same asset (or its absence). */
+export function assetFieldNames(component: { assetFields?: readonly { field: string }[] }): ReadonlySet<string> {
+ return new Set((component.assetFields ?? []).map((a) => a.field));
+}
+
function getType(value: unknown): string {
if (value === null) return 'null';
if (value === undefined) return 'undefined';