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): 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.ymlindex 70f652df2..f895eaad4 100644--- a/.github/workflows/android-compat.yml+++ b/.github/workflows/android-compat.yml@@ -46,9 +46,9 @@ on:default: 'space-shooter'type: stringapi-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: stringtemplate-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: trueenv:- # 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_6CANARY_EXAMPLES: ${{ inputs.examples || 'space-shooter' }}diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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-02The agent went from working to being pleasant to work with. It answers from the keyboarddiff --git a/build-tools/cli.js b/build-tools/cli.jsindex 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.jsindex 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.jsindex 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 appdiff --git a/build-tools/tasks/nativeTemplateEmit.js b/build-tools/tasks/nativeTemplateEmit.jsindex 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.jsindex 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.jsindex 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 = filleddiff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdxindex 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.mdxindex 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.txtindex 1e16cedab..0522add08 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -243,6 +243,7 @@ if(ESTELLA_QUICKJS_DIR)host/media/audio_spectrum.cpphost/media/ktx2_decode.cpphost/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.inindex 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 isnative, 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.cppnew file mode 100644index 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 eshostdiff --git a/native/host/media/font_scan.hpp b/native/host/media/font_scan.hppnew file mode 100644index 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 eshostdiff --git a/native/host/platform/android.cpp b/native/host/platform/android.cppindex 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