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 nativeScriptModules.mjs — what each `esengine/*` specifier MEANS to a
* script inside a natively packaged game.
*
* A native build has no module loader, so the exporter rewrites every `esengine`
* import to something the host already evaluated. It did that with one rule:
*
* /^esengine(\/.*)?$/ -> globalThis.ESEngine
*
* which reads "esengine, and also anything under it" — four distinct modules
* collapsed onto the core namespace. The core does not carry their exports, so
* `import { Physics3D } from 'esengine/physics3d'` produced `undefined`, `Res`
* stored it without looking (a descriptor holds the reference; nothing reads
* `_id` until a frame resolves it), and the game threw
* `cannot read property '_id' of undefined` every frame it ran on a device.
* 49 exports across the four subpaths are unreachable that way; `Physics3D` is
* merely the one that crashed instead of being quietly undefined.
*
* So a specifier is not matched, it is LOOKED UP. Each one carries a class, and
* each class owes an obligation a gate can check. There is deliberately NO
* default: an export added to sdk/package.json with no disposition here fails
* the build rather than inheriting a guess, which is the whole failure this
* file exists to make impossible.
*/
/**
* The registry a native game script resolves a subpath through — installed as a
* non-enumerable global by the native entry, holding namespaces from the
* ALREADY-RUNNING graph. A second copy would mint a second `Physics3D`, and
* `Res` is keyed by identity: the runtime installs one, the game asks another.
*/
export const NATIVE_MODULE_REGISTRY = '__ESTELLA_NATIVE_MODULES__';
export const DISPOSITIONS = {
'core-global': {
means: 'the host has already evaluated the SDK and installed globalThis.ESEngine; this binds to that instance',
resolvesTo: 'globalThis.ESEngine',
needsNamespace: false,
},
'native-subpath': {
means: 'a public plugin module whose namespace the native entry publishes from its own graph',
resolvesTo: `globalThis.${NATIVE_MODULE_REGISTRY}[<specifier>]`,
needsNamespace: true,
},
'forbidden-native-script': {
means: 'a real SDK entry that a natively packaged game script must not import; packaging fails and says why',
resolvesTo: null,
needsNamespace: false,
},
};
/**
* Every specifier the SDK's `exports` map publishes, and what it means here.
*
* `why` is owed by anything forbidden: "no" without a reason is the kind of
* rule that gets deleted by whoever hits it next.
*/
export const MODULES = {
'esengine': { disposition: 'core-global' },
'esengine/physics': { disposition: 'native-subpath' },
'esengine/physics3d': { disposition: 'native-subpath' },
'esengine/spine': { disposition: 'native-subpath' },
'esengine/dragonbones': { disposition: 'native-subpath' },
'esengine/tilemap': { disposition: 'native-subpath' },
'esengine/terrain': { disposition: 'native-subpath' },
'esengine/timeline': { disposition: 'native-subpath' },
'esengine/fx-basic': { disposition: 'native-subpath' },
'esengine/fx-atmosphere': { disposition: 'native-subpath' },
'esengine/fx-lighting': { disposition: 'native-subpath' },
'esengine/fx-agx': { disposition: 'native-subpath' },
'esengine/foliage': { disposition: 'native-subpath' },
'esengine/worldgen': { disposition: 'native-subpath' },
'esengine/water': { disposition: 'native-subpath' },
'esengine/image': { disposition: 'native-subpath' },
'esengine/sound': { disposition: 'native-subpath' },
'esengine/spline': { disposition: 'native-subpath' },
'esengine/voxel': { disposition: 'native-subpath' },
'esengine/rig2d': { disposition: 'native-subpath' },
'esengine/imported-scene': { disposition: 'native-subpath' },
'esengine/skeletal-animation': { disposition: 'native-subpath' },
'esengine/character-shaders': { disposition: 'native-subpath' },
'esengine/logic': { disposition: 'native-subpath' },
'esengine/ai': { disposition: 'native-subpath' },
'esengine/replication': { disposition: 'native-subpath' },
'esengine/gameplay': { disposition: 'native-subpath' },
'esengine/session': { disposition: 'native-subpath' },
'esengine/native': {
disposition: 'forbidden-native-script',
why: 'the SDK entry the host itself evaluated — a game script importing it is asking for a second copy of the thing already running',
},
'esengine/debug-channel': {
disposition: 'forbidden-native-script',
why: 'a development export adds it to a web or mini-game package; a native host has no socket for it, and a game script has no reason to import it',
},
'esengine/wasm': {
disposition: 'forbidden-native-script',
why: 'the emscripten module surface; a native build embeds Dawn and QuickJS and has no such module',
},
'esengine/node': {
disposition: 'forbidden-native-script',
why: 'the Node entry, for servers and tools (examples/multiplayer-arena/server) — it reaches for node: builtins a packaged game has none of',
},
'esengine/wechat': {
disposition: 'forbidden-native-script',
why: 'the WeChat mini-game entry, a different host with a different platform adapter',
},
'esengine/minigame': {
disposition: 'forbidden-native-script',
why: 'the mini-game entry, as above',
},
'esengine/douyin': {
disposition: 'forbidden-native-script',
why: "Douyin's platform profile — it names a host global (`tt`) that a native build does not have",
},
'esengine/kuaishou': {
disposition: 'forbidden-native-script',
why: "Kuaishou's platform profile — it names a host global (`ks`) that a native build does not have",
},
'esengine/bilibili': {
disposition: 'forbidden-native-script',
why: "Bilibili's platform profile — it names a host global (`bl`) that a native build does not have",
},
'esengine/quickgame': {
disposition: 'forbidden-native-script',
why: "the quick-game platform profile — it names a host global (`qg`) that a native build does not have",
},
'esengine/alipay': {
disposition: 'forbidden-native-script',
why: "Alipay's platform profile — it names a host global (`my`) that a native build does not have",
},
'esengine/huawei': {
disposition: 'forbidden-native-script',
why: "Huawei's quick-game profile — it names a host global (`qg`) that a native build does not have",
},
'esengine/openpaas': {
disposition: 'forbidden-native-script',
why: "OpenPaaS's platform profile requires the sud host and is unavailable in a native build",
},
};
/** The `exports` subpath ("." / "./physics3d") a specifier corresponds to. */
export function subpathOf(specifier) {
return specifier === 'esengine' ? '.' : `.${specifier.slice('esengine'.length)}`;
}
/** The specifier an `exports` subpath corresponds to — the inverse of the above. */
export function specifierOf(subpath) {
return subpath === '.' ? 'esengine' : `esengine${subpath.slice(1)}`;
}
/** Every specifier that must have a namespace in the native registry. */
export function nativeSubpaths() {
return Object.entries(MODULES)
.filter(([, m]) => DISPOSITIONS[m.disposition]?.needsNamespace)
.map(([specifier]) => specifier);
}