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
fix(android): make the availability guards mean something below the floor
esengine1a90c22d4ec8
diff --git a/build-tools/cli.js b/build-tools/cli.jsindex f396bb37f..1528d5638 100644--- a/build-tools/cli.js+++ b/build-tools/cli.js@@ -167,7 +167,9 @@ program.option('--dawn-build <dir>', 'Dawn build dir for this target (default: <dawn>/out-<target>, built if absent)').option('--quickjs <dir>', 'QuickJS-ng source dir (default: the pinned checkout; or ESTELLA_QUICKJS_DIR)').option('--abi <abi>', 'Android ABI', 'arm64-v8a')- .option('--platform <platform>', 'Android platform', 'android-24')+ // No default: the floor is the manifest's, and repeating it here is how the+ // two drift. An unset value reaches androidMinPlatform() in the task.+ .option('--platform <platform>', 'Android platform (default: the manifest\'s minSdkVersion)').option('--ios-min <version>', 'iOS deployment target', '17.0').option('--simulator', 'iOS: build the simulator slice (needs a simulator Dawn)', false).option('--package', 'Assemble the app around --content from the installed runtime template: Android a signed APK, iOS an Xcode project', false)diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.jsindex 0b3c93154..e00581edd 100644--- a/build-tools/tasks/native.js+++ b/build-tools/tasks/native.js@@ -17,6 +17,7 @@ import { runCommand, getCpuCount, resolvePython } from '../utils/emscripten.js';import { requireSdk, requireNdk, sdkCmake } from '../utils/android.js';import { emitNativeTemplate, writeTemplateIndex, readEngineVersion } from './nativeTemplateEmit.js';import { fetchNativeDeps, pinnedDep, ensureDawnBuild, dawnLibrary, DAWN_TARGETS } from './nativeDeps.js';+import { androidMinPlatform } from '../utils/androidFloor.js';import {ANDROID_ABIS, BYTECODE_FILE, findTemplate, iosTemplateSources, templateStoreDir,} from '../utils/nativeTemplate.js';@@ -319,7 +320,7 @@ async function buildAndroidHost(options) {// into a load-time requirement. At android-33 that shipped a host which could// not dlopen below API 31: `cannot locate symbol APerformanceHint_getManager`,// on Android 10 and 11, before a line of our code ran.- const { abi = 'arm64-v8a', platform = 'android-24' } = options;+ const { abi = 'arm64-v8a', platform = androidMinPlatform() } = options;const rootDir = config.paths.root;const sdk = requireSdk();@@ -327,7 +328,7 @@ async function buildAndroidHost(options) {const toolchain = path.join(ndk, 'build', 'cmake', 'android.toolchain.cmake');const { cmake, ninja } = sdkCmake(sdk);- const { dawnDir, dawnBuild } = await dawnPaths(options, 'android', { ndk, cmake, ninja });+ const { dawnDir, dawnBuild } = await dawnPaths({ ...options, platform }, 'android', { ndk, cmake, ninja });// One build tree per ABI, beside the generated sources they share — a second// architecture must not overwrite the first one's objects.const buildDir = path.join(rootDir, 'build/cmake/native', abi);@@ -349,6 +350,17 @@ async function buildAndroidHost(options) {`-DCMAKE_TOOLCHAIN_FILE=${toolchain}`,`-DANDROID_ABI=${abi}`,`-DANDROID_PLATFORM=${platform}`,+ // Without this the NDK marks every symbol newer than the platform+ // `unavailable` outright — a hard compile error that no availability+ // guard can satisfy, because the annotation means "this build cannot see+ // it" rather than "call me under a check". ON makes those references+ // weak, which is what gives `__builtin_available` something to test.+ //+ // Turning it on used to be the riskier choice: while the floor equalled+ // the newest API the host called, dropping the flag changed nothing and+ // would have gone unnoticed. Below that floor it cannot — the build stops+ // and names the symbol, which is how this line came to be here.+ '-DANDROID_WEAK_API_DEFS=ON','-DANDROID_STL=c++_shared','-DCMAKE_BUILD_TYPE=Release',// Emit build/cmake/native/compile_commands.json so editor IntelliSense (thediff --git a/build-tools/tasks/nativeDeps.js b/build-tools/tasks/nativeDeps.jsindex f681d7631..b285437a9 100644--- a/build-tools/tasks/nativeDeps.js+++ b/build-tools/tasks/nativeDeps.js@@ -10,6 +10,7 @@// without a flag.import path from 'path';+import { androidMinPlatform } from '../utils/androidFloor.js';import { existsSync, readFileSync } from 'fs';import { mkdir } from 'fs/promises';import config from '../build.config.js';@@ -109,10 +110,18 @@ export function dawnLibrary(dawnBuild, target) {/** Dawn's build directory for a target. Android's is per-ABI — an emulator build* and a device build are different binaries — with the default ABI keeping the- * plain name a checkout may already have. */-export function dawnBuildDir(dawn, target, abi) {- const suffix = target === 'android' && abi && abi !== 'arm64-v8a' ? `-${abi}` : '';- return path.join(dawn, DAWN_TARGETS[target].out + suffix);+ * plain name a checkout may already have.+ *+ * The API level is part of it for the same reason the ABI is: a Dawn compiled+ * against a newer platform links symbols the host's own floor promised not to+ * need, and the result installs and then fails to load on the versions the floor+ * exists to cover. Sharing one directory across levels made lowering the floor a+ * no-op on whichever machine already had a build. */+export function dawnBuildDir(dawn, target, abi, androidPlatform) {+ if (target !== 'android') return path.join(dawn, DAWN_TARGETS[target].out);+ const abiSuffix = abi && abi !== 'arm64-v8a' ? `-${abi}` : '';+ const apiSuffix = androidPlatform ? `-${String(androidPlatform).replace(/^android-/, 'api')}` : '';+ return path.join(dawn, DAWN_TARGETS[target].out + abiSuffix + apiSuffix);}/**@@ -124,7 +133,8 @@ export function dawnBuildDir(dawn, target, abi) {export async function ensureDawnBuild(options) {const target = DAWN_TARGETS[options.target];if (!target) throw new Error(`Unknown Dawn target ${options.target}.`);- const buildDir = options.buildDir || dawnBuildDir(options.dawn, options.target, options.abi);+ const buildDir = options.buildDir+ || dawnBuildDir(options.dawn, options.target, options.abi, options.androidPlatform);if (existsSync(dawnLibrary(buildDir, options.target))) return buildDir;const cmake = options.cmake || 'cmake';@@ -145,7 +155,7 @@ export async function ensureDawnBuild(options) {? [`-DCMAKE_TOOLCHAIN_FILE=${path.join(options.ndk, 'build', 'cmake', 'android.toolchain.cmake')}`,`-DANDROID_ABI=${options.abi || 'arm64-v8a'}`,- `-DANDROID_PLATFORM=${options.androidPlatform || 'android-24'}`,+ `-DANDROID_PLATFORM=${options.androidPlatform || androidMinPlatform()}`,'-DANDROID_STL=c++_shared','-DDAWN_ENABLE_VULKAN=ON', '-DDAWN_ENABLE_METAL=OFF',// Shared on Android (the APK ships the .so); static on iOS (an appdiff --git a/build-tools/tasks/nativeTemplateEmit.js b/build-tools/tasks/nativeTemplateEmit.jsindex 0918b0038..76b045bdd 100644--- a/build-tools/tasks/nativeTemplateEmit.js+++ b/build-tools/tasks/nativeTemplateEmit.js@@ -10,6 +10,7 @@// to put a game on a phone.import path from 'path';+import { androidMinPlatform } from '../utils/androidFloor.js';import { existsSync, readFileSync, writeFileSync } from 'fs';import { createHash } from 'crypto';import { mkdir, rm, cp, readdir } from 'fs/promises';@@ -200,7 +201,7 @@ export async function emitNativeTemplate(options) {spineVersion: options.spineVersion || '4.2',...(platform === 'ios' ? { deploymentTarget: options.deploymentTarget || '17.0' } : {}),...(platform === 'android'- ? { androidPlatform: options.androidPlatform || 'android-24', abis: templateAbis(dir) }+ ? { androidPlatform: options.androidPlatform || androidMinPlatform(), abis: templateAbis(dir) }: {}),});diff --git a/build-tools/utils/androidFloor.js b/build-tools/utils/androidFloor.jsnew file mode 100644index 000000000..41bbfd64b--- /dev/null+++ b/build-tools/utils/androidFloor.js@@ -0,0 +1,44 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The Android API floor, read from the one place that declares it.+ *+ * The NDK must build against exactly the manifest's minSdkVersion. Above it,+ * every `__builtin_available` guard compiles out and its symbol becomes a+ * load-time requirement, so the app installs on an older device and then fails+ * before a line of our code runs — which is how a build targeted at android-33+ * shipped a host that could not dlopen below API 31.+ *+ * That coupling used to be a rule someone had to remember while editing four+ * defaults in four files. Reading the number instead means the manifest is the+ * only place it is written, and the two cannot disagree.+ */+import { readFileSync } from 'fs';+import path from 'path';++import config from '../build.config.js';++/** The template every packaged game's manifest is filled from. */+export function manifestTemplatePath() {+ return path.join(config.paths.root, 'native', 'android', 'host', 'AndroidManifest.xml.in');+}++let cached = null;++/** `minSdkVersion` as declared, e.g. 24. */+export function androidMinSdk() {+ if (cached !== null) return cached;+ const template = manifestTemplatePath();+ const found = /android:minSdkVersion="(\d+)"/.exec(readFileSync(template, 'utf8'));+ if (!found) {+ throw new Error(`No android:minSdkVersion in ${template} — it is the single source for `+ + 'the API level the NDK builds against, so a build cannot proceed without it.');+ }+ cached = Number(found[1]);+ return cached;+}++/** The same number as the NDK spells it, e.g. `android-24`. */+export function androidMinPlatform() {+ return `android-${androidMinSdk()}`;+}diff --git a/native/host/platform/android.cpp b/native/host/platform/android.cppindex e214fe345..d481edc18 100644--- a/native/host/platform/android.cpp+++ b/native/host/platform/android.cpp@@ -518,19 +518,17 @@ void onAppCmd(android_app* app, int32_t cmd) {//// Resolved by hand, through dlsym, rather than called directly.//-// ADPF is API 33 and this host builds against the manifest's floor, so the NDK-// marks those four symbols `unavailable`: a hard compile error, and no-// `__builtin_available` guard changes that — the annotation is not "call me-// under a check", it is "this build cannot see me". Raising the build target is-// what makes them callable, and that is precisely the mistake being fixed here:-// at android-33 every availability guard in this file became dead code and every-// guarded symbol became a load-time requirement, so the released host could not-// dlopen on Android 10 or 11 at all.+// This predates the build turning on ANDROID_WEAK_API_DEFS, which is what makes+// `__builtin_available` mean anything: without it the NDK marks a newer symbol+// `unavailable` outright — not "call me under a check" but "this build cannot+// see me" — and no guard satisfies that. Every other guarded call here now goes+// through the flag; ADPF still comes through dlsym because it works and this is+// not the change to test it in.//-// The NDK's own answer is ANDROID_WEAK_API_DEFS, which turns such symbols into-// weak references. Looking them up here instead keeps the decision in the code-// that depends on it, where it is visible, rather than in a toolchain flag whose-// absence would silently restore the same class of failure.+// The objection to the flag was that its absence would silently restore the+// failure it prevents. That was true while the floor equalled the newest API+// this file called, when dropping it changed nothing. Below that floor it is a+// compile error naming the symbol, which is how the flag got turned on.struct PerformanceHints {void* session = nullptr;