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.

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.cpp
index 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.md
index 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; } | undefined
width: 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
```
AssetPlugin
diff --git a/sdk/src/ecs/nativeBindings.ts b/sdk/src/ecs/nativeBindings.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 it
diff --git a/sdk/src/index.native.ts b/sdk/src/index.native.ts
index 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; uploads
diff --git a/sdk/src/platform/native/hostEnvironment.ts b/sdk/src/platform/native/hostEnvironment.ts
index 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.ts
index 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.ts
index 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/);
+ });
+});