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): the floor is Android 7, and the font path can stand on it

esengine3d9808d96b7b
diff --git a/.github/workflows/android-compat.yml b/.github/workflows/android-compat.yml
index 70f652df2..f895eaad4 100644
--- a/.github/workflows/android-compat.yml
+++ b/.github/workflows/android-compat.yml
@@ -46,9 +46,9 @@ on:
default: 'space-shooter'
type: string
api-floor:
- description: 'Oldest API level to test (29 = Android 10).'
+ description: 'Oldest API level to test (24 = Android 7.0, the manifest floor).'
required: false
- default: '29'
+ default: '24'
type: string
template-source:
description: 'Which runtime template to wrap: the latest release, this branch (~35 min), or decide from what the PR touches.'
@@ -68,10 +68,16 @@ concurrency:
cancel-in-progress: true
env:
- # Android 10. The manifest claims 26, which is a wider promise than anything
- # here checks — raising this floor is a decision about what we support, so it is
- # stated once, in one place, rather than implied by a matrix.
- ANDROID_API_FLOOR: ${{ inputs.api-floor || '29' }}
+ # Android 7.0, matching the manifest's minSdkVersion — the promise and the thing
+ # that checks it must be the same number, or one of them is decoration. Changing
+ # this floor is a decision about what we support, so it is stated once, in one
+ # place, rather than implied by a matrix.
+ #
+ # An emulator below API 28 may have no Vulkan at all, and the host has no GLES
+ # path, so those rows can red for the runner's reasons rather than ours. That is
+ # a result worth having rather than a reason to hide them: this matrix exists to
+ # say which versions work, and "we cannot tell from CI" is one of the answers.
+ ANDROID_API_FLOOR: ${{ inputs.api-floor || '24' }}
ANDROID_PROFILE: pixel_6
CANARY_EXAMPLES: ${{ inputs.examples || 'space-shooter' }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4abb9a479..deed33f20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,33 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Changed
+
+- **Android's minimum is API 24 (Android 7.0), lowered from 29.** The floor was 29
+ because the font path called `AFontMatcher_create` and nothing below it could
+ answer; on 24 through 28 the engine now picks the font out of `/system/fonts`
+ itself, asking each candidate whether it has a glyph for the character rather
+ than trusting a family name. Read the Vulkan requirement alongside this: it is
+ unchanged and still `required="true"`, and it filters far more devices than the
+ API level does, so what 24 adds is Android 7/8-era hardware that has a Vulkan
+ driver — not every phone on those releases. The compatibility matrix now starts
+ at 24; emulators below API 28 may have no Vulkan, so those rows can report "no
+ data" rather than a verdict.
+
+### Fixed
+
+- **Saves no longer live in a directory the platform may delete.** Key/value
+ storage went to the host's cache directory, whose stated purpose was the
+ regenerable bytecode cache. On iOS that is `NSCachesDirectory`, which the system
+ empties when it wants the space back and no backup includes — so a player's
+ saves and settings could vanish between launches. Android put the same file in
+ `files/`, which nothing reclaims: one API, two opposite promises. There is now a
+ durable directory distinct from the reclaimable one (Application Support on iOS,
+ `internalDataPath` on Android) and storage writes there. Android's cache
+ directory is also a real cache directory now, so the hot-update store can be
+ reclaimed instead of growing forever. Writes go through a temp file and a
+ rename, so a kill mid-write cannot truncate a save.
+
## [0.40.0] - 2026-08-02
The agent went from working to being pleasant to work with. It answers from the keyboard
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 7837fdc32..f396bb37f 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -167,7 +167,7 @@ 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-29')
+ .option('--platform <platform>', 'Android platform', 'android-24')
.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.js
index 0831f24d8..0b3c93154 100644
--- a/build-tools/tasks/native.js
+++ b/build-tools/tasks/native.js
@@ -319,7 +319,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-29' } = options;
+ const { abi = 'arm64-v8a', platform = 'android-24' } = options;
const rootDir = config.paths.root;
const sdk = requireSdk();
diff --git a/build-tools/tasks/nativeDeps.js b/build-tools/tasks/nativeDeps.js
index 027ec349c..f681d7631 100644
--- a/build-tools/tasks/nativeDeps.js
+++ b/build-tools/tasks/nativeDeps.js
@@ -145,7 +145,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-29'}`,
+ `-DANDROID_PLATFORM=${options.androidPlatform || 'android-24'}`,
'-DANDROID_STL=c++_shared',
'-DDAWN_ENABLE_VULKAN=ON', '-DDAWN_ENABLE_METAL=OFF',
// Shared on Android (the APK ships the .so); static on iOS (an app
diff --git a/build-tools/tasks/nativeTemplateEmit.js b/build-tools/tasks/nativeTemplateEmit.js
index 1ce6293ab..0918b0038 100644
--- a/build-tools/tasks/nativeTemplateEmit.js
+++ b/build-tools/tasks/nativeTemplateEmit.js
@@ -200,7 +200,7 @@ export async function emitNativeTemplate(options) {
spineVersion: options.spineVersion || '4.2',
...(platform === 'ios' ? { deploymentTarget: options.deploymentTarget || '17.0' } : {}),
...(platform === 'android'
- ? { androidPlatform: options.androidPlatform || 'android-29', abis: templateAbis(dir) }
+ ? { androidPlatform: options.androidPlatform || 'android-24', abis: templateAbis(dir) }
: {}),
});
diff --git a/build-tools/utils/apk.js b/build-tools/utils/apk.js
index 25f9937de..77add482c 100644
--- a/build-tools/utils/apk.js
+++ b/build-tools/utils/apk.js
@@ -28,9 +28,10 @@ import { fillTemplate, androidScreenOrientation } from './nativeApp.js';
* smaller page size also divides. */
const PAGE_ALIGNMENT = 16384;
-/** APK Signature Scheme v2. minSdk 29 is well past the API 24 that introduced it,
- * so v1 (JAR signing) would be dead weight — and its PKCS#7 is the only part of
- * APK signing that is genuinely hard to write. */
+/** APK Signature Scheme v2, introduced in API 24 — exactly the minSdk, so every
+ * device that can install this can verify it and v1 (JAR signing) would be dead
+ * weight. Its PKCS#7 is the only part of APK signing that is genuinely hard to
+ * write, so a floor below 24 would cost considerably more than one number. */
const V2_BLOCK_ID = 0x7109871a;
const SIG_ALGO_RSA_PKCS1_SHA256 = 0x0103;
const APK_SIG_BLOCK_MAGIC = Buffer.from('APK Sig Block 42', 'latin1');
diff --git a/build-tools/utils/gradleProject.js b/build-tools/utils/gradleProject.js
index 830537fd2..68034dab8 100644
--- a/build-tools/utils/gradleProject.js
+++ b/build-tools/utils/gradleProject.js
@@ -54,7 +54,7 @@ export function gradleManifest(templateXml, app) {
HAS_CODE: 'true',
});
- const minSdk = Number(/android:minSdkVersion="(\d+)"/.exec(filled)?.[1] ?? 29);
+ const minSdk = Number(/android:minSdkVersion="(\d+)"/.exec(filled)?.[1] ?? 24);
const targetSdk = Number(/android:targetSdkVersion="(\d+)"/.exec(filled)?.[1] ?? 33);
const xml = filled
diff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdx
index 37f2cc72e..662f2ef93 100644
--- a/docs/astro/src/content/docs/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/guides/mobile.mdx
@@ -53,18 +53,30 @@ where Xcode does the assembling.
| | Android | iOS |
|---|---|---|
-| Minimum OS | **Android 10** (API 29) | **iOS 17.0** |
+| Minimum OS | **Android 7.0** (API 24) | **iOS 17.0** |
| Declared target | API 33 | — |
| CPU | `arm64-v8a` (every real device) + `x86_64` (the emulator) | arm64 device + simulator slice |
| GPU | **Vulkan 1.0.3 required** — declared `required="true"`, so a device without it does not see the app on Play | Metal |
-Android's floor is 29 because the engine's font path calls `AFontMatcher_create`,
-which is API 29 — below that there is nothing to fall back to. It was **declared** as
-26 through v0.37.0, which was a claim rather than a capability: those builds install
-on Android 10 and 11 and then fail to start, because the NDK was told to build against
-a higher API and turned every guarded symbol into a load-time requirement. Nothing
-that ran on v0.37.0 stops running on v0.38.0 — the number now says what was always
-true.
+Android's floor is 24 because that is where Vulkan and `AChoreographer` both arrive,
+and the engine cannot run without either. Read the GPU row before the OS row, though:
+Vulkan stayed **optional** for hardware until long after Android 7, so `required="true"`
+filters out far more devices than the API level does. What API 24 adds is the Android
+7 and 8 era hardware that does have a Vulkan driver — largely the flagships of the
+time — not every phone still running those releases.
+
+The floor was 29 through v0.40.0, because the font path called `AFontMatcher_create`
+and that is API 29 with nothing below it to fall back to. There is now: on 24 through
+28 the engine picks the font out of `/system/fonts` itself, asking each candidate
+whether it actually has a glyph for the character rather than trusting a family name.
+System font aliases and the platform's own fallback ordering are lost, so a character
+two fonts both cover may resolve to the other one — it draws either way.
+
+<Aside type="caution">
+ API 24–27 is the least verifiable tier we ship. A hosted emulator below API 28
+ may have no Vulkan at all, so CI can report "cannot tell" for those rows rather
+ than pass or fail. Test on real hardware before promising an Android 7 build.
+</Aside>
<Aside type="note">
The Vulkan requirement follows from the runtime: the engine renders through Dawn,
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
index 68ab13834..f5d1c8f1d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
@@ -46,16 +46,27 @@ Android 两者都给,是因为它两者都做得到:编辑器既能直接装配
| | Android | iOS |
|---|---|---|
-| 最低系统 | **Android 10**(API 29) | **iOS 17.0** |
+| 最低系统 | **Android 7.0**(API 24) | **iOS 17.0** |
| 声明的 target | API 33 | — |
| CPU | `arm64-v8a`(所有真机)+ `x86_64`(模拟器) | arm64 真机 + 模拟器切片 |
| GPU | **要求 Vulkan 1.0.3**——声明为 `required="true"`,不具备的设备在 Play 上根本看不到这个应用 | Metal |
-Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,那是 API 29——
-再往下没有可退的路。直到 v0.37.0 它**声明**的都还是 26,而那是个说法而非能力:
-那些构建能装到 Android 10 和 11 上,然后起不来——因为 NDK 被要求按更高的 API 构建,
-于是把每个受保护的符号都变成了加载期的硬依赖。v0.37.0 上能跑的东西在 v0.38.0 上
-一样能跑,这个数字只是终于说了实话。
+Android 的下限是 24,因为 Vulkan 和 `AChoreographer` 都在这一版到齐,而引擎缺哪个都跑
+不了。不过 GPU 那行要比系统那行先看:Vulkan 在硬件上一直是**可选**的,直到远晚于
+Android 7 才普及,所以 `required="true"` 挡掉的设备比 API 级别挡掉的多得多。API 24
+真正带来的是 Android 7、8 时代**有 Vulkan 驱动**的机器——主要是当年的旗舰——而不是
+所有还在跑这些版本的手机。
+
+直到 v0.40.0 下限还是 29,因为字体路径调用 `AFontMatcher_create`,那是 API 29 且往下
+没有可退的路。现在有了:在 24 到 28 上,引擎自己从 `/system/fonts` 里挑字体,逐个问候选
+字体**是否真的有这个字的字形**,而不是去信一个 family 名字。系统的字体别名和它自己的
+回退顺序都拿不到了,所以一个两种字体都覆盖的字可能落到另一种上——两种都画得出来。
+
+<Aside type="caution">
+ API 24–27 是我们发布的所有档位里最难验证的一档。托管的模拟器在 API 28 以下可能
+ 完全没有 Vulkan,所以 CI 对这几行给出的可能是「测不出来」而不是通过或失败。要承诺
+ Android 7 的构建,先在真机上验。
+</Aside>
<Aside type="note">
Vulkan 的要求来自这套运行时:引擎经 Dawn 渲染,而 Dawn 的 Android 后端就是 Vulkan。
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index 1e16cedab..0522add08 100644
--- a/native/CMakeLists.txt
+++ b/native/CMakeLists.txt
@@ -243,6 +243,7 @@ if(ESTELLA_QUICKJS_DIR)
host/media/audio_spectrum.cpp
host/media/ktx2_decode.cpp
host/media/glyph_raster.cpp
+ host/media/font_scan.cpp
"${BASIS_TRANSCODER}" "${BASIS_ZSTD}" "${NATIVE_BINDINGS}" "${NATIVE_FN_BINDINGS}")
if(ESTELLA_IOS)
diff --git a/native/android/host/AndroidManifest.xml.in b/native/android/host/AndroidManifest.xml.in
index 787912588..80ab9421e 100644
--- a/native/android/host/AndroidManifest.xml.in
+++ b/native/android/host/AndroidManifest.xml.in
@@ -9,21 +9,25 @@
restarted for. `hasCode` follows whether the Java shim compiled — the game is
native, and the only Java in the package is the IME's side of a text field.
- minSdkVersion 29, and the NDK MUST build against the same number (`--platform`,
- build-tools/tasks/native.js). The host calls AFontMatcher_create unguarded and
- that is API 29, so nothing below it could ever have run; 26 promised three
- releases the code never supported. The equality is what makes the availability
- guards work: the NDK emits a weak reference only for an API newer than the
- build target, so building above the declared floor compiles every
+ minSdkVersion 24 (Android 7.0), and the NDK MUST build against the same number
+ (`--platform`, build-tools/tasks/native.js). The equality is what makes the
+ availability guards work: the NDK emits a weak reference only for an API newer
+ than the build target, so building above the declared floor compiles every
`__builtin_available` out and turns its symbol into a load-time requirement.
Built at android-33, the released host could not dlopen below API 31 —
"cannot locate symbol APerformanceHint_getManager" on Android 10 and 11.
+
+ 24 is where Vulkan and AChoreographer both arrive, which is the real floor: the
+ host has no GLES path, so a device without Vulkan cannot run it at any API
+ level. The uses-feature below is what keeps such a device from being offered
+ the app at all, and it does more filtering than minSdkVersion does — Vulkan was
+ optional until well after 24.
-->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="@APP_ID@"
android:versionCode="@VERSION_CODE@"
android:versionName="@VERSION_NAME@">
- <uses-sdk android:minSdkVersion="29" android:targetSdkVersion="33" />
+ <uses-sdk android:minSdkVersion="24" android:targetSdkVersion="33" />
<uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />
<application android:label="@APP_NAME@" android:icon="@mipmap/ic_launcher"
android:hasCode="@HAS_CODE@" android:extractNativeLibs="false">
diff --git a/native/host/media/font_scan.cpp b/native/host/media/font_scan.cpp
new file mode 100644
index 000000000..b38de8b20
--- /dev/null
+++ b/native/host/media/font_scan.cpp
@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file font_scan.cpp
+ * @brief Directory font matching by codepoint coverage.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+#include "font_scan.hpp"
+
+// The implementation lives in glyph_raster.cpp; this TU only needs the decls.
+#include "stb_truetype.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <cstring>
+#include <dirent.h>
+#include <unordered_map>
+#include <vector>
+
+using namespace esengine;
+
+namespace eshost {
+namespace {
+
+bool hasSuffix(const std::string& s, const char* suffix) {
+ const size_t n = strlen(suffix);
+ if (s.size() < n) return false;
+ return std::equal(s.end() - n, s.end(), suffix,
+ [](char a, char b) { return std::tolower(a) == std::tolower(b); });
+}
+
+/** Letters and digits only, lowercased — so "Noto Sans CJK" and
+ * "NotoSansCJK-Regular.ttc" can be compared without either being wrong. */
+std::string fold(const std::string& s) {
+ std::string out;
+ out.reserve(s.size());
+ for (const char c : s) {
+ if (std::isalnum((unsigned char)c)) out.push_back((char)std::tolower(c));
+ }
+ return out;
+}
+
+std::vector<u8> readFile(const std::string& path) {
+ std::vector<u8> bytes;
+ FILE* f = fopen(path.c_str(), "rb");
+ if (!f) return bytes;
+ fseek(f, 0, SEEK_END);
+ const long size = ftell(f);
+ fseek(f, 0, SEEK_SET);
+ if (size > 0) {
+ bytes.resize((size_t)size);
+ if (fread(bytes.data(), 1, bytes.size(), f) != bytes.size()) bytes.clear();
+ }
+ fclose(f);
+ return bytes;
+}
+
+/** Every font file in @p dir, listed once. Names only — a system font directory
+ * holds well over a hundred megabytes across its CJK files, so nothing is read
+ * until a candidate is actually being considered. */
+const std::vector<std::string>& listing(const char* dir) {
+ static std::unordered_map<std::string, std::vector<std::string>> cache;
+ auto it = cache.find(dir);
+ if (it != cache.end()) return it->second;
+
+ std::vector<std::string> names;
+ if (DIR* d = opendir(dir)) {
+ while (const dirent* e = readdir(d)) {
+ const std::string name = e->d_name;
+ if (hasSuffix(name, ".ttf") || hasSuffix(name, ".otf") || hasSuffix(name, ".ttc")) {
+ names.push_back(name);
+ }
+ }
+ closedir(d);
+ }
+ // Stable order, so the same device answers the same way every launch.
+ std::sort(names.begin(), names.end());
+ return cache.emplace(dir, std::move(names)).first->second;
+}
+
+/** Generic CSS families have no file of their own; these are what Android has
+ * shipped under those names since well before the floor. */
+const char* const* genericStems(const std::string& folded, size_t& count) {
+ static const char* kSans[] = {"roboto", "droidsans", "notosans"};
+ static const char* kSerif[] = {"notoserif", "droidserif"};
+ static const char* kMono[] = {"droidsansmono", "cutivemono", "notomono"};
+ if (folded == "serif") { count = 2; return kSerif; }
+ if (folded == "monospace" || folded == "mono") { count = 3; return kMono; }
+ count = 3;
+ return kSans; // sans-serif, and anything unrecognized
+}
+
+int rank(const std::string& name, const std::string& family, bool wantBold, bool wantItalic) {
+ const std::string folded = fold(name);
+ const std::string wanted = fold(family.empty() ? "sans-serif" : family);
+
+ int score = 0;
+ if (!wanted.empty() && folded.find(wanted) != std::string::npos) {
+ score += 100;
+ } else {
+ size_t count = 0;
+ const char* const* stems = genericStems(wanted, count);
+ for (size_t i = 0; i < count; ++i) {
+ if (folded.find(stems[i]) != std::string::npos) { score += 60 - (int)i; break; }
+ }
+ }
+ // Style is read off the filename because the alternative is parsing every
+ // candidate's OS/2 table to sort candidates we have not read yet. Android's
+ // own files are named for their style; a device whose are not still gets a
+ // correct glyph, drawn from a face this scores lower.
+ const bool isBold = folded.find("bold") != std::string::npos;
+ const bool isItalic = folded.find("italic") != std::string::npos
+ || folded.find("oblique") != std::string::npos;
+ if (isBold == wantBold) score += 10;
+ if (isItalic == wantItalic) score += 5;
+ return score;
+}
+
+/** Paths that covered a codepoint before, newest first. CJK resolves to one huge
+ * file, and without this every glyph in a sentence would re-read the candidates
+ * ahead of it before arriving at the same answer. */
+std::vector<std::string>& recentFor(const std::string& family, int style) {
+ static std::unordered_map<std::string, std::vector<std::string>> mru;
+ return mru[family + "\x1f" + std::to_string(style)];
+}
+
+void remember(std::vector<std::string>& mru, const std::string& name) {
+ mru.erase(std::remove(mru.begin(), mru.end(), name), mru.end());
+ mru.insert(mru.begin(), name);
+ if (mru.size() > 4) mru.resize(4);
+}
+
+/** Does any face in this file draw @p codepoint? Fills the face index if so. */
+bool covers(const std::vector<u8>& bytes, u32 codepoint, int& faceIndex) {
+ const int faces = stbtt_GetNumberOfFonts(bytes.data());
+ for (int i = 0; i < (faces > 0 ? faces : 1); ++i) {
+ const int offset = stbtt_GetFontOffsetForIndex(bytes.data(), i);
+ if (offset < 0) continue;
+ stbtt_fontinfo info{};
+ if (!stbtt_InitFont(&info, bytes.data(), offset)) continue;
+ if (stbtt_FindGlyphIndex(&info, (int)codepoint) != 0) { faceIndex = i; return true; }
+ }
+ return false;
+}
+
+} // namespace
+
+FontFile scanFontDir(const char* dir, const std::string& family, u32 codepoint, int style) {
+ FontFile out;
+ const std::vector<std::string>& names = listing(dir);
+ if (names.empty()) return out;
+
+ const bool wantBold = (style & GLYPH_BOLD) != 0;
+ const bool wantItalic = (style & GLYPH_ITALIC) != 0;
+ const u32 wanted = codepoint ? codepoint : (u32)'A';
+
+ std::vector<std::string>& mru = recentFor(family, style);
+ std::vector<std::string> order(mru);
+ std::vector<std::string> rest;
+ for (const std::string& name : names) {
+ if (std::find(mru.begin(), mru.end(), name) == mru.end()) rest.push_back(name);
+ }
+ std::stable_sort(rest.begin(), rest.end(), [&](const std::string& a, const std::string& b) {
+ return rank(a, family, wantBold, wantItalic) > rank(b, family, wantBold, wantItalic);
+ });
+ order.insert(order.end(), rest.begin(), rest.end());
+
+ for (const std::string& name : order) {
+ const std::string path = std::string(dir) + "/" + name;
+ std::vector<u8> bytes = readFile(path);
+ if (bytes.empty()) continue;
+ int faceIndex = 0;
+ if (!covers(bytes, wanted, faceIndex)) continue; // freed on the next pass
+
+ const std::string folded = fold(name);
+ out.path = path;
+ out.bytes = std::move(bytes);
+ out.faceIndex = faceIndex;
+ out.syntheticBold = wantBold && folded.find("bold") == std::string::npos;
+ out.syntheticItalic = wantItalic && folded.find("italic") == std::string::npos
+ && folded.find("oblique") == std::string::npos;
+ remember(mru, name);
+ return out;
+ }
+ return out;
+}
+
+} // namespace eshost
diff --git a/native/host/media/font_scan.hpp b/native/host/media/font_scan.hpp
new file mode 100644
index 000000000..979e08d74
--- /dev/null
+++ b/native/host/media/font_scan.hpp
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file font_scan.hpp
+ * @brief Pick a font file out of a directory, for platforms with no matcher.
+ * @details {@link Platform::loadFont} asks for a file that covers one codepoint,
+ * which iOS answers with CoreText and Android with AFontMatcher — but
+ * AFontMatcher is API 29 and the Android floor is 24, so between them
+ * there is no OS matcher to ask. Choosing a file out of a directory of
+ * them is not Android knowledge, so it lives here beside the rasterizer
+ * that already owns stb_truetype rather than in one platform's glue.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+#pragma once
+
+#include "Host.hpp"
+
+#include <string>
+
+namespace eshost {
+
+/**
+ * The first font in @p dir that has a glyph for @p codepoint, preferring files
+ * whose name looks like @p family and the requested @p style.
+ *
+ * Coverage is decided by asking the font, not by trusting a name: a family is
+ * only the starting order, and the answer is whichever candidate actually draws
+ * the character. An empty {@link FontFile::path} means nothing in the directory
+ * covers it.
+ */
+FontFile scanFontDir(const char* dir, const std::string& family, esengine::u32 codepoint, int style);
+
+} // namespace eshost
diff --git a/native/host/platform/android.cpp b/native/host/platform/android.cpp
index f24eeeda4..e214fe345 100644
--- a/native/host/platform/android.cpp
+++ b/native/host/platform/android.cpp
@@ -32,6 +32,7 @@
#include "Host.hpp"
#include "media/glyph_raster.hpp" // GLYPH_BOLD / GLYPH_ITALIC, for the font match
+#include "media/font_scan.hpp" // the pre-29 stand-in for AFontMatcher
#define LOG_TAG "EstellaSDK"
@@ -226,7 +227,19 @@ struct AndroidPlatform final : eshost::Platform {
// installed families, applies weight/italic, and — the part worth having —
// falls back per codepoint, so CJK text resolves to Noto without the host
// hard-coding a single font path.
+ //
+ // Below 29 there is no such API, and `/system/fonts` is what the matcher is
+ // reading anyway. Scanning it ourselves loses the system's own family
+ // aliases and its ordering, so a codepoint two fonts both cover may resolve
+ // to the other one — the character draws either way, which is the property
+ // that matters.
eshost::FontFile loadFont(const std::string& family, u32 codepoint, int style) override {
+ if (__builtin_available(android 29, *)) return matchFont(family, codepoint, style);
+ return eshost::scanFontDir("/system/fonts", family, codepoint, style);
+ }
+
+ eshost::FontFile matchFont(const std::string& family, u32 codepoint, int style)
+ __attribute__((availability(android, introduced = 29))) {
eshost::FontFile out;
AFontMatcher* matcher = AFontMatcher_create();
if (!matcher) return out;
@@ -647,8 +660,8 @@ struct FrameDriver {
if (__builtin_available(android 29, *)) {
AChoreographer_postFrameCallback64(choreographer, &FrameDriver::onVsync64, this);
} else {
- // Deprecated in 29 and the only one that exists below it. minSdk is 26,
- // so this branch is the two releases the 64-bit call cannot serve — not
+ // Deprecated in 29 and the only one that exists below it. minSdk is 24,
+ // so this branch is the five releases the 64-bit call cannot serve — not
// an oversight, which is why the warning is turned off rather than the
// call changed.
#pragma clang diagnostic push