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
refactor(sdk): the es_* contract has one spelling, checked at boot
esengined73f342020f2
diff --git a/native/host_js/host_core.cpp b/native/host_js/host_core.cppindex e2802b468..78d940236 100644--- a/native/host_js/host_core.cpp+++ b/native/host_js/host_core.cpp@@ -65,6 +65,10 @@ globalThis.TextDecoder.prototype.decode = function (buf) {return buf == null ? '' : es_utf8Decode(buf);};+// The whole host contract in one check — the JS globals a bare engine lacks and+// the es_* bindings this shell binds — so a gap is named here, not downstream.+ESEngine.assertNativeHost(globalThis);+// The bridge over the host's es_* bindings; it also installs es_onNativeTouch,// the entry point the host calls per touch.globalThis.__esNativeBridge = ESEngine.createHostBridge(globalThis);diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 5b5b5b544..3a202dd9c 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1348 stable · 22 beta · 0 deprecated+Symbols: 1353 stable · 22 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -4216,6 +4216,11 @@ texelSize: { x: number; y: number; } | undefinedwidth: number | undefined```+## PLATFORM_BINDINGS — const+```+{ readonly readAsset: "es_readAsset"; readonly loadImagePixels: "es_loadImagePixels"; readonly utf8Decode: "es_utf8Decode"; }+```+## PREFAB_FORMAT_VERSION — const```"2"@@ -5174,6 +5179,11 @@ static prototype: QueryInstance<any>]```+## REGISTRY_BINDINGS — const+```+{ readonly createEntity: "es_createEntity"; readonly destroyEntity: "es_destroyEntity"; readonly setParent: "es_setParent"; readonly hasParent: "es_hasParent"; readonly removeParent: "es_removeParent"; readonly hasChildren: "es_hasChildren"; readonly getChildren: "es_getChildren"; }+```+## REPLICATION_CHANNEL — const```1@@ -5184,6 +5194,11 @@ static prototype: QueryInstance<any>2```+## RESOURCE_BINDINGS — const+```+{ readonly createTexture: "es_createTexture"; readonly releaseTexture: "es_releaseTexture"; readonly getTextureDimensions: "es_getTextureDimensions"; }+```+## RETIRED_COMPONENT_TYPES — const```ReadonlySet<string>@@ -8203,6 +8218,16 @@ AnimationPlugin(scope?: Record<string, unknown>): void```+## assertNativeBindings — function+```+(scope?: Record<string, unknown>): void+```++## assertNativeHost — function+```+(scope?: Record<string, unknown>): void+```+## assetPlugin — const```AssetPlugindiff --git a/sdk/src/ecs/nativeBindings.ts b/sdk/src/ecs/nativeBindings.tsnew file mode 100644index 000000000..d2199ebc1--- /dev/null+++ b/sdk/src/ecs/nativeBindings.ts@@ -0,0 +1,64 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file nativeBindings.ts+ * @brief The names a native host binds on the JS global, declared once.+ * @details Half of this contract is generated — `es_set_<C>` / `es_<C>_buffer`+ * and friends come out of the same reflection pass that emits the web+ * bindings, so neither side can misspell them. The hand-written half+ * (entities, hierarchy, textures, the platform primitives) had no such+ * guarantee: the host spelled each name in C++, the SDK spelled it again+ * in a string literal at the call site, and a mismatch surfaced whenever+ * that particular call first ran.+ *+ * These constants are the one spelling. The call sites read them, and+ * {@link assertNativeBindings} checks the whole set at boot.+ */++/** Entity + hierarchy — the base Registry surface the SDK's World drives. */+export const REGISTRY_BINDINGS = {+ createEntity: 'es_createEntity',+ destroyEntity: 'es_destroyEntity',+ setParent: 'es_setParent',+ hasParent: 'es_hasParent',+ removeParent: 'es_removeParent',+ hasChildren: 'es_hasChildren',+ getChildren: 'es_getChildren',+} as const;++/** The native ResourceManager surface the asset pipeline uploads through. */+export const RESOURCE_BINDINGS = {+ createTexture: 'es_createTexture',+ releaseTexture: 'es_releaseTexture',+ getTextureDimensions: 'es_getTextureDimensions',+} as const;++/** Platform primitives the SDK's bridge and file reading are built on. */+export const PLATFORM_BINDINGS = {+ readAsset: 'es_readAsset',+ loadImagePixels: 'es_loadImagePixels',+ utf8Decode: 'es_utf8Decode',+} as const;++/**+ * Verify a host bound everything before anything calls it.+ *+ * @throws listing every missing binding at once — a host that is halfway through+ * implementing the contract learns all of what is left, not the first+ * name some code path happened to reach.+ */+export function assertNativeBindings(+ scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,+): void {+ const missing = [+ ...Object.values(REGISTRY_BINDINGS),+ ...Object.values(RESOURCE_BINDINGS),+ ...Object.values(PLATFORM_BINDINGS),+ ].filter((name) => typeof scope[name] !== 'function');+ if (missing.length > 0) {+ throw new Error(+ `[native] the host has not bound: ${missing.join(', ')} — see NativeHostBindings `+ + 'and the es_* contract in nativeBindings.ts',+ );+ }+}diff --git a/sdk/src/ecs/nativeRegistry.ts b/sdk/src/ecs/nativeRegistry.tsindex 6cbd70d2e..598b2ec50 100644--- a/sdk/src/ecs/nativeRegistry.ts+++ b/sdk/src/ecs/nativeRegistry.ts@@ -17,6 +17,7 @@import type { CppRegistry } from '../wasm';import type { Entity } from '../types';import { PTR_ACCESSORS } from './ptrAccessors.generated';+import { REGISTRY_BINDINGS } from './nativeBindings';import { COMPONENT_META } from '../component.generated';import { convertForWasm, convertFromWasm } from './BuiltinBridge';@@ -62,16 +63,16 @@ export function createNativeRegistry(// Entity lifecycle + hierarchy — the base Registry surface World drives (spawn,// despawn, parent/child). These are not per-component; the host binds them by// hand (the native siblings of the embind Registry's entity ops).- reg.create = (): Entity => hostCall(scope, 'es_createEntity', []) as Entity;- reg.destroy = (e: Entity): void => { hostCall(scope, 'es_destroyEntity', [e]); };- reg.hasParent = (e: Entity): boolean => !!hostCall(scope, 'es_hasParent', [e]);+ reg.create = (): Entity => hostCall(scope, REGISTRY_BINDINGS.createEntity, []) as Entity;+ reg.destroy = (e: Entity): void => { hostCall(scope, REGISTRY_BINDINGS.destroyEntity, [e]); };+ reg.hasParent = (e: Entity): boolean => !!hostCall(scope, REGISTRY_BINDINGS.hasParent, [e]);reg.setParent = (child: Entity, parent: Entity): void => {- hostCall(scope, 'es_setParent', [child, parent]);+ hostCall(scope, REGISTRY_BINDINGS.setParent, [child, parent]);};- reg.removeParent = (e: Entity): void => { hostCall(scope, 'es_removeParent', [e]); };- reg.hasChildren = (e: Entity): boolean => !!hostCall(scope, 'es_hasChildren', [e]);+ reg.removeParent = (e: Entity): void => { hostCall(scope, REGISTRY_BINDINGS.removeParent, [e]); };+ reg.hasChildren = (e: Entity): boolean => !!hostCall(scope, REGISTRY_BINDINGS.hasChildren, [e]);reg.getChildren = (e: Entity) => ({- entities: vectorEntity((hostCall(scope, 'es_getChildren', [e]) as Entity[] | undefined) ?? []),+ entities: vectorEntity((hostCall(scope, REGISTRY_BINDINGS.getChildren, [e]) as Entity[] | undefined) ?? []),});reg.delete = (): void => {};diff --git a/sdk/src/ecs/nativeResourceManager.ts b/sdk/src/ecs/nativeResourceManager.tsindex 7513496b7..7b1f13a56 100644--- a/sdk/src/ecs/nativeResourceManager.ts+++ b/sdk/src/ecs/nativeResourceManager.ts@@ -15,6 +15,7 @@// method when present, so web (embind, no such method) stays byte-identical.import type { CppResourceManager } from '../wasm';+import { RESOURCE_BINDINGS } from './nativeBindings';/** Invoke a host-provided global by name; throws if the host did not bind it* (these are part of the native ResourceManager contract). */@@ -57,7 +58,7 @@ export function createNativeResourceManager(createTextureFromBytes: (width, height, pixels, format, flipY, filterMode, wrapMode,): number =>- hostCall(scope, 'es_createTexture',+ hostCall(scope, RESOURCE_BINDINGS.createTexture,[width, height, pixels, format, flipY, filterMode, wrapMode]) as number,updateTextureSubregionFromBytes: (handle, x, y, width, height, pixels): void => {@@ -65,11 +66,11 @@ export function createNativeResourceManager(},releaseTexture: (handle): void => {- hostCallOpt(scope, 'es_releaseTexture', [handle]);+ hostCallOpt(scope, RESOURCE_BINDINGS.releaseTexture, [handle]);},getTextureDimensions: (handle): { width: number; height: number } | null =>- (hostCallOpt(scope, 'es_getTextureDimensions', [handle]) as+ (hostCallOpt(scope, RESOURCE_BINDINGS.getTextureDimensions, [handle]) as{ width: number; height: number } | null | undefined) ?? null,// The engine applies RuntimeConfig.textureCacheBudget at startup; forward itdiff --git a/sdk/src/index.native.ts b/sdk/src/index.native.tsindex 37f2f9e89..a8914fa38 100644--- a/sdk/src/index.native.ts+++ b/sdk/src/index.native.ts@@ -34,7 +34,7 @@ markEngineComponentBaseline();export * from './core';export * from './webAppFactory';-export { NativePlatformAdapter, installNativePlatform, createHostBridge, assertHostEnvironment } from './platform/native';+export { NativePlatformAdapter, installNativePlatform, createHostBridge, assertHostEnvironment, assertNativeHost } from './platform/native';export type { NativeBridge, NativeInputListener, NativeFetchResult, NativeHostBindings } from './platform/native';// Fast-path memory backend for the native core. The shell builds one over its@@ -49,6 +49,9 @@ export type { MemoryProvider, ComponentHeap, NativeComponentBufferFn } from './e// _remove bindings; pass to BuiltinBridge.connect as the cppRegistry.export { createNativeRegistry } from './ecs/nativeRegistry';+// The es_* names a host binds, declared once and checked at boot.+export { REGISTRY_BINDINGS, RESOURCE_BINDINGS, PLATFORM_BINDINGS, assertNativeBindings } from './ecs/nativeBindings';+// The native ResourceManager — the embind-ResourceManager sibling the SDK's asset// pipeline drives (createTexture / releaseTexture / dims). Built over the host's// es_createTexture / es_releaseTexture / es_getTextureDimensions bindings; uploadsdiff --git a/sdk/src/platform/native/hostEnvironment.ts b/sdk/src/platform/native/hostEnvironment.tsindex 4154ba0a8..e4f9d9f70 100644--- a/sdk/src/platform/native/hostEnvironment.ts+++ b/sdk/src/platform/native/hostEnvironment.ts@@ -15,6 +15,8 @@* missing global is named at the seam instead.*/+import { assertNativeBindings } from '../../ecs/nativeBindings';+/** A host global the SDK requires, and what breaks without it. */interface RequiredGlobal {name: string;@@ -32,7 +34,8 @@ const REQUIRED: RequiredGlobal[] = [];/**- * Verify the host installed everything the SDK needs, before anything uses it.+ * Verify the host installed the JS globals the SDK needs, before anything uses+ * them. {@link assertNativeHost} checks this plus the es_* bindings.** @throws naming the first missing global and what it is needed for.*/@@ -52,3 +55,16 @@ export function assertHostEnvironment();}}++/**+ * The whole native host contract, checked at once: the JS environment a bare+ * engine lacks, and the es_* bindings the shell provides. Call it as the first+ * thing after evaluating the SDK — a shell that is missing something learns it+ * here, by name, rather than from a failure somewhere downstream.+ */+export function assertNativeHost(+ scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,+): void {+ assertHostEnvironment(scope);+ assertNativeBindings(scope);+}diff --git a/sdk/src/platform/native/index.ts b/sdk/src/platform/native/index.tsindex f32139d76..70320cfea 100644--- a/sdk/src/platform/native/index.ts+++ b/sdk/src/platform/native/index.ts@@ -12,5 +12,5 @@export { NativePlatformAdapter, installNativePlatform } from './adapter';export type { NativeBridge, NativeInputListener, NativeFetchResult } from './bridge';export { createHostBridge } from './hostBridge';-export { assertHostEnvironment } from './hostEnvironment';+export { assertHostEnvironment, assertNativeHost } from './hostEnvironment';export type { NativeHostBindings } from './hostBridge';diff --git a/sdk/tests/native-host-bridge.test.ts b/sdk/tests/native-host-bridge.test.tsindex bd9a13537..4c1da1dff 100644--- a/sdk/tests/native-host-bridge.test.ts+++ b/sdk/tests/native-host-bridge.test.ts@@ -7,7 +7,8 @@* what is missing, not fail later somewhere unrelated.*/import { describe, it, expect, vi } from 'vitest';-import { createHostBridge, assertHostEnvironment } from '../src/platform/native';+import { createHostBridge, assertHostEnvironment, assertNativeHost } from '../src/platform/native';+import { REGISTRY_BINDINGS, RESOURCE_BINDINGS, PLATFORM_BINDINGS } from '../src/ecs/nativeBindings';/** The globals a real host installs (console, timers, clock, decoder). */function hostGlobals(): Record<string, unknown> {@@ -108,3 +109,34 @@ describe('createHostBridge', () => {expect(native.get('x')).toBe('1');});});++describe('assertNativeHost', () => {+ /** Everything a complete shell binds. */+ function fullHost(): Record<string, unknown> {+ const scope = hostGlobals();+ for (const name of [+ ...Object.values(REGISTRY_BINDINGS),+ ...Object.values(RESOURCE_BINDINGS),+ ...Object.values(PLATFORM_BINDINGS),+ ]) scope[name] = () => undefined;+ return scope;+ }++ it('passes on a complete host', () => {+ expect(() => assertNativeHost(fullHost())).not.toThrow();+ });++ it('lists every missing binding at once, not just the first', () => {+ const scope = fullHost();+ delete scope[REGISTRY_BINDINGS.setParent];+ delete scope[RESOURCE_BINDINGS.createTexture];+ expect(() => assertNativeHost(scope)).toThrow(/es_setParent/);+ expect(() => assertNativeHost(scope)).toThrow(/es_createTexture/);+ });++ it('checks the JS environment before the bindings', () => {+ const scope = fullHost();+ delete scope.TextDecoder;+ expect(() => assertNativeHost(scope)).toThrow(/TextDecoder/);+ });+});