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
feat(android): PhysX is its own library, packed only for a PhysX project
yhhe57a87291f58
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.jsindex 80044da20..9bb1b26fd 100644--- a/build-tools/tasks/native.js+++ b/build-tools/tasks/native.js@@ -22,6 +22,7 @@ import {} from './nativeDeps.js';import {ANDROID_ABIS, BYTECODE_FILE, findTemplate, iosTemplateSources, templateStoreDir,+ androidPhysXLibs, packageAbis,} from '../utils/nativeTemplate.js';import { readAppConfig, fillTemplate, iosInterfaceOrientations } from '../utils/nativeApp.js';import { emitIosXcodeProject } from '../utils/iosProject.js';@@ -104,8 +105,11 @@ async function generateNativeFunctionBindings(rootDir, genDir, python) {'--native-shim', 'esn_shim.hpp',// PhysX answers the same 3D physics surface as Jolt and links beside it, so// its copy of the surface is renamed (the header below is force-included- // into its TUs) and wrapped a second time from the same declarations.+ // into its TUs) and wrapped a second time from the same declarations — in+ // a TU of its own, linked wherever PhysX is (the host on a desktop, its own+ // library on Android: native/CMakeLists.txt).'--native-functions-alias', PHYSX_ALIAS,+ '--native-functions-alias-output', path.join(genDir, 'PhysX3DFunctionBindings.generated.cpp'),'--native-functions-alias-header', path.join(genDir, 'PhysX3DRename.generated.hpp'),], { cwd: rootDir });// The TS engine surface: the CORE headers only. It is committed (the SDK compiles@@ -781,6 +785,15 @@ async function packageAndroidApk(options) {if (!options.key) logger.info('Signing with the development key (sideload only — not for a store).');const assembly = { templateDir: template.dir, contentDir, app, key };+ // PhysX rides along only for a project that picked it, as the editor's export+ // does it (pipeline/src/export/exportGame.ts) — read from the packaged config.+ const configFile = path.join(contentDir, 'game.config.json');+ const packaged = existsSync(configFile) ? JSON.parse(readFileSync(configFile, 'utf8')) : {};+ if (packaged.physics3dBackend === 'physx') {+ const physx = androidPhysXLibs(template.dir, packageAbis(template.dir));+ if (physx) assembly.extraLibs = physx;+ else logger.warn('The project’s 3D solver is PhysX and this template has no PhysX library: it runs on Jolt.');+ }logger.step('Assembling the APK...');const apk = assembleApk(assembly);const out = path.join(contentDir, apkFileName(app.id));diff --git a/build-tools/utils/nativeTemplate.d.ts b/build-tools/utils/nativeTemplate.d.tsindex 0b8454b07..b6b051357 100644--- a/build-tools/utils/nativeTemplate.d.ts+++ b/build-tools/utils/nativeTemplate.d.ts@@ -129,6 +129,10 @@ export function releaseAssetBases(engineVersion: string, env?: NodeJS.ProcessEnvexport function parseTemplateIndex(doc: unknown, engineVersion?: string): PublishedTemplate[] | null;export const DEFAULT_ICON: string;/** The pieces an exported Android Studio project is assembled from. */+/** PhysX's optional Android library, kept under plugins/<abi>/ in a template. */+export const ANDROID_PHYSX_LIBRARY: string;+/** PhysX's library per packaged ABI, for lib/<abi>/; null when the template has none. */+export function androidPhysXLibs(dir: string, abis: string[]): Record<string, string[]> | null;export function androidTemplateSources(dir: string): {/** The engine's shared libraries, one directory per ABI. */libs: string;diff --git a/build-tools/utils/nativeTemplate.js b/build-tools/utils/nativeTemplate.jsindex 6e1121393..6395f8e1d 100644--- a/build-tools/utils/nativeTemplate.js+++ b/build-tools/utils/nativeTemplate.js@@ -59,6 +59,30 @@ export const V8_WINDOWS_RUNTIME = [/** The V8 an Android V8 host links, one per ABI beside the host library. */export const V8_ANDROID_LIBRARY = 'libv8android.so';+/**+ * PhysX, as the Android host's optional library (native/CMakeLists.txt). The+ * template keeps it under `plugins/<abi>/`, outside the `lib/` every package+ * copies, so a package carries it only when its project's 3D solver is PhysX+ * ({@link androidPhysXLibs}); the host dlopens it by name when it is there.+ */+export const ANDROID_PHYSX_LIBRARY = 'libestella_physx.so';++/**+ * PhysX's library for each of `abis`, for a package's `lib/<abi>/` — or null when+ * the template carries none (a host built with -DESTELLA_PHYSX=OFF), in which case+ * a PhysX project runs on Jolt and its log says so.+ *+ * @param {string} dir An installed android template.+ * @param {string[]} abis The ABIs the package carries.+ * @returns {Record<string, string[]> | null}+ */+export function androidPhysXLibs(dir, abis) {+ const found = abis+ .map((abi) => [abi, path.join(dir, 'plugins', abi, ANDROID_PHYSX_LIBRARY)])+ .filter(([, file]) => existsSync(file));+ return found.length === 0 ? null : Object.fromEntries(found.map(([abi, file]) => [abi, [file]]));+}+/** Where an Android V8 host reads its startup snapshot from, inside the package's* assets — the name native/CMakeLists.txt compiles in as ESJS_V8_SNAPSHOT_ASSET. */export function v8SnapshotAsset(abi) {@@ -257,6 +281,12 @@ export function templateLayout(platform, options = {}) {rel: `lib/${abi}/${V8_ANDROID_LIBRARY}`, strip: true, abi, optional: true,from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, V8_ANDROID_LIBRARY),},+ {+ // PhysX, the optional 3D solver: outside lib/ so that only a+ // package whose project picked it carries it (androidPhysXLibs).+ rel: `plugins/${abi}/${ANDROID_PHYSX_LIBRARY}`, strip: true, abi, optional: true,+ from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, ANDROID_PHYSX_LIBRARY),+ },{// Its startup snapshot, which this V8 keeps outside the library. An// asset, read by the host before the engine starts (Runtime.cpp).diff --git a/desktop b/desktopindex 51b098ef1..4f5e6f652 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 51b098ef1d904ba7be21edec07603d76756521cd+Subproject commit 4f5e6f65296313e1c5753c989c164a8ccd463790diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdxindex b6962bd96..022c361de 100644--- a/docs/astro/src/content/docs/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/gameplay/physics-3d.mdx@@ -62,11 +62,12 @@ What it costs: the PhysX web module is 3.5 MB (1.14 MB gzipped), against Jolt'sglancing off the edge of a hinged door) ends differently on the two solvers, asit would between any two engines.-Native builds for Windows, Linux and Android compile both solvers into-the app and run the one the project chose, so a native game and its web build use-the same solver. Carrying PhysX makes every native app larger whichever solver it-uses: 4 MB on the Windows executable, and 2 MB of an Android download (4.7 MB-installed, per ABI). macOS and iOS builds include only Jolt for now. A PhysX+Native builds for Windows, Linux and Android run the solver the project chose,+so a native game and its web build use the same solver. Desktop apps compile both+solvers in, which adds 4 MB to every Windows executable. An Android package+carries PhysX as a library of its own, `libestella_physx.so`, only when the project+chose PhysX: that adds about 2 MB to the download (4.9 MB installed, per ABI), and a+Jolt project pays nothing. macOS and iOS builds include only Jolt for now. A PhysXproject there runs on Jolt and logs that once at startup.## Bodiesdiff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdxindex 61b634133..fb02a6291 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx@@ -49,9 +49,10 @@ PhysX 按 Unity 的默认值设置:投影高斯-赛德尔求解、patch 摩擦代价:PhysX 的 Web 模块 3.5 MB(gzip 1.14 MB),Jolt 是 1.3 MB;只有选了它的项目才加载。混沌的场景(比如球擦过铰链门的边缘)在两个求解器上的结果会不同,任何两个引擎之间都会这样。-Windows、Linux 和 Android 的原生包把两个求解器都编进应用,运行项目选的那个,-所以原生游戏和它的 Web 版用的是同一个求解器。带上 PhysX 会让每个原生应用都变大,不管它用哪个求解器:-Windows 可执行文件大约多 4 MB,Android 下载包大约多 2 MB(每个 ABI 安装后多 4.7 MB)。+Windows、Linux 和 Android 的原生包运行项目选的那个求解器,所以原生游戏和它的 Web 版用的是同一个求解器。+桌面应用把两个求解器都编进去,每个 Windows 可执行文件大约多 4 MB。Android 包把 PhysX 作为单独的库+`libestella_physx.so`,只有选了 PhysX 的项目才带:下载包大约多 2 MB(每个 ABI 安装后多 4.9 MB),+用 Jolt 的项目不增加任何体积。macOS 和 iOS 包目前只编进了 Jolt,选了 PhysX 的项目在这两个平台上运行 Jolt,启动时会记一条日志说明。## 刚体diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex cc37e4347..da5307f34 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -335,8 +335,15 @@ if(ESTELLA_QUICKJS_DIR)else()target_compile_options(estella_physics3d_physx PRIVATE -include "${PHYSX_RENAME}")endif()- # INTERFACE: what turns the es_physx3d_* wrappers on is linking this.+ # INTERFACE: what tells a TU that links this that PhysX is in its binary.target_compile_definitions(estella_physics3d_physx INTERFACE ES_ENABLE_PHYSX)+ # PhysX's es_physx3d_* wrappers, generated from the same declarations as+ # Jolt's (build-tools/tasks/native.js, PHYSX_ALIAS) and linked wherever+ # PhysX is: into the host on a desktop, into libestella_physx.so on Android.+ set(PHYSX_FN_BINDINGS "${ESTELLA_NATIVE_GEN_DIR}/PhysX3DFunctionBindings.generated.cpp")+ if(NOT EXISTS "${PHYSX_FN_BINDINGS}")+ message(FATAL_ERROR "Missing ${PHYSX_FN_BINDINGS} — generate it via `cli native`.")+ endif()endif()# QuickJS-ng interpreter — core is just these four C files.@@ -513,6 +520,10 @@ if(ESTELLA_QUICKJS_DIR)target_link_libraries(estella_js_host esengine estella_physics estella_physics3destella_video estella_spine estella_dragonbones esjs_engine SDL3::SDL3)if(TARGET estella_physics3d_physx)+ # Linked in: a desktop app's size is not a download a player waits on+ # the way a phone's is, and an executable cannot be linked against+ # by a library the way the Android host is below.+ target_sources(estella_js_host PRIVATE "${PHYSX_FN_BINDINGS}")target_link_libraries(estella_js_host estella_physics3d_physx)endif()if(ESTELLA_V8_RUNTIME)@@ -566,7 +577,18 @@ if(ESTELLA_QUICKJS_DIR)estella_video estella_spineestella_dragonbones esjs_engine native_app_glue android log)if(TARGET estella_physics3d_physx)- target_link_libraries(estella_js_host estella_physics3d_physx)+ # A library of its own, so a package carries it only when its project+ # picked PhysX (4.9 MB per ABI): the template keeps it under plugins/,+ # the export copies it into lib/<abi>/, and the host dlopens it by name+ # (host/Runtime.cpp). It links against the host for the engine surface+ # and the heap its wrappers marshal through.+ add_library(estella_physx SHARED "${PHYSX_FN_BINDINGS}" host/plugins/physx_plugin.cpp)+ target_link_libraries(estella_physx PRIVATE estella_physics3d_physx estella_js_host)+ target_include_directories(estella_physx PRIVATE+ "${CMAKE_CURRENT_SOURCE_DIR}/host" "${ESTELLA_NATIVE_GEN_DIR}"+ $<TARGET_PROPERTY:esengine,INTERFACE_INCLUDE_DIRECTORIES>)+ target_compile_definitions(estella_physx PRIVATE+ $<TARGET_PROPERTY:esengine,INTERFACE_COMPILE_DEFINITIONS>)endif()set_target_properties(estella_js_host PROPERTIES LINK_FLAGS "-u ANativeActivity_onCreate")if(ESJS_ENGINE STREQUAL "v8")diff --git a/native/host/Runtime.cpp b/native/host/Runtime.cppindex e78ff3ed1..976879491 100644--- a/native/host/Runtime.cpp+++ b/native/host/Runtime.cpp@@ -28,6 +28,10 @@#include "esengine_bundle.h" // the real SDK, bundled: installs globalThis.ESEngine#include "host_bootstrap.h" // bootstrap.js, embedded+#if defined(__ANDROID__) && !defined(ES_ENABLE_PHYSX)+#include <dlfcn.h>+#endif+#include <chrono>#include <cstdarg>#include <cstdio>@@ -36,6 +40,12 @@using namespace esengine;+// PhysX's copy of the 3D physics surface (es_physx3d_*), generated beside the+// host's own wrappers. Where PhysX is linked into this binary (a desktop host) it+// is registered directly; an Android host ships it as libestella_physx.so, which+// only a PhysX project's package carries (see loadPhysXLibrary).+void esn_register_functions_physx3d(esjs::Val global);+namespace eshost {// =============================================================================@@ -101,6 +111,31 @@ void readByteSource(esjs::Val v, std::vector<u8>& out) {namespace {+#if defined(__ANDROID__) && !defined(ES_ENABLE_PHYSX)+/**+ * PhysX, on Android, is a library of its own: 4.9 MB per ABI that a project on+ * Jolt should not download. The export packs libestella_physx.so into lib/<abi>/+ * only for a project whose 3D solver is PhysX, and the app's linker namespace+ * finds it there by its bare name. It links against this host for the engine+ * surface and the heap, and registers its es_physx3d_* wrappers when called.+ *+ * Absent is the normal case, not an error: the SDK then answers a PhysX project+ * with Jolt and says so (sdk/src/ecs/bridge/nativeSideModules.ts).+ */+void loadPhysXLibrary(esjs::Val global) {+ void* lib = dlopen("libestella_physx.so", RTLD_NOW | RTLD_LOCAL);+ if (lib == nullptr) return;+ using Register = void (*)(esjs::Val*);+ auto reg = reinterpret_cast<Register>(dlsym(lib, "estella_physx_register"));+ if (reg == nullptr) {+ ESHOST_LOGE("libestella_physx.so has no estella_physx_register: %s", dlerror());+ return;+ }+ reg(&global);+ ESHOST_LOGI("PhysX loaded (libestella_physx.so)");+}+#endif+esjs::Val consoleWrite(const esjs::Args& a, bool error) {std::string line;for (int i = 0; i < a.size(); ++i) {@@ -368,6 +403,11 @@ void initRuntime(HostState& h) {// from, so the SDK reaches the engine by the same names on either platform.esn_register(global);esn_register_functions(global);+#if defined(ES_ENABLE_PHYSX)+ esn_register_functions_physx3d(global);+#elif defined(__ANDROID__)+ loadPhysXLibrary(global);+#endif// Layer 1: the real SDK bundle, embedded — installs `ESEngine`.const double tCtx = nowMs();diff --git a/native/host/plugins/physx_plugin.cpp b/native/host/plugins/physx_plugin.cppnew file mode 100644index 000000000..21ba46e47--- /dev/null+++ b/native/host/plugins/physx_plugin.cpp@@ -0,0 +1,20 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file physx_plugin.cpp+ * @brief libestella_physx.so's one entry point: register the es_physx3d_* surface.+ * @details On Android PhysX is a library of its own, packed only into a package+ * whose project picked it (pipeline/src/export/exportGame.ts). The host+ * dlopens it by name at boot and, when it is there, calls this with the JS+ * global object (native/host/Runtime.cpp, loadPhysXLibrary). The wrappers+ * it registers are generated from the same declarations as Jolt's, and+ * reach the engine surface and the heap through the host library this one+ * links against.+ */+#include "esn_shim.hpp"++void esn_register_functions_physx3d(esjs::Val global);++extern "C" __attribute__((visibility("default"))) void estella_physx_register(esjs::Val* global) {+ esn_register_functions_physx3d(*global);+}diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 78b91663e..95361e8b1 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -70,7 +70,7 @@ import { orientationCss, orientationOverlayHtml, orientationLockScript, orientatimport { PAGE_BACKGROUND, splashCss, splashHtml, type SplashLook } from './splash';import { emitIosXcodeProject, type IosProjectSources } from '../../../build-tools/utils/iosProject.js';import { emitAndroidGradleProject } from '../../../build-tools/utils/gradleProject.js';-import { androidTemplateSources, packageAbis } from '../../../build-tools/utils/nativeTemplate.js';+import { androidPhysXLibs, androidTemplateSources, packageAbis } from '../../../build-tools/utils/nativeTemplate.js';import { assembleApk, apkFileName } from '../../../build-tools/utils/apk.js';import { ANDROID_AOT_LIBRARY, androidAotCompilers } from './androidAot';import { assembleAab, aabFileName } from '../../../build-tools/utils/aab.js';@@ -1372,6 +1372,19 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>if (platform === 'android') {const template = opts.androidTemplate ?? null;const wantsProject = opts.androidOutput === 'project';+ // PhysX is the host's optional library: in this package only when the project+ // picked it, beside the compiled systems in lib/<abi>/ (the host dlopens it).+ let extraLibs = androidAotLibs;+ if (template && opts.features?.physics?.backend3d === 'physx') {+ const physx = androidPhysXLibs(template, packageAbis(template, { emulator: opts.androidEmulatorAbi === true }));+ if (physx) {+ extraLibs = { ...(extraLibs ?? {}) };+ for (const [abi, files] of Object.entries(physx)) extraLibs[abi] = [...(extraLibs[abi] ?? []), ...files];+ } else {+ warnings.push('This project’s 3D solver is PhysX, and the installed Android runtime template carries no '+ + 'PhysX library: the app runs on Jolt. Install a template built with PhysX, then export again.');+ }+ }if (!template) {warnings.push(`No Android runtime template is installed for this editor version, so no ${wantsProject ? 'project was written' : 'APK was assembled'} — the content is here. `@@ -1379,7 +1392,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>} else if (wantsProject) {progress({ phase: 'Writing Android Studio project' });androidProject = await emitAndroidGradleProject(- absOut, appConfig, { ...androidTemplateSources(template), ...(androidAotLibs ? { extraLibs: androidAotLibs } : {}) }, icon);+ absOut, appConfig, { ...androidTemplateSources(template), ...(extraLibs ? { extraLibs } : {}) }, icon);} else {progress({ phase: 'Assembling the APK' });const release = opts.minify && opts.androidKey@@ -1393,7 +1406,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>templateDir: template, contentDir: absOut, app: appConfig, key, icon,emulatorAbi: opts.androidEmulatorAbi === true,compressNativeLibs: opts.androidCompressNativeLibs !== false,- ...(androidAotLibs ? { extraLibs: androidAotLibs } : {}),+ ...(extraLibs ? { extraLibs } : {}),};apkFile = path.join(absOut, apkFileName(appConfig.id));await writeFile(apkFile, assembleApk(assembly));diff --git a/pipeline/tests/apk-extra-libs.test.ts b/pipeline/tests/apk-extra-libs.test.tsindex 1dec0749d..ce9328282 100644--- a/pipeline/tests/apk-extra-libs.test.ts+++ b/pipeline/tests/apk-extra-libs.test.ts@@ -14,6 +14,7 @@ import { assembleApk, withExtractNativeLibs } from '../../build-tools/utils/apk.import { readZip } from '../../build-tools/utils/zip.js';import { debugSigningKey } from '../../build-tools/utils/androidKeystore.js';import { ANDROID_AOT_LIBRARY } from '../src/export/androidAot';+import { ANDROID_PHYSX_LIBRARY, androidPhysXLibs } from '../../build-tools/utils/nativeTemplate.js';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');@@ -120,3 +121,57 @@ describe('how an APK packs its native libraries', () => {.toContain('<application android:extractNativeLibs="true" android:label="x">');});});++describe('PhysX on Android is in the package only when the project picked it', () => {+ const fixture = () => {+ const dir = mkdtempSync(path.join(tmpdir(), 'estella-apk-physx-'));+ const template = path.join(dir, 'template');+ mkdirSync(path.join(template, 'lib', 'arm64-v8a'), { recursive: true });+ writeFileSync(path.join(template, 'lib', 'arm64-v8a', 'libestella_js_host.so'), Buffer.from('host'));+ // Where the template keeps it: outside lib/, which every package copies.+ mkdirSync(path.join(template, 'plugins', 'arm64-v8a'), { recursive: true });+ writeFileSync(path.join(template, 'plugins', 'arm64-v8a', ANDROID_PHYSX_LIBRARY), Buffer.from('physx'));+ copyFileSync(path.join(ROOT, 'native/android/host/AndroidManifest.xml.in'), path.join(template, 'AndroidManifest.xml.in'));+ copyFileSync(path.join(ROOT, 'native/icon.png'), path.join(template, 'icon.png'));+ const content = path.join(dir, 'content');+ mkdirSync(content, { recursive: true });+ writeFileSync(path.join(content, 'game.config.json'), '{}');+ const apk = (extraLibs?: Record<string, string[]>) => new Map(readZip(assembleApk({+ templateDir: template, contentDir: content,+ app: { id: 'com.example.physx', name: 'PhysX', version: '1.0', versionCode: 1 } as never,+ key: debugSigningKey(), ...(extraLibs ? { extraLibs } : {}),+ })).map((e) => [e.name, e.data]));+ return { dir, template, apk };+ };++ it('leaves it out of the package of a Jolt project', () => {+ const { dir, apk } = fixture();+ try {+ expect([...apk().keys()].filter((n) => n.includes(ANDROID_PHYSX_LIBRARY))).toEqual([]);+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+ });++ it('puts it in lib/<abi>/ for a PhysX project, where the host dlopens it by name', () => {+ const { dir, template, apk } = fixture();+ try {+ const libs = androidPhysXLibs(template, ['arm64-v8a', 'x86_64']);+ // Only the ABIs the template built it for.+ expect(Object.keys(libs ?? {})).toEqual(['arm64-v8a']);+ expect(apk(libs!).get(`lib/arm64-v8a/${ANDROID_PHYSX_LIBRARY}`)?.toString()).toBe('physx');+ expect([...apk(libs!).keys()].some((n) => n.startsWith('plugins/'))).toBe(false);+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+ });++ it('answers null for a template built without PhysX, so the export can say so', () => {+ const dir = mkdtempSync(path.join(tmpdir(), 'estella-apk-nophysx-'));+ try {+ expect(androidPhysXLibs(dir, ['arm64-v8a'])).toBeNull();+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+ });+});diff --git a/tools/check-native-bindings.mjs b/tools/check-native-bindings.mjsindex 5e8852b63..5b94d40d8 100644--- a/tools/check-native-bindings.mjs+++ b/tools/check-native-bindings.mjs@@ -47,6 +47,7 @@ if (failed) {const out = mkdtempSync(path.join(tmpdir(), 'estella-nfb-'));const generated = path.join(out, 'NativeFunctionBindings.generated.cpp');const renames = path.join(out, 'PhysX3DRename.generated.hpp');+const physxWrappers = path.join(out, 'PhysX3DFunctionBindings.generated.cpp');// `python` is not a command macOS ships; `python3` is. Asking the same resolver// the build asks is why this gate can run on a developer's machine at all — it// was CI-only on the belief that it could not.@@ -64,6 +65,7 @@ try {'--native-functions-output', generated,'--native-shim', 'esn_shim.hpp','--native-functions-alias', PHYSX_ALIAS,+ '--native-functions-alias-output', physxWrappers,'--native-functions-alias-header', renames,], { cwd: ROOT, stdio: 'pipe' });} catch (e) {@@ -86,7 +88,10 @@ for (const inc of includes) {// wrapper has its physx3d_* twin, and every declared name is renamed (one left// out would collide with Jolt's symbol in the host link).const joltWrapped = new Set([...text.matchAll(/setFunction\(global, "es_physics3d_(\w+)"/g)].map((m) => m[1]));-const physxWrapped = new Set([...text.matchAll(/setFunction\(global, "es_physx3d_(\w+)"/g)].map((m) => m[1]));+const physxText = readFileSync(physxWrappers, 'utf8');+if (/es_physx3d_/.test(text)) fail('physx3d_* wrappers leaked into the host TU — they belong in their own (PhysX3DFunctionBindings)');+if (!/^void esn_register_functions_physx3d\(esjs::Val global\)/m.test(physxText)) fail('the PhysX TU has no esn_register_functions_physx3d');+const physxWrapped = new Set([...physxText.matchAll(/setFunction\(global, "es_physx3d_(\w+)"/g)].map((m) => m[1]));for (const name of joltWrapped) {if (!physxWrapped.has(name)) fail(`physics3d_${name} has no physx3d_ twin in the generated wrappers`);}diff --git a/tools/eht/__main__.py b/tools/eht/__main__.pyindex af1988262..12bf53d73 100644--- a/tools/eht/__main__.py+++ b/tools/eht/__main__.py@@ -48,6 +48,14 @@ def _emit_native_functions(args) -> int:print(f"[FAIL] --native-functions-alias: {err}")return 1gen = NativeFunctionsGenerator(headers, shim_header=args.native_shim, aliases=aliases)+ if aliases and args.native_functions_alias_output is None:+ print("[FAIL] --native-functions-alias needs --native-functions-alias-output "+ "(the aliased wrappers are a TU of their own)")+ return 1+ if args.native_functions_alias_output is not None:+ args.native_functions_alias_output.parent.mkdir(parents=True, exist_ok=True)+ print(f"Generating: {args.native_functions_alias_output}")+ _write_lf(args.native_functions_alias_output, gen.generate_aliases())if args.native_functions_alias_header is not None:args.native_functions_alias_header.parent.mkdir(parents=True, exist_ok=True)print(f"Generating: {args.native_functions_alias_header}")@@ -136,6 +144,8 @@ def main() -> int:# behind GATE, and the alias header renames that implementation's symbols.parser.add_argument('--native-functions-alias', type=str, action='append', default=None,help='Also wrap <src>* entry points as <dst>* behind GATE: <src>=<dst>:<GATE>')+ parser.add_argument('--native-functions-alias-output', type=Path, default=None,+ help='Where to write the aliased wrappers and their registration (.cpp)')parser.add_argument('--native-functions-alias-header', type=Path, default=None,help='Write the #define rename header for the aliases (.hpp)')args = parser.parse_args()diff --git a/tools/eht/generators/native_functions.py b/tools/eht/generators/native_functions.pyindex 16e4b7793..48a6085f4 100644--- a/tools/eht/generators/native_functions.py+++ b/tools/eht/generators/native_functions.py@@ -120,12 +120,12 @@ class Alias(NamedTuple):differ: the 3D physics surface is answered by Jolt as ``physics3d_*`` and byPhysX as ``physx3d_*`` (its TUs compiled with the rename header this emits).The aliased wrappers are derived from the same declarations, so the second- backend cannot drift from the first — it is the same list under a new name,- behind the gate the build defines when it links that backend.+ backend cannot drift from the first — it is the same list under a new name, in+ a TU of its own (generate_aliases) that is linked wherever the backend is."""src: str # prefix in the header, e.g. 'physics3d_'dst: str # prefix of the second implementation, e.g. 'physx3d_'- gate: str # the define the build sets when it links it, e.g. 'ES_ENABLE_PHYSX'+ gate: str # the define the build sets where it links it, e.g. 'ES_ENABLE_PHYSX'@staticmethoddef parse(spec: str) -> 'Alias':@@ -521,26 +521,6 @@ class NativeFunctionsGenerator:self.skipped.extend(skipped)lines.append('')- # The aliased copies: declared here (the header declares only the original- # names), then wrapped and registered like any other entry point.- for alias in self.aliases:- copies = [fn for fn in functions if fn.extern_c and fn.name.startswith(alias.src)]- if not copies:- raise ValueError(f'alias {alias.src}->{alias.dst}: no extern "C" entry point '- f'starts with {alias.src}')- lines.append(f'#ifdef {alias.gate}')- lines.append('extern "C" {')- lines.extend(alias.rename(fn.decl) for fn in copies)- lines.append('}')- lines.append('#endif')- lines.append('')- functions = functions + [fn._replace(- name=alias.rename(fn.name),- guards=fn.guards + (alias.gate,),- heap_return=alias.rename(fn.heap_return) if fn.heap_return else None,- decl=alias.rename(fn.decl),- ) for fn in copies]-for fn in sorted(functions, key=lambda f: f.name):self.emitted.append(fn.name)lines.extend(self._wrapper(fn))@@ -556,6 +536,64 @@ class NativeFunctionsGenerator:lines.append('')return '\n'.join(lines)+ @staticmethod+ def alias_register_name(alias: 'Alias') -> str:+ """The function the alias TU registers its wrappers through:+ ``esn_register_functions_physx3d`` for the ``physx3d_`` copy."""+ return f'esn_register_functions_{alias.dst.rstrip("_")}'++ def generate_aliases(self) -> str:+ """The aliased copies as a TU of their own, with their own registration+ function (see alias_register_name).++ Its own TU because it is linked where the second implementation is: into+ the host on a desktop, into a separate library on Android (so an app that+ did not pick that implementation does not carry it). Nothing here is+ gated — the TU is compiled only where its implementation is linked."""+ lines = [+ '// Auto-generated by EHT (native_functions) — DO NOT EDIT.',+ '// A second implementation of a C surface, wrapped from the SAME declarations',+ '// as the first under its own prefix, and registered by its own function.',+ f'#include "{self.shim_header}"',+ '',+ '#include <cstdint>',+ '#include <string>',+ '#include <vector>',+ '',+ ]+ functions: List[Function] = []+ for include, text in self.headers:+ parsed, _ = parse_header(text)+ functions.extend(parsed)+ for alias in self.aliases:+ copies = [fn for fn in functions if fn.extern_c and fn.name.startswith(alias.src)]+ if not copies:+ raise ValueError(f'alias {alias.src}->{alias.dst}: no extern "C" entry point '+ f'starts with {alias.src}')+ renamed = sorted((fn._replace(+ name=alias.rename(fn.name),+ heap_return=alias.rename(fn.heap_return) if fn.heap_return else None,+ decl=alias.rename(fn.decl),+ ) for fn in copies), key=lambda f: f.name)+ # Declared here: the shared header declares only the original names.+ lines.append('extern "C" {')+ lines.extend(fn.decl for fn in renamed)+ lines.append('}')+ lines.append('')+ for fn in renamed:+ self.emitted.append(fn.name)+ lines.extend(self._wrapper(fn))+ lines.append(f'void {self.alias_register_name(alias)}(esjs::Val global) {{')+ for fn in renamed:+ js_arity = len([p for p in fn.params if p.cpp_type not in _IMPLICIT_REFS])+ lines.extend(f'#ifdef {g}' for g in fn.guards)+ js = self._js_name(fn.name)+ lines.append(f' esjs::setFunction(global, "{js}", {js}, {js_arity});')+ lines.extend('#endif' for _ in fn.guards)+ lines.append('}')+ lines.append('')+ return '\n'.join(lines)+def generate_alias_header(self) -> str:"""``#define <src>name <dst>name`` for every C name an alias renames — whatthe second implementation's TUs are compiled with (forced include), so the