shenleiandClaude Opus 5
19a9b18554
用户决定：Linux 和 Windows 不做，不验收、不作为任何步骤的阻塞项。 - PORT-PLAN 第 1 节写明范围；2A step 3 的平台列表、2P step 1/2 措辞跟着改； 2P step 4 由「五个平台分别验证」改为「两个目标平台」，Linux/Windows 两行 划掉但保留原因备查（上游 2.7 只支持 MSVC + PC/pyconfig.h，mingw 下 posixmodule.c / dynload_win.c 与 MinGW 头文件冲突）。 - PLATFORMS.md 新增 Scope 段；THIRD-PARTY.md 的 CPython Windows 段由 "not built yet" 改为 out of scope；PYTHON-EMBED-EVAL.md 下一步两条。 - 仓库里的 mingw-w64 交叉编译只留作可移植性门禁（它抓到过 UserInterface/StdAfx.h 的真问题），不代表支持 Windows。 - iOS arm64 暂按次要目标记录：保持交叉编译干净，但不作为验收目标。 仅文档改动。port_map.py check 0 error；参考 EterPack.cpp 的 8 个 pack key 值逐个 git grep --cached -w，均未入库。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
208 lines
14 KiB
Markdown
208 lines
14 KiB
Markdown
# Platform builds (macOS / iOS / Android)
|
||
|
||
Phase 1 shipped the GDExtension for macOS only. As of 2026-08-30 the build system
|
||
is opened up for the two Phase 2 devices (BACKLOG F1/F2): **iPhone 16** (iOS,
|
||
Metal) and **OnePlus 13** (Android arm64, Vulkan). The native deps that used to
|
||
come from Homebrew are now vendored and cross-compile from the same tree — see
|
||
`docs/THIRD-PARTY.md`.
|
||
|
||
**Scope (decided 2026-09-23, PORT-PLAN §1):** the shipping targets are **macOS
|
||
arm64** and **Android arm64**. iOS arm64 stays cross-compile-clean but is not an
|
||
acceptance target. **Linux and Windows are not done** — the mingw-w64 cross
|
||
build is kept only as a portability gate (it catches real include/layering bugs),
|
||
not as Windows support, and MSVC is not built at all.
|
||
|
||
## What each script does
|
||
|
||
| Script | Target | Output |
|
||
|---------------------|---------------------------|---------------------------------------------------------|
|
||
| `./build.sh` | macOS (host) | `project/bin/libmtgodot.macos.template_{debug,release}.dylib` |
|
||
| `./build-ios.sh` | iOS arm64 device (`OS64`) | `project/bin/libmtgodot.ios.template_{debug,release}.a` + staged deps in `project/bin/ios/` |
|
||
| `./build-android.sh`| Android `arm64-v8a` | `project/bin/libmtgodot.android.template_{debug,release}.arm64.so` |
|
||
| `./export-android.sh [Debug\|Release] [--install]` | Android APK (wraps build-android + Godot export) | `build/export/mtgodot-poc[-release].apk` |
|
||
| `./gen-debug-keystore.sh` | Android debug keystore (once) | `~/Library/Application Support/Godot/keystores/debug.keystore` |
|
||
| `./pack-assets.sh` | Metin2 assets → mountable zip | `build/export/assets.zip` (`zip -0`, ~2.2 GB) |
|
||
|
||
All three run `git submodule update --init --recursive` if needed. The host tools
|
||
(`packtool`, `net_probe`) and CTest suite build only on a host build
|
||
(`CMAKE_SYSTEM_NAME == CMAKE_HOST_SYSTEM_NAME`), never when cross-compiling.
|
||
|
||
`project/bin/mtgodot.gdextension` has the `[libraries]` entries for all three
|
||
platforms and an `[dependencies]` block for iOS (see below).
|
||
|
||
## Status
|
||
|
||
### macOS — ✅ done
|
||
Unchanged. `./build.sh` → dylib, `ctest` 9/9.
|
||
|
||
### iOS — 🟡 compiles; export/sign/device pending (F1)
|
||
**Verified here (Xcode 26.4.1 + iPhoneOS 26.4 SDK):**
|
||
- `./build-ios.sh Debug` cross-compiles the whole surface to **arm64, minos 15.0**:
|
||
libsodium, libzstd, miniLZO, libgr2, xr_formats, mtnet, godot-cpp, and the
|
||
extension itself → `libmtgodot.ios.template_debug.a` (valid `ar` archive).
|
||
- iOS forces the extension to **STATIC** (`MT_LIB_KIND` in `extension/CMakeLists.txt`)
|
||
because the platform can't `dlopen`. Godot links the archive + its deps into the
|
||
app at export time, which is why `.gdextension` carries an `[dependencies]`
|
||
`ios.debug` / `ios.release` map listing every archive `build-ios.sh` stages
|
||
into `project/bin/ios/`.
|
||
|
||
**Not done (needs the device + Godot iOS export templates, ~2–3 days):**
|
||
- Install matching Godot 4.7 iOS export templates.
|
||
- Godot editor → Export → iOS preset; add `project/bin/ios/*.a` as extra link
|
||
libraries (or fold into an `.xcframework`).
|
||
- Free personal provisioning profile + signing for on-device install.
|
||
- First run on the iPhone 16; capture a frame for F3.
|
||
- Release build (`./build-ios.sh Release`) and size/strip pass.
|
||
|
||
### Android — ✅ APK builds; on-device run pending USB debugging (F2/F3)
|
||
**Done (2026-08-31):**
|
||
- `extension/CMakeLists.txt` handles `CMAKE_SYSTEM_NAME == Android` (SHARED `.so`,
|
||
`arm64` output-name suffix). `./build-android.sh` drives it through the NDK's own
|
||
`build/cmake/android.toolchain.cmake` (`ANDROID_ABI=arm64-v8a`, `android-24`).
|
||
- Toolchain on this machine: `sdkmanager "ndk;27.2.12479018" "platforms;android-35"
|
||
"build-tools;35.0.0"`; `brew install openjdk@21`; Godot 4.7.1 export templates
|
||
installed; `./gen-debug-keystore.sh`.
|
||
- `editor_settings-4.7.tres`: `export/android/android_sdk_path` = `~/Library/Android/sdk`,
|
||
`java_sdk_path` = `/opt/homebrew/opt/openjdk@21/.../Home`, `debug_keystore` = the
|
||
generated one (pass `android`).
|
||
- `project/export_presets.cfg` `[preset.1]` "Android": `arm64-v8a` only,
|
||
`gradle_build/use_gradle_build=false` (prebuilt template APK — no Gradle/JDK17 build),
|
||
`permissions/internet=true`, pkg `org.internal.mtgodotpoc`, minSdk 24.
|
||
- `./export-android.sh Debug` → `build/export/mtgodot-poc.apk` (~73 MB), signed with the
|
||
debug keystore via `build-tools/28.0.3/apksigner`. Contains
|
||
`lib/arm64-v8a/{libgodot_android.so, libmtgodot.android.template_debug.arm64.so, libc++_shared.so}`.
|
||
- Renderer stays `forward_plus` (OnePlus 13 = flagship Vulkan). No GLES3 / Compatibility
|
||
fallback — all target devices are modern.
|
||
|
||
**Asset IO portability (A1, 2026-08-31):** the extension used to read every asset with raw
|
||
`std::fopen` / `std::ifstream`, which cannot read a Godot PCK — so a bundled-assets APK
|
||
would launch to nothing. Fixed by routing all *running-extension* reads through
|
||
`godot::FileAccess` (works for `res://` PCK, `user://`, and absolute OS paths):
|
||
- `extension/src/asset_io.{h,cpp}` — `read_file()` / `dds_from_file()` / `gr2_from_file()`.
|
||
All `gr2::File::load_path` and `load_dds_path` call sites (model / anim / weapon / hair /
|
||
static objects / trees / terrain splat / water / shadowmap) now go through it.
|
||
- `formats/` funnels every read through `fmt::read_file`; added `fmt::set_file_reader()` and
|
||
`register_types.cpp` installs a `FileAccess`-backed reader → `height.raw` / `tile.raw` /
|
||
`water.wtr` / `.msenv` / `areadata.txt` / `map_setting` / `property` / `.spt` /
|
||
`texture_set` / `.msm` / `.msa` (textscript) all portable.
|
||
- `mtproto`: added `load_proto_bytes()`; `Metin2Proto` reads via `asset_io`.
|
||
- The standalone-lib `*_path()` functions are untouched, so the four non-Godot CTests
|
||
(`proto.item_mob`, `pack.roundtrip`, `formats.map_formats`, `libgr2.loader_errors`) stay green.
|
||
- **Phase 2b done (2026-08-31):** `fmt::AssetResolver` can no longer `std::filesystem`-scan a
|
||
PCK, so it's now a **baked index**: `AssetResolver::save_index()` / `load_index()` (line format
|
||
`MTIDX1` + `Y|R\t<key>\t<rel>`, paths relative to assets_root), and
|
||
`build_or_load(root)` → loads `<root>/asset_index.txt` via `fmt::read_file` if present, else
|
||
scans (desktop dev). `resolve()` now returns `assets_root + "/" + rel` so it's portable
|
||
(`res://assets/...` on device). Generate the index with
|
||
`godot --headless --path project --script bake_asset_index.gd` (→ `assets/asset_index.txt`,
|
||
~8 MB, 54k files) — `export-android.sh` does this automatically. `metin2_world.cpp` calls
|
||
`build_or_load`; `Metin2World.bake_asset_index(out)` is the bound builder method.
|
||
- **`eterpack` / `asset_source`** — unused while the dev asset tree is fully loose (no `.epk`).
|
||
|
||
### Bundling the assets (mobile) — the mount-a-zip approach
|
||
|
||
The APK/IPA is **code-only** (73 MB): `assets/` (2.1 GB) + `bgm/` (80 MB) are gitignored and
|
||
sit beside `project/`, not under `res://`. Getting them into `res://` via the exporter fails:
|
||
`.gdignore` blocks `include_filter` too, and without `.gdignore` Godot imports the ~10 k
|
||
`.dds`/`.tga`/`.jpg`/`.wav` → converts them to `.ctex`/etc → `FileAccess("res://.../x.dds")`
|
||
no longer yields raw DXT bytes → the C++ decoder breaks. (It also litters the asset tree with
|
||
`.import`/`.uid` sidecars and bloats `.godot/` to ~190 MB.)
|
||
|
||
Instead: **ship a plain `zip -0` and mount it at runtime.** All C++ asset IO now goes through
|
||
`godot::FileAccess` (see A1 above), so once the zip is mounted at `res://` everything reads
|
||
from it transparently.
|
||
- `./pack-assets.sh` → `build/export/assets.zip` (bakes `asset_index.txt` first; `zip -0`
|
||
store, no compression — DXT/gr2 don't compress and we want fast random access; paths stay
|
||
`assets/…` `bgm/…` so they mount as `res://assets/…` `res://bgm/…`).
|
||
- `project/asset_pack.gd` (`class_name AssetPack`) — `ensure()` finds the zip
|
||
(`MT_ASSETS_ZIP` env → `user://assets.zip` → `OS.get_user_data_dir()/assets.zip` → exe-dir →
|
||
`res://../assets.zip`) and `ProjectSettings.load_resource_pack()`s it. `client_main.gd`
|
||
calls it in `_ready()` before `AppFlow.start()`.
|
||
- `project/asset_root.gd` — adds `res://assets` as the first candidate **iff**
|
||
`res://assets/asset_index.txt` exists (the "pack mounted" sentinel; the empty
|
||
`project/assets/.gdignore` stub doesn't count).
|
||
- Deploy: `./export-android.sh Debug --install` pushes both the APK and (if present)
|
||
`assets.zip` → `/sdcard/Android/data/org.internal.mtgodotpoc/files/assets.zip` over USB.
|
||
iOS later: `ios-deploy --bundle_id … --upload assets.zip --to Documents/`. Same mount code.
|
||
- **Future (download instead of push):** only `AssetPack._find_local_zip()`'s failure branch
|
||
changes — HTTPRequest `ASSET_PACK_URL` → `user://assets.zip` (resume + sha256 + progress UI)
|
||
→ same `load_resource_pack`. Structurally additive.
|
||
- One more `std::filesystem` scan turned up: `fmt::PropertyRegistry::scan()` walks
|
||
`<root>/Property/` for `.pr*` CRC files (drives building/tree placement). Added
|
||
`PropertyRegistry::scan_list(root, rel_paths)` + `AssetResolver::all_rel()`; `metin2_world.cpp`
|
||
feeds it the resolver's file list (both index-loaded and dir-scanned modes). `scan()` kept
|
||
for the `formats.map_formats` CTest.
|
||
- **Verified end to end**: force-mount the real `assets.zip` (2.1 GB, 58183 entries) with the
|
||
loose tree hidden → `Metin2World.load_map("OutdoorA1/metin2_map_a1")` →
|
||
20/20 chunks, 20 splatted, **601 objects (0 missing), 368 trees, 1330 property CRCs**, water,
|
||
env — byte-for-byte the same result as the loose tree. Desktop unaffected. ctest 10/10,
|
||
GDScript 34/34. Android `.so` + iOS `.a` rebuilt.
|
||
|
||
**Pending:** the OnePlus 13 is on USB and macOS sees it (`ioreg` shows vendor "OnePlus"),
|
||
but `adb devices` is empty → enable **Developer options → USB debugging** on the phone and
|
||
accept the "Allow USB debugging?" RSA prompt (USB mode: File transfer / MTP). Then:
|
||
- `./export-android.sh Debug --install` (or `adb install -r build/export/mtgodot-poc.apk`
|
||
then `adb shell am start -n org.internal.mtgodotpoc/com.godot.game.GodotApp`).
|
||
- `adb logcat -s godot GodotError Godot` — first run WILL need shader / GPU-skin fixes
|
||
under Godot's mobile Vulkan path (never exercised); capture a frame for F3.
|
||
- adb note: a stale `sdk/platform-tools/adb` daemon can hold `:5037` ("Address already in
|
||
use"); `pkill -9 -f adb` then use one adb consistently (`/opt/homebrew/bin/adb`).
|
||
|
||
## Notes / gotchas
|
||
|
||
- The `ranlib: ... has no symbols` spam during a libsodium build is harmless: the
|
||
x86 SIMD translation units compile to empty objects on arm64 (their bodies are
|
||
guarded by CPU-feature macros). libsodium-cmake compiles the full file list on
|
||
every arch by design.
|
||
- The staged `project/bin/ios/libgodot-cpp.*.a` is ~430 MB in Debug (all classes,
|
||
unstripped). Fine for a dev link; Release + dead-strip shrinks it hard.
|
||
`project/bin/ios/` and `project/bin/android/` are gitignored.
|
||
- Shaders (`SRC_TERRAIN/WATER/LEAF/SKIN/MIX` + the §2.7 spec branch) and the
|
||
GPU-skin bone-texture path have **not** been exercised under Godot's Mobile
|
||
renderer yet — that's a separate verification pass once a device boots.
|
||
- `net_stream.cpp` is pure POSIX sockets → fine on iOS/Android/Linux/macOS; only
|
||
a Windows target would need a Winsock shim.
|
||
|
||
## GPU texture compression (F4)
|
||
|
||
`extension/src/texture_util.{h,cpp}` — `make_color_texture(w,h,rgba,len,mipmaps)`
|
||
is the single funnel for "decoded RGBA8 → `ImageTexture`". On a mobile OS (or
|
||
`MTGODOT_TEXCOMP=1`) it runs the decoded colour image through runtime **ASTC 8x8**
|
||
(~2 bpp vs 32 for RGBA8), falling back to RGBA8 if the encoder is unavailable.
|
||
Desktop default is **off** and byte-identical to the old per-site code.
|
||
|
||
Wired: character skins (`metin2_model::_load_dds`), building albedo
|
||
(`static_object`), tree bark / leaf-composite (`tree_placeholder`). **Not** wired
|
||
(exact texel values matter): splat control maps, `shadowmap`, water, HUD
|
||
`load_dds` / minimap.
|
||
|
||
`texcomp_set_enabled(bool)` overrides at runtime. Verified: macOS + iOS compile,
|
||
`ctest` 9/9, desktop character render unchanged, `MTGODOT_TEXCOMP=1` render OK.
|
||
Remaining: on-device quality check + VRAM/bandwidth numbers (needs F1/F2).
|
||
|
||
## App lifecycle (F5)
|
||
|
||
`project/app_lifecycle.gd` — an `AppLifecycle` node. Add it early (or as an
|
||
autoload); `bind(m2client, audio)` wires the common consumers. It turns the
|
||
SceneTree-forwarded MainLoop notifications into signals
|
||
(`paused` / `resumed` / `focus_changed(bool)` / `memory_warning` /
|
||
`back_requested` / `close_requested`) and, by default, on background: pauses the
|
||
tree, stops BGM, drops `Engine.max_fps` to 8; restores on foreground.
|
||
`pause_tree_on_background` / `background_max_fps` are tunable (login screen sets
|
||
`pause_tree_on_background = false`).
|
||
|
||
`M2Client` (C++) handles `NOTIFICATION_APPLICATION_PAUSED/RESUMED` itself →
|
||
`suspend()` / `resume()`. While suspended `_process()` doesn't pump the socket.
|
||
A mobile OS drops the TCP connection within ~30 s of backgrounding, so the first
|
||
pump after `resume()` surfaces `disconnected`; `reconnect()` redoes the full
|
||
auth→game login from stored credentials. `login.gd` auto-calls it on `resumed`
|
||
when the stage was in-game. New signals: `suspended`, `resumed`.
|
||
|
||
Rendering-context loss (Android Vulkan surface) is handled by Godot; every GPU
|
||
resource we hold (bone textures, MultiMesh, ShaderMaterials, ImageTextures) is
|
||
RenderingServer-managed and survives — nothing for the extension to do.
|
||
|
||
Verified: headless smoke (`suspend`/`resume`/`reconnect` bound, idempotent,
|
||
signals fire once), `ctest` 9/9, iOS compile. Remaining: on-device background/
|
||
resume/reconnect cycle and a real iOS memory-warning.
|