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.

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.js
index 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.ts
index 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.ProcessEnv
export 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.js
index 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/desktop
index 51b098ef1..4f5e6f652 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 51b098ef1d904ba7be21edec07603d76756521cd
+Subproject commit 4f5e6f65296313e1c5753c989c164a8ccd463790
diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdx
index 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's
glancing off the edge of a hinged door) ends differently on the two solvers, as
it 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 PhysX
project there runs on Jolt and logs that once at startup.
## Bodies
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx
index 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.txt
index 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_physics3d
estella_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_spine
estella_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.cpp
index 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.cpp
new file mode 100644
index 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.ts
index 78b91663e..95361e8b1 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -70,7 +70,7 @@ import { orientationCss, orientationOverlayHtml, orientationLockScript, orientat
import { 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.ts
index 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.mjs
index 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__.py
index 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 1
gen = 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.py
index 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 by
PhysX 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'
@staticmethod
def 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 — what
the second implementation's TUs are compiled with (forced include), so the