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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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';