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
//
// The native ResourceManager — the embedded-Dawn sibling of the embind-bound C++
// ResourceManager. It presents the CppResourceManager surface the SDK's asset
// pipeline consumes (createTexture / releaseTexture / getTextureDimensions), so
// the real Assets channel + TextureLoader run on the native core unchanged.
//
// The one wasm-specific op in the texture path — marshal RGBA into the wasm heap,
// then call embind createTexture(ptr) — becomes createTextureFromBytes here: the
// native core has no wasm heap, so the JS-owned bytes go straight to the same
// engine entry point (rm_createTextureEx), whose QuickJS wrapper copies them and
// hands the binding a real pointer. This mirrors how createNativeRegistry composes
// the ECS over es_* host globals; the same single generated/marshalling
// philosophy, one more backend. The upload helpers (runtimeAssets, TextureLoader)
// prefer this byte method when present, so web (embind, no such method) stays
// byte-identical.
import type { CppResourceManager } from '../../wasm';
import { RESOURCE_BINDINGS, TEXT_BINDINGS } from './nativeBindings';
/** `rm_createTextureEx` filter/wrap codes, for the case with no import settings.
* They spell out what the plain `rm_createTexture` path does, so the two agree. */
const FILTER_LINEAR = 1;
const WRAP_CLAMP_TO_EDGE = 1;
/** Invoke a host-provided global by name; throws if the host did not bind it
* (these are part of the native ResourceManager contract). */
function hostCall(scope: Record<string, unknown>, name: string, args: unknown[]): unknown {
const fn = scope[name];
if (typeof fn !== 'function') {
throw new Error(`native host binding "${name}" is missing`);
}
return (fn as (...a: unknown[]) => unknown)(...args);
}
/** Optional host global — returns undefined (and does nothing) when unbound, for
* the residency/budget hooks a minimal host may not provide yet. */
function hostCallOpt(scope: Record<string, unknown>, name: string, args: unknown[]): unknown {
const fn = scope[name];
if (typeof fn !== 'function') return undefined;
return (fn as (...a: unknown[]) => unknown)(...args);
}
/**
* Build the CppResourceManager over the host's native texture bindings. `scope`
* holds the globals (the QuickJS global object on a device; a plain object in
* tests): the host binds
* * es_rm_createTextureEx(w, h, pixels, len, format, flip, filter, wrap) -> handle
* * es_rm_releaseTexture(handle)
* * es_getTextureDimensions(handle) -> { width, height } | null
* and optionally es_rm_updateTextureSubregion / es_setTextureBudget. The `rm_`
* names are the engine's own entry points, generated for QuickJS from the same
* declarations embind registers — see {@link RESOURCE_BINDINGS}.
*
* Only the methods the native asset path actually calls are implemented; the
* wasm-specific ones (heap-pointer createTexture, registerExternalTexture,
* bitmap-font glyph upload) throw if reached, and the residency /
* stats hooks the SDK optional-chains are simply omitted — so a texture that lost
* its last reference re-decodes instead of reviving (correct, just not yet cached).
*/
export function createNativeResourceManager(
scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): CppResourceManager {
const rm: Partial<CppResourceManager> = {
// The module-free upload the SDK prefers on native (no wasm heap). The
// engine entry point is the web's `rm_createTextureEx`: it takes a byte
// COUNT beside the buffer, because on the web the buffer is a heap offset.
// Absent import settings mean the defaults the plain `rm_createTexture`
// path applies — Linear filtering, ClampToEdge wrap (Texture::create's
// pixel overload) — so a texture with no settings uploads identically.
createTextureFromBytes: (
width, height, pixels, format, flipY, content, filterMode, wrapMode,
): number =>
hostCall(scope, RESOURCE_BINDINGS.createTexture,
[width, height, pixels, pixels.length, format, flipY,
filterMode ?? FILTER_LINEAR, wrapMode ?? WRAP_CLAMP_TO_EDGE, content]) as number,
// A texture array from its layers back to back, as the engine's `rm_createTextureArray` takes them: the host copies the bytes, as it does
// for `createTextureFromBytes`, so the terrain's layer arrays exist on a device with no wasm heap.
createTextureArrayFromBytes: (width, height, layers, pixels, format, filterMode, wrapMode, content): number =>
hostCall(scope, RESOURCE_BINDINGS.createTextureArray,
[width, height, layers, pixels, pixels.length, format, filterMode, wrapMode, content]) as number,
// The host transcodes KTX2 (basis) and uploads the blocks:
// { id, width, height, format, blockRefused } → { handle, ... }. A host
// without the last two leaves them undefined, never a compressed answer.
createTextureFromKTX2: (bytes, srgb) => {
const r = hostCall(scope, RESOURCE_BINDINGS.createTextureKTX2, [bytes, srgb]) as
{ id: number; width: number; height: number;
format?: number; blockRefused?: boolean } | null;
return r
? { handle: r.id, width: r.width, height: r.height,
format: r.format, blockRefused: r.blockRefused }
: null;
},
updateTextureSubregionFromBytes: (handle, x, y, width, height, pixels): void => {
hostCallOpt(scope, TEXT_BINDINGS.updateTextureSubregion,
[handle, x, y, width, height, pixels, pixels.length]);
},
// The id a draw command binds a texture by. Named for GL because that is
// where it started, but the engine returns `Texture::getId()` on every
// backend — the glyph atlas passes it straight to the text batch. The
// host reads it off the same ResourceManager it created the texture in.
getTextureGLId: (handle): number =>
hostCall(scope, TEXT_BINDINGS.getTextureRenderId, [handle]) as number,
releaseTexture: (handle): void => {
hostCallOpt(scope, RESOURCE_BINDINGS.releaseTexture, [handle]);
},
wrapDeviceTexture: (textureId, width, height): number =>
(hostCallOpt(scope, RESOURCE_BINDINGS.wrapDeviceTexture, [textureId, width, height]) as number | undefined) ?? 0,
// Register the handle under a logical path so a later load-by-path revives
// the same texture instead of re-decoding. The web RM does this in its
// loaders; the Spine loader calls it directly (not through the optional
// TextureLoader path), so the native RM must answer it or Spine textures
// fail to bind. hostCallOpt: a host that did not compile the entry point
// simply skips the cache registration.
registerTextureWithPath: (handle, path): void => {
hostCallOpt(scope, RESOURCE_BINDINGS.registerTextureWithPath, [handle, path]);
},
// A texture's nine-slice border, from its import settings. Without it a
// UIVisual that takes its border from the texture draws as one stretched
// quad on a device — the corners of a rounded panel come out square.
setTextureMetadata: (handle, left, right, top, bottom): void => {
hostCallOpt(scope, RESOURCE_BINDINGS.setTextureMetadata, [handle, left, right, top, bottom]);
},
getTextureDimensions: (handle): { width: number; height: number } | null =>
(hostCallOpt(scope, RESOURCE_BINDINGS.getTextureDimensions, [handle]) as
{ width: number; height: number } | null | undefined) ?? null,
// The engine applies RuntimeConfig.textureCacheBudget at startup; forward it
// to the native pool when the host wires it, else no-op (eviction off).
setTextureBudget: (bytes): void => {
hostCallOpt(scope, 'es_setTextureBudget', [bytes]);
},
};
// The heap-pointer / GL / bitmap-font surface is not reachable on native (the
// asset path takes the byte upload above); fail loud rather than silently
// corrupt if some path ever calls one.
const unsupported = (name: string) => (): never => {
throw new Error(`native ResourceManager: ${name} is not supported (no wasm heap / GL on the embedded-Dawn core)`);
};
rm.createTexture = unsupported('createTexture(ptr)');
rm.createTextureEx = unsupported('createTextureEx(ptr)');
rm.registerExternalTexture = unsupported('registerExternalTexture');
rm.registerExternalTextureSized = unsupported('registerExternalTextureSized');
return rm as CppResourceManager;
}