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
// 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.
*
* A name starting `es_rm_` or `es_renderer_` is GENERATED: the host binds
* it from the same `bindings/*.hpp` declaration embind registers on the
* web, so both platforms run one implementation of that entry point (and
* both get its BoundarySpan validation). The rest are the host's own —
* either native-only (KTX2 transcode, glyph rasterization) or a shape the
* generator cannot marshal (an `emscripten::val` result). Those, and only
* those, are hand-written in `native/host/bindings/`.
*/
import { REGISTRY_OPS } from './registryOps.generated';
export { REGISTRY_OPS, type RegistryOp } from './registryOps.generated';
/**
* The hierarchy reads and the other entity-level entry points that are not
* Registry methods on the web. The Registry's own entity ops (create, destroy,
* valid, activity, destruction ownership, setParent) are {@link REGISTRY_OPS},
* generated from the one table embind is generated from, so a host cannot bind
* fewer of them than the web has.
*/
export const REGISTRY_BINDINGS = {
// Embind answers these through the Parent/Children component methods; a
// native host has no such component surface, so they are entity ops here.
hasParent: 'es_hasParent',
getParent: 'es_getParent',
removeParent: 'es_removeParent',
hasChildren: 'es_hasChildren',
getChildren: 'es_getChildren',
// MeshSkin's joints are a variable-length entity list, so the component has no
// POD layout and no generated accessor — the same reason Children is here.
getMeshSkinJoints: 'es_getMeshSkinJoints',
setMeshSkinJoints: 'es_setMeshSkinJoints',
// The web build reaches this as an embind free function on the module; a
// native host has no module, so it is a binding like the rest.
layoutEpoch: 'es_registryLayoutEpoch',
// The world-transform composition's two halves, for the same reason. The
// epoch is handed over as MEMORY, not read through a call: every Transform
// write announces through it.
transformEpoch: 'es_transformEpochBuffer',
ensureComposed: 'es_transformEnsureComposed',
} as const;
/**
* The composition's change REPORT, which not every host has to answer: a core
* that does not leaves consumers rebuilding rather than updating, so these are
* outside {@link assertNativeBindings}' required set.
*/
export const COMPOSITION_BINDINGS = {
setChangeTracking: 'es_transformSetChangeTracking',
compositionChanges: 'es_transformCompositionChanges',
takeChanges: 'es_transformTakeChanges',
} as const;
/**
* The native ResourceManager surface the asset pipeline uploads through.
*
* `createTexture` and `releaseTexture` are the engine's own `rm_*` entry points,
* generated — the same ones embind exposes as methods on the web ResourceManager,
* so a texture is created by one implementation on both platforms. The other two
* cannot be: KTX2 transcoding is native-only (the web path is WebGL2 + a wasm
* transcoder), and the dimensions query returns an `emscripten::val`.
*/
export const RESOURCE_BINDINGS = {
createTexture: 'es_rm_createTextureEx',
createTextureArray: 'es_rm_createTextureArray',
createTextureKTX2: 'es_createTextureKTX2',
releaseTexture: 'es_rm_releaseTexture',
registerTextureWithPath: 'es_rm_registerTextureWithPath',
getTextureDimensions: 'es_getTextureDimensions',
setTextureMetadata: 'es_rm_setTextureMetadata',
wrapDeviceTexture: 'es_rm_wrapDeviceTexture',
} as const;
/**
* Text rendering, which on native crosses the seam twice: the host rasterizes a
* glyph (it owns the font stack — there is no 2D canvas) and the host submits the
* laid-out quads (there is no wasm heap to marshal them through). Everything
* between those two calls — atlas, layout, batching — is the same SDK code the
* web runs.
*
* Only the glyph source is genuinely the host's: rasterization has no engine entry
* point to generate from, because on the web a 2D canvas does it. The other three
* ARE engine entry points, generated — the submit even regains the boundary
* validation a hand-written copy used to skip.
*
* OPTIONAL, like {@link AUDIO_BINDINGS}: a host that has not bound its font stack
* simply draws no text, rather than failing to boot. {@link hasTextBindings} is
* the gate.
*/
export const TEXT_BINDINGS = {
rasterizeGlyph: 'es_rasterizeGlyph',
submitTextBatch: 'es_renderer_submitTextBatch',
updateTextureSubregion: 'es_rm_updateTextureSubregion',
getTextureRenderId: 'es_rm_getTextureGLId',
} as const;
/** Whether a host bound the whole text surface — all-or-nothing, so a partially
* implemented host draws nothing instead of half-drawing. */
export function hasTextBindings(
scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): boolean {
return Object.values(TEXT_BINDINGS).every((name) => typeof scope[name] === 'function');
}
/**
* The frame. These are the engine calls the SDK's own render pipeline makes on
* web through the wasm module (`renderer_*`), bound here for a core that has no
* heap to marshal through — so the CAMERAS, viewports, clear flags, y-sort and
* pre-flush draws are decided by one implementation on both platforms, and the
* native host owns only its swapchain.
*
* Required as a set (a host that renders binds all of them); {@link
* hasRendererBindings} gates whether the SDK drives the frame at all, since a
* host may still own it while this lands.
*/
export const RENDERER_BINDINGS = {
resize: 'es_renderer_resize',
beginFrame: 'es_renderer_beginFrame',
updateTransforms: 'es_renderer_updateTransforms',
begin: 'es_renderer_begin',
submitAll: 'es_renderer_submitAll',
flush: 'es_renderer_flush',
end: 'es_renderer_end',
setStage: 'es_renderer_setStage',
setViewport: 'es_renderer_setViewport',
setYSortLayers: 'es_renderer_setYSortLayers',
/** Host-specific: the drawable size, which no wasm entry point has. */
surfaceSize: 'es_renderer_surfaceSize',
} as const;
/** The per-frame counters, read one call each — the same entry points the wasm
* module exposes under the same names, so the two paths report identically. */
export const RENDERER_STATS_BINDINGS = {
drawCalls: 'es_renderer_getDrawCalls',
gpuDraws: 'es_renderer_getGpuDrawCalls',
triangles: 'es_renderer_getTriangles',
sprites: 'es_renderer_getSprites',
text: 'es_renderer_getText',
meshes: 'es_renderer_getMeshes',
culled: 'es_renderer_getCulled',
} as const;
/**
* What the SDK declares back to the host, on the same global object.
*
* A host predates these bindings gracefully: it keeps a fallback frame (one
* full-viewport pass) for a game script that never drives one. `ownsFrame` is how
* it learns to stop — set once the SDK's render pipeline is installed, so the two
* never both draw (which would look like the SDK's frame silently vanishing, since
* the host's pass would clear and re-collect over it).
*/
export const HOST_FLAGS = {
ownsFrame: 'es_jsOwnsFrame',
} as const;
/**
* Renderer entry points a host may legitimately NOT have, and which therefore
* must stay out of `hasRendererBindings`.
*
* That probe is an all-or-nothing gate on the SDK driving the frame, so adding an
* entry to RENDERER_BINDINGS retroactively declares every host built before it
* rendererless — the SDK would hand the frame back and the game would go blank
* on a shell that was working. A capability added after a host shipped belongs
* here and is called through the optional path.
*/
export const RENDERER_OPTIONAL_BINDINGS = {
/** The render origin (render/renderOrigin.ts); a host predating it draws relative to zero. */
setOrigin: 'es_renderer_setOrigin',
/** 2.5D depth layers; hosts predating the feature simply stay painter-ordered. */
setDepthLayers: 'es_renderer_setDepthLayers',
/** Layers painted in hierarchy order (cocos compat); hosts predating it paint them as before. */
setTreeSortLayers: 'es_renderer_setTreeSortLayers',
/** Camera culling mask; hosts predating it draw every layer, as they always did. */
setCullingMask: 'es_renderer_setCullingMask',
/** Closes the frame. A host predating it released the swapchain image at
* every camera's end instead, which is where multi-camera and the screen
* overlay both fell over — so it is a fix, not only a new call. */
endFrame: 'es_renderer_endFrame',
/** The frame's screen-space overlay. All four or none: a host with only
* some of them would partition the world and then never draw the half it
* took out. The glue is generated from the same headers the engine
* compiles, so the pass and the partition arrive together. */
beginScreenOverlay: 'es_renderer_beginScreenOverlay',
submitScreenOverlay: 'es_renderer_submitScreenOverlay',
endScreenOverlay: 'es_renderer_endScreenOverlay',
/** The view a collect looks from; hosts predating it share one LOD memory. */
setViewId: 'es_renderer_setViewId',
/** What a view decided about one object's level, and holding another level up
* to look at instead. An editor's questions — a host that binds neither runs
* no editor, and the game it does run is unaffected either way. */
lodInspect: 'es_renderer_lodInspect',
setLodPreview: 'es_renderer_setLodPreview',
/** How a view shades its meshes — clay, albedo or as authored. An editor's view mode. */
setViewShading: 'es_renderer_setViewShading',
/** Edge buffers for meshes realized from now on — a wireframe view's geometry. */
setMeshEdgeBuffers: 'es_renderer_setMeshEdgeBuffers',
/** Colour one skinned entity by a joint's weights — an editor's view of a rig. */
setViewSkinWeights: 'es_renderer_setViewSkinWeights',
/** Which lights the cap turned away — an editor's question, like the two above. */
lightStatus: 'es_renderer_lightStatus',
shadowStatus: 'es_renderer_shadowStatus',
} as const;
/** Whether the host bound the whole frame surface — the gate for the SDK driving
* the frame (cameras and all) rather than the host hard-coding one. Optional
* entry points (RENDERER_OPTIONAL_BINDINGS) are deliberately not part of it. */
export function hasRendererBindings(
scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): boolean {
return Object.values(RENDERER_BINDINGS).every((name) => typeof scope[name] === 'function');
}
/** Optional bulk inspection; older hosts retain individual component checks. */
export const INSPECTION_BINDINGS = {
getBuiltinComponentNames: 'es_getBuiltinComponentNames',
componentTypeId: 'es_componentTypeId',
} as const;
/**
* Scene queries the wasm module answers as module-level functions over the
* registry. The native registry answers them itself (see createNativeRegistry);
* optional, since a host that binds neither simply has no cameras to render.
*/
export const SCENE_QUERY_BINDINGS = {
canvasEntity: 'es_registry_getCanvasEntity',
canvasEntities: 'es_registry_getCanvasEntities',
cameraEntities: 'es_registry_getCameraEntities',
} 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;
/**
* The native audio engine surface (a host with a sound device binds it). Unlike
* the sets above this one is OPTIONAL: a host with no audio omits every name and
* the audio system falls back to the silent Null backend, so it is not part of
* {@link assertNativeBindings}' required set — {@link hasAudioBindings} decides
* whether {@link NativeAudioBackend} is wired at all.
*/
export const AUDIO_BINDINGS = {
load: 'es_audioLoad',
unload: 'es_audioUnload',
play: 'es_audioPlay',
stop: 'es_audioStop',
pause: 'es_audioPause',
resume: 'es_audioResume',
setVolume: 'es_audioSetVolume',
setPan: 'es_audioSetPan',
setLoop: 'es_audioSetLoop',
setRate: 'es_audioSetRate',
voiceState: 'es_audioVoiceState',
suspendAll: 'es_audioSuspendAll',
resumeAll: 'es_audioResumeAll',
} as const;
/** Whether a host bound the whole audio surface — the gate for the native audio
* backend (all-or-nothing, so a partially-implemented host stays silent rather
* than half-playing). */
export function hasAudioBindings(
scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): boolean {
return Object.values(AUDIO_BINDINGS).every((name) => typeof scope[name] === 'function');
}
/**
* 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_OPS),
...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',
);
}
}