commit 46578a2b5d302de5d01b5d50b68e2a077e5da0ad
Author: jhaizhou <258432107+jhaizhou-ops@users.noreply.github.com>
Date: Mon Oct 12 16:51:08 2026 +0800
Initial public release
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..3ba13e0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1 @@
+blank_issues_enabled: false
diff --git a/.github/ISSUE_TEMPLATE/problem.md b/.github/ISSUE_TEMPLATE/problem.md
new file mode 100644
index 0000000..bc9aa79
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/problem.md
@@ -0,0 +1,38 @@
+---
+name: 报告问题 / Report a problem
+about: 构建不过、装不上、进不了游戏、游戏里的毛病 / Build fails, cannot install, cannot enter the game, in-game problems
+---
+
+
+
+**哪一步出的问题 / Which step fails**
+
+
+
+**你的环境 / Your setup**
+- 电脑与系统 / Computer and OS:
+- Xcode 版本(如果用了)/ Xcode version (if used):
+- 手机型号与系统版本 / Phone model and iOS version:
+- 签名用的账号类型:付费 / 免费 / 自签工具 / Signing: paid account / free account / sideloading tool:
+- 仓库的提交号 / Commit of this repository:
+
+**`./setup.sh check` 的输出 / Output of `./setup.sh check`**
+```
+(贴在这里 / paste here)
+```
+
+**发生了什么 / What happened**
+
+
+
+**日志 / Log**
+
+
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..5d9e1a1
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,45 @@
+
+
+## What changed
+
+
+
+## Why
+
+
+
+## Checks run
+
+
+
+No game files needed:
+
+- [ ] `python3 dm/i18n/scan_literals.py`
+- [ ] `python3 dm/ios/tools/dm_i18n.py --check`
+
+Game files and a workspace prepared by `./setup.sh` needed:
+
+- [ ] `make -C dm/host/tests run`
+- [ ] `make -C dm/gfx/tests run`
+- [ ] `make -C dm/ios/tests test`
+- [ ] `dm/verify/regress.sh` (with `--fresh` if `dm/tools/patch_nso.py` changed)
+- [ ] `cd dm/ios && ./run.sh build`
+- [ ] `dm/ios/tools/smoke_mac.sh 1`
+- [ ] `dm/ios/tools/check_hud_gen.sh`
+
+Anything else you ran, and on what (Mac host, iOS package on a Mac, which device):
+
+## Visible changes
+
+- [ ] Nothing on screen changes
+- [ ] Something on screen changes — screenshots taken after the change are attached below
+- [ ] New on-screen text is in `dm/i18n/ui_text.tsv`, and `dm/host/dm_i18n_tab.h` was regenerated
+
+## No game content
+
+- [ ] This change contains no game files, nothing generated from game files, no keys, and no built package
+- [ ] It does not carry the local rewrites `./setup.sh` makes to `dm/gfx/tools/dmsh_chain.lock`, `dm/gfx/nvn/dmsh_chain.h` and `dm/gfx/nvn/c1_full.tsv`
+
+## Comments
+
+- [ ] New and changed comments are in both Chinese and English
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..19201d4
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+# 构建产物(Xcode 的派生数据目录,由 dm/ios 下的脚本生成)
+.iosdd/
+.iosdd_mac/
+.iosdd_*/
+.DS_Store
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..456f030
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,120 @@
+# Contributing
+
+中文: [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)
+
+This page covers three things: what you must be able to run before changing anything, the three rules of this repository, and what to attach when reporting a problem. How the parts work is not repeated here; see [dm/README.md](dm/README.md) and [dm/verify/README.md](dm/verify/README.md).
+
+## Before you change anything: get the tests passing
+
+Run everything below that you can on the untouched code first, then again after your change. All commands are run from the repository root.
+
+### No game files needed
+
+These only read source files; `python3` is enough.
+
+| Command | What it checks |
+|---|---|
+| `python3 dm/i18n/scan_literals.py` | The literal gate: whether any Chinese text the player can see bypasses the Chinese-English string table; see [dm/i18n/README.md](dm/i18n/README.md) |
+| `python3 dm/ios/tools/dm_i18n.py --check` | Whether every row of the string table `dm/i18n/ui_text.tsv` follows the rules, and whether the checked-in `dm/host/dm_i18n_tab.h` was generated from the current table |
+
+### Game files and a prepared workspace needed
+
+Prerequisite: your own game files are in place, `./setup.sh` has finished (it creates the Python environment, produces the rewrite output and translates the shaders), and you have entered that Python environment: `source ~/dm-work/build/cache/dm/venv/bin/activate` (if you set `DM_ROOT`, use it in place of `~/dm-work`). Use `./setup.sh check` to see what is missing.
+
+| Command | What it checks | Extra prerequisites |
+|---|---|---|
+| `make -C dm/host/tests run` | Host unit tests. Also runs the two text checks above and two source-only scans: no writes to the original game's UI widgets (`native_write_scan.py`), and the registration of touch / controller mode behavior (`mode_scan.py`) | Some tests read the game's program files and resource directory directly |
+| `make -C dm/gfx/tests run` | Graphics-layer unit tests, run for real on this machine's Metal | Some tests read the shader cache translated by `./setup.sh` |
+| `make -C dm/ios/tests test` | Unit tests of the iOS shell: touch handling, skill binding parsing and so on. No device, and the app is not launched | The skill index is not in the repository; when missing it is generated from the game files |
+| `dm/verify/regress.sh` | Rewrite-equivalence regression: whether the rewriter's output is structurally correct, whether every rewritten site behaves like the original instruction, and whether the host gates work. Last line `REGRESS OK` or `REGRESS FAIL` | `llvm-objdump` and `llvm-objcopy`; point `LLVM_BIN` at their directory |
+| `cd dm/ios && ./run.sh build` | Whether the iOS package builds (build only, no device involved) | Xcode, and the signing configuration in `dm/ios/local.env` |
+| `dm/ios/tools/smoke_mac.sh 1` | Smoke test: actually launches the iOS package on the Mac, loads a save and enters the game, with audio playing and no line marked 【红】 (red) in the log. Last line `SMOKE-MAC OK` or `SMOKE-MAC RED` | Run `dm/ios/tools/make_fixture.sh` once first to create the smoke save |
+| `dm/ios/tools/check_hud_gen.sh` | Whether anything generated from game files has been added to git; when this machine has game files it also generates the bottom UI once for real | Run inside the git repository |
+
+If you changed the rewriter `dm/tools/patch_nso.py`, use `dm/verify/regress.sh --fresh`: it first regenerates the output with the rewriter in your working tree and then verifies that.
+
+Criteria, output locations and environment variables for each of these are in [dm/verify/README.md](dm/verify/README.md) and [dm/ios/README.md](dm/ios/README.md).
+
+### The part you cannot run
+
+In the full acceptance run `dm/verify/accept.sh`, the save comparison, the screenshot gate and the logic gates need "ground-truth data": recordings of the original game running. That data is not in the repository and never will be, and the emulator driver scripts used to record it are not shipped either. What ground truth is and how it is formatted is described in [dm/verify/README.md](dm/verify/README.md).
+
+When you submit a change, state which checks you actually ran and what they reported. If you did not run something, say so.
+
+## Three rules
+
+### 1. No game content in the repository
+
+The repository contains and distributes no game content. The game program, art, text, shaders and saves, and any image, table or code generated from them, stay out. Everyone produces these on their own machine from their own game files. What the repository does carry is interface information recorded to make the port work (shader interface descriptions, the graphics API function table, addresses inside the program and so on), listed item by item in [docs/DERIVED.md](docs/DERIVED.md); open an issue to discuss before adding anything of that kind.
+
+The following are generated at build time and are already listed in the `.gitignore` files of their directories. Do not force-add them:
+
+| Path | What it is |
+|---|---|
+| `dm/host/dm_vault_tab.h`, `dm/host/dm_hud_exp.h`, `dm/host/dm_bright_levels.inc` | Headers generated from the game's data tables (by `dm/host/Makefile` at build time) |
+| `dm/ios/Gen/` | Generated parts of the iOS package: UI images made from the game files, the embedded game program, the overlay |
+| `dm/ios/Sources/TouchArt/dm_native_*.png`, `dm/ios/Sources/dm_touch_native_art.c` | The skill atlas and skill index |
+| `dm/ios/DmIOS.xcodeproj/`, `dm/ios/Sources/Info.plist`, `dm/ios/Sources/DmIOS.entitlements`, and `Info.plist` and `RomfsDownloader.entitlements` under `dm/ios/RomfsDownloader/` | The project and configuration generated from `dm/ios/project.yml` |
+| `dm/ios/local.env` | Your own signing configuration |
+| `dm/host/dmhost`, `*.dSYM/`, `*.bin`, `*.pkl`, `__pycache__/`, the test programs built under each `tests/` | Build output and intermediate files |
+| `.iosdd/`, `.iosdd_mac/`, `.iosdd_*/` | Xcode derived-data directories |
+
+Three more files are in the repository but get rewritten by `./setup.sh` to match the tools on your machine: `dm/gfx/tools/dmsh_chain.lock`, `dm/gfx/nvn/dmsh_chain.h` and `dm/gfx/nvn/c1_full.tsv`. That is expected; do not commit those changes.
+
+Everything under the workspace `$DM_ROOT` (default `~/dm-work`) — game files, rewrite output, caches, run logs — lives outside the repository and never enters it.
+
+The same applies to issues and pull requests: no game files, no keys, no packages you built.
+
+### 2. Comments are bilingual
+
+Every comment in the code exists in both Chinese and English, saying the same thing. There are two existing forms; follow them:
+
+- File headers and block comments: the Chinese lines first, immediately followed by the English lines.
+
+ ```c
+ // 导入解析(已实现接宿主、其余接记名桩)与宿主门分派。
+ // Import resolution (implemented ones go to the host, the rest go to named stubs) and host gate dispatch.
+ ```
+
+- Trailing comments, and single lines in Python docstrings: Chinese first, then English, on the same line, separated by ` | `.
+
+ ```c
+ int dm_lang_zh(void); // 1 = 我们的字用中文 | 1 = our text uses Chinese
+ ```
+
+Every source file opens with a comment saying what it does and what that is based on; the feature files in `dm/host` also name the addresses in the game program they rely on (all offsets into the original 3.3.94012 image). New files do the same.
+
+Documentation is bilingual too, with matching content: `README.md` is English, `README.zh-CN.md` is Chinese.
+
+`dm/third_party/` holds other people's code, kept as upstream; this rule does not apply there.
+
+### 3. New on-screen text goes into the string table
+
+Any text of ours that the player can see is registered in `dm/i18n/ui_text.tsv` (key / Chinese / English / where used); code refers to the key, never to a literal. After changing the table, regenerate and commit `dm/host/dm_i18n_tab.h`:
+
+```
+python3 dm/ios/tools/dm_i18n.py --header > dm/host/dm_i18n_tab.h
+```
+
+The literal gate `python3 dm/i18n/scan_literals.py` stops Chinese literals that are not in the table. It only recognizes literals containing Chinese, so it cannot catch hard-coded English; that belongs in the table all the same. Chinese that only goes to logs and never reaches the screen does not need an entry. The table's rules, the full steps for adding a string, and how to write a whitelist row are in [dm/i18n/README.md](dm/i18n/README.md).
+
+## Submitting a change
+
+- Say what you changed and why.
+- Say which of the checks above you ran and what they reported.
+- If anything visible on screen changed, attach screenshots taken after the change.
+- Confirm that no game content is included.
+
+A template lists these items when you open a pull request.
+
+## Reporting a problem
+
+Use the issue template. What to attach:
+
+- Which step fails: preparing game files, `./setup.sh`, `./run.sh build`, the no-Xcode tool, installing, launching, or in game.
+- Your setup: computer and OS, Xcode version, phone model and iOS version, the kind of signing (paid account / free account / sideloading tool), and the commit of this repository.
+- The full output of `./setup.sh check`.
+- What happened: the exact error text, what the screen showed, and steps to reproduce.
+- The log: in game, pause menu → share diagnostic log. Look it over before posting and remove anything you do not want public (device name, user names in file paths).
+
+Do not post game files or keys, or links to them, and do not upload the package you built: it contains game content. Issues containing any of these are deleted without discussion. We cannot help with obtaining game files; that takes your own console and the game you bought.
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
new file mode 100644
index 0000000..ab77e40
--- /dev/null
+++ b/CONTRIBUTING.zh-CN.md
@@ -0,0 +1,120 @@
+# 参与开发
+
+English: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+这一页讲三件事:改动之前要能跑通什么,仓库的三条规矩,报问题时附什么。各部分怎么工作不在这里重复,见 [dm/README.zh-CN.md](dm/README.zh-CN.md) 与 [dm/verify/README.zh-CN.md](dm/verify/README.zh-CN.md)。
+
+## 改动之前:先跑通测试
+
+先在没动过的代码上把下面能跑的都跑通,改完再跑一遍。命令都在仓库根目录执行。
+
+### 不需要游戏文件
+
+只读源码,有 `python3` 就能跑。
+
+| 命令 | 验什么 |
+|---|---|
+| `python3 dm/i18n/scan_literals.py` | 字面量闸门:玩家看得到的中文有没有绕过中英表,见 [dm/i18n/README.zh-CN.md](dm/i18n/README.zh-CN.md) |
+| `python3 dm/ios/tools/dm_i18n.py --check` | 中英表 `dm/i18n/ui_text.tsv` 每一行合不合规则,入库的 `dm/host/dm_i18n_tab.h` 是不是由当前的表生成的 |
+
+### 需要游戏文件与备好的工作区
+
+前提:你自己的游戏文件已放到位,`./setup.sh` 已跑完(它建好 Python 环境、出好改写产物、翻译好着色器),并且已经进入那个 Python 环境:`source ~/dm-work/build/cache/dm/venv/bin/activate`(设了 `DM_ROOT` 就把 `~/dm-work` 换成它)。缺什么用 `./setup.sh check` 查。
+
+| 命令 | 验什么 | 额外前提 |
+|---|---|---|
+| `make -C dm/host/tests run` | 宿主单元测试。同时跑上面两条文字检查,以及两条只读源码的扫描:不许写原版界面控件(`native_write_scan.py`)、触屏 / 手柄两种模式的登记(`mode_scan.py`) | 其中几项直接读游戏的程序文件与资源目录 |
+| `make -C dm/gfx/tests run` | 图形层单元测试,在本机的 Metal 上真跑 | 其中几项读 `./setup.sh` 翻译出的着色器缓存 |
+| `make -C dm/ios/tests test` | 触摸判定、技能绑定解析等 iOS 外壳的单元测试,不需要设备,也不启动 App | 技能索引不进仓库,缺了会从游戏文件现生成 |
+| `dm/verify/regress.sh` | 改写等价回归:改写器的输出结构对不对,每一处改写与原指令行为是否一致,宿主门功能是否正常。末行 `REGRESS OK` 或 `REGRESS FAIL` | `llvm-objdump` 与 `llvm-objcopy`,目录用 `LLVM_BIN` 指定 |
+| `cd dm/ios && ./run.sh build` | iOS 包能不能编出来(只构建,不碰设备) | Xcode,`dm/ios/local.env` 里的签名配置 |
+| `dm/ios/tools/smoke_mac.sh 1` | 冒烟:把 iOS 包放在 Mac 上真起一遍,读档进局、有声音、日志里没有带「【红】」的行。末行 `SMOKE-MAC OK` 或 `SMOKE-MAC RED` | 先跑一次 `dm/ios/tools/make_fixture.sh` 生成冒烟存档 |
+| `dm/ios/tools/check_hud_gen.sh` | 由游戏文件生成的东西有没有被加进 git;本机有游戏文件时再把底部界面实际生成一遍 | 在 git 仓库里执行 |
+
+改了改写器 `dm/tools/patch_nso.py` 时,用 `dm/verify/regress.sh --fresh`:它先用你工作树里的改写器重出一份产物再验。
+
+各项的判据、输出位置和环境变量见 [dm/verify/README.zh-CN.md](dm/verify/README.zh-CN.md) 与 [dm/ios/README.zh-CN.md](dm/ios/README.zh-CN.md)。
+
+### 你跑不了的那部分
+
+整套验收 `dm/verify/accept.sh` 里的存档对拍、画面闸门、逻辑闸门要用「真值数据」——原版游戏的运行记录。这些数据不在仓库里,也不会放进来;录制它们用的模拟器驱动脚本同样不随仓库提供。真值是什么、格式怎样,见 [dm/verify/README.zh-CN.md](dm/verify/README.zh-CN.md)。
+
+提交改动时写明你实际跑了哪些、结果如何;没跑的直接说没跑。
+
+## 三条规矩
+
+### 一、不提交游戏内容
+
+仓库不含、也不分发任何游戏内容:游戏程序、美术、文字、着色器、存档,以及由它们生成的图、表、代码,都不进仓库。这些东西在每个人自己的机器上、用自己的游戏文件现做出来。仓库里带着的是为适配而记录的接口信息(着色器的接口描述、图形接口函数表、程序内的地址等),逐项列在 [docs/DERIVED.zh-CN.md](docs/DERIVED.zh-CN.md);要往里加这一类东西,先开 Issue 商量。
+
+下面这些是构建时生成的,已经写在各目录的 `.gitignore` 里,不要强行加进来:
+
+| 位置 | 是什么 |
+|---|---|
+| `dm/host/dm_vault_tab.h`、`dm/host/dm_hud_exp.h`、`dm/host/dm_bright_levels.inc` | 由游戏的数据表生成的表头(`dm/host/Makefile` 构建时生成) |
+| `dm/ios/Gen/` | iOS 包的生成物:由游戏文件做出的界面图、内嵌的游戏程序、覆盖层 |
+| `dm/ios/Sources/TouchArt/dm_native_*.png`、`dm/ios/Sources/dm_touch_native_art.c` | 技能图集与技能索引 |
+| `dm/ios/DmIOS.xcodeproj/`、`dm/ios/Sources/Info.plist`、`dm/ios/Sources/DmIOS.entitlements`、`dm/ios/RomfsDownloader/` 下的 `Info.plist` 与 `RomfsDownloader.entitlements` | 由 `dm/ios/project.yml` 生成的工程与配置 |
+| `dm/ios/local.env` | 你自己的签名配置 |
+| `dm/host/dmhost`、`*.dSYM/`、`*.bin`、`*.pkl`、`__pycache__/`、各 `tests/` 下编出的测试程序 | 编译产物与中间文件 |
+| `.iosdd/`、`.iosdd_mac/`、`.iosdd_*/` | Xcode 的派生数据目录 |
+
+另有三个文件在仓库里,但 `./setup.sh` 会按你本机的工具改写它们:`dm/gfx/tools/dmsh_chain.lock`、`dm/gfx/nvn/dmsh_chain.h`、`dm/gfx/nvn/c1_full.tsv`。这是预期的,不要提交这些改动。
+
+工作区 `$DM_ROOT`(缺省 `~/dm-work`)下的东西——游戏文件、改写产物、缓存、运行日志——都在仓库之外,本来就不会进来。
+
+报问题和提改动时同样:不贴游戏文件、密钥,不上传自己做出来的安装包。
+
+### 二、注释中英双语
+
+代码里的注释都是中文、英文各一份,内容相同。现有的写法有两种,照着写:
+
+- 文件开头和成段的注释:先写中文各行,紧接着写英文各行。
+
+ ```c
+ // 导入解析(已实现接宿主、其余接记名桩)与宿主门分派。
+ // Import resolution (implemented ones go to the host, the rest go to named stubs) and host gate dispatch.
+ ```
+
+- 行尾注释,以及 Python 文档串里的单行:同一行里中文在前、英文在后,中间用 ` | ` 隔开。
+
+ ```c
+ int dm_lang_zh(void); // 1 = 我们的字用中文 | 1 = our text uses Chinese
+ ```
+
+每个源文件开头有一段注释,说明它做什么、依据是什么;`dm/host` 里的功能文件还写明用到游戏程序里的哪些地址(都是 3.3.94012 原映像的偏移)。新文件照此写。
+
+说明文档同样中英各一份,内容对应:`README.md` 是英文,`README.zh-CN.md` 是中文。
+
+`dm/third_party/` 下是别人的代码,保持上游原样,不适用这一条。
+
+### 三、屏上新增的文字进中英表
+
+玩家看得到的、我们自己加的文字,一律登记在 `dm/i18n/ui_text.tsv`(键 / 中文 / English / 用在哪),代码里只写键,不写字面量。改了表要重出并提交 `dm/host/dm_i18n_tab.h`:
+
+```
+python3 dm/ios/tools/dm_i18n.py --header > dm/host/dm_i18n_tab.h
+```
+
+字面量闸门 `python3 dm/i18n/scan_literals.py` 会拦住没进表的中文字面量。它只认含中文的字面量,直接写死的英文它拦不住,同样要进表。只进日志、不上屏的中文不用进表。表的规则、加一条文字的完整步骤、闸门的白名单怎么写,见 [dm/i18n/README.zh-CN.md](dm/i18n/README.zh-CN.md)。
+
+## 提交改动
+
+- 说明里写清改了什么、为什么。
+- 写明跑了上面哪些测试、结果如何。
+- 屏上有可见变化的,附改动后的截图。
+- 确认没有带进任何游戏内容。
+
+提交时会有一份模板列出这几项。
+
+## 报问题
+
+用 Issue 模板。要附的东西:
+
+- 哪一步出的问题:准备游戏文件、`./setup.sh`、`./run.sh build`、不用 Xcode 的工具、装机、启动,还是游戏里。
+- 你的环境:电脑与系统、Xcode 版本、手机型号与系统版本、签名用的账号类型(付费 / 免费 / 自签工具)、仓库的提交号。
+- `./setup.sh check` 的完整输出。
+- 发生了什么:报错原文、屏上看到的字、能复现的步骤。
+- 日志:游戏里暂停菜单 →「分享诊断日志」导出的文件。贴之前看一眼,去掉不想公开的东西(设备名、文件路径里的用户名)。
+
+不要贴游戏文件、密钥,也不要贴它们的下载地址;不要上传你做出来的安装包,里面有游戏内容。带这些内容的问题会被直接删除。「怎么拿到游戏文件」这一步我们帮不了:那要用你自己的主机和你自己买的游戏。
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..e98c762
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhaizhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..99ca305
--- /dev/null
+++ b/README.md
@@ -0,0 +1,273 @@
+# D2R Mobile
+
+**An open-source iOS compatibility layer for Diablo II: Resurrected.** It brings the Nintendo Switch release you bought to iPhone and iPad in full: the original game code runs natively, every control is rebuilt for touch, the frame rate holds at 60 fps, and you are in a game one second after the main menu.
+
+This is not a tech demo that "sort of runs". It is a mobile version polished for daily play, from your first character all the way through the endgame.
+
+Platforms: iPhone / iPad (iOS 26 and later) · Game version: Switch release 3.3.94012 · English / 中文 · License: MIT · **Bring your own game files**
+
+中文: [README.zh-CN.md](README.zh-CN.md)
+
+
+
+
+
+
+
+
+
+| 100% | 60 fps | about 1 s | about 3.8 W |
+|:---:|:---:|:---:|:---:|
+| The original gameplay, because it is the original program | Steady, with no drops once the device warms up | From the main menu into a game | Whole-device power draw at 60 fps |
+
+## What it is, and what it is not
+
+**It is:**
+
+- The game's own aarch64 program, **executing directly on the device**, with no emulated CPU. iPhone and Switch use the same class of processor; only the handful of instructions that cannot run unchanged under Apple's kernel are rewritten, and every other byte of the program is left exactly as shipped. Every class, every Runeword, Terror Zones, bosses, drop rules and quest flow are identical to the original.
+- The platform services the game expects — system calls, the file system, the graphics API, audio, input — provided by a small host written for Apple platforms. The graphics API is reimplemented entirely on Apple's Metal with no emulation layer in between, and the shaders are translated offline from the game's originals.
+- A port built for phones, and taken all the way: a complete touch control scheme, edge-to-edge iPhone and true full-screen iPad display, controller support, a power saver mode, save sync, English and Chinese, and a whole set of endgame modes and quality-of-life features the original never had.
+
+**It is not:**
+
+- An emulator, cloud gaming, or streaming.
+- **A source of game content. It contains none and distributes none.** There is no game program, art, text, data table or shader in this repository; all of that is generated on your own machine from your own files (see [docs/GAME_FILES.md](docs/GAME_FILES.md)). What the repository does carry is the interface information we recorded to make the port work — shader interface descriptions, the graphics API function table, addresses inside the program and the like — listed item by item in [docs/DERIVED.md](docs/DERIVED.md).
+- Online. There is no multiplayer; the game runs fully offline and needs no online account.
+
+## Battle-tested
+
+All **44** iPhones and iPads in the closed beta — 35 devices registered for direct install (25 iPhones and 10 iPads), plus 9 TestFlight accounts with one device each — **completed Normal, Nightmare and Hell with multiple characters**, and the experience was excellent. From an iPhone 14 Pro Max with 6 GB of memory to the latest iPad Pro, not one device fell behind.
+
+| | Models |
+|---|---|
+| iPhone | 14 Pro Max, 15, 15 Pro, 15 Pro Max, 16 Plus, 16 Pro, 16 Pro Max, 17 Pro Max and more |
+| iPad | iPad Air, iPad mini, iPad Pro 11-inch and 12.9 / 13-inch (including M2 and M4) and more |
+| Lowest model tested | **iPhone 14 Pro Max (A16, 6 GB): a flawless 60 fps** |
+
+iPhone and iPad share a single install package.
+
+
+
+
+
+
+
+
+
+## Fast, smooth, and easy on the battery
+
+Measured on a real device (iPhone 17 Pro Max):
+
+| Item | Reading |
+|---|---|
+| In-game frame rate | **60 fps**, steady, with no drops once the device warms up |
+| App launch | 0.15 s |
+| To the main menu | about 1 s |
+| From the main menu into a game | **about 1 s** |
+| Quick Restart, back in a game | about 1.2 s |
+| Longest frame when changing acts | about 0.1 s |
+| Whole-device power, 60 fps | **about 3.8 W** (in camp, 50% brightness): nearly 5 hours of continuous play on a full charge |
+| Whole-device power, power saver mode at 30 fps | **about 1.85 W**, about half the 60 fps figure, for about twice the battery life |
+
+Measurement conditions: power is whole-device power measured on 2026-10-10 on an iPhone 17 Pro Max, standing in the Act I camp at 50% brightness, with 60 fps and power saver mode measured in the same scene; battery life is calculated from the measured power and the battery capacity, not by playing from full to empty. Launch and game-entry times were measured on the same model in 2026-10; frame rate and act-change readings were taken on the same model on 2026-10-12 while moving through areas and changing acts after entering a game.
+
+The install package is only a little over 100 MB. The game resources (about 5.6 GB) are placed on the phone separately, and updating the app touches neither your saves nor the resources.
+
+Why it is this fast: the program executes natively, and not a single instruction goes through emulation; graphics go straight to Metal; every shader is translated offline and compiled ahead of time, so nothing is compiled when you enter a new scene. Older chips such as the A16 do not support the game's original compressed texture format, so we built a supplementary texture pack for them, and they run at full frame rate too.
+
+## Redesigned for fingers
+
+This is not a gamepad pasted onto the screen. Every panel and every action was rebuilt for fingers under one design principle: **keep the original interface language, and use gestures instead of adding buttons to the screen**. Text sizes and tap targets are sized for fingers. You know how to play the moment you pick it up, and it stays comfortable over long sessions.
+
+
+
+
+
+
+- **Move**: a virtual stick with precise diagonals; tap an NPC or the ground to path there automatically; doors, portals and cave entrances are tappable across their whole surface.
+- **Fight**: press a skill button to cast, hold to keep casting, **drag to aim at any angle**; nearby monsters are targeted automatically. Two skill sets. Skills on your secondary weapons cast with one tap — the game swaps weapons, casts, and swaps back — and the button shows the charges remaining.
+- **Boss health bar**: pinned to the top of the screen, showing the percentage remaining.
+- **Items**: tap, double-tap, long-press and drag and drop all track your finger. Double-tap gear to equip or unequip it; drag an item anywhere onto the vendor panel to sell it; on a stack, double-tap takes 1 and long-press takes 3; long-press an empty inventory slot to sort everything.
+- **Text**: typed with the system keyboard. Character names can be in Chinese; leave the name blank for a random one.
+- **Screen**: on iPhone the 19.5:9 display is filled edge to edge, clear of the notch and rounded corners; on iPad the game fills the entire screen, and the interface centers itself when you open a panel; the 3D picture can be brightened.
+
+### Controller
+
+Connect a controller and press any button: the interface switches to the original controller layout, with button prompts at the bottom of every panel. Touch the screen and you are back in the touch interface instantly. Inventory, stash, skill tree, Chronicle and settings are fully controller-navigable, with the same button mapping as on Switch.
+
+
+
+
+
+
+## New ways to play, on top of the original
+
+Finishing the original game is only the beginning. Without touching the original rules, we added a full set of endgame content that keeps you farming.
+
+### Greater Rift
+
+Enter through the red portal in Harrogath after completing Hell. There are 100 levels, and the monsters grow stronger with each one; fill the progress bar and slay the Rift Guardian within 15 minutes to clear a level. Every 2 levels cleared grants +1 Skill Point and +5 Stat Points, and the skill level cap rises from 20 to 40. Every 10 levels has a first-clear reward, and clearing level 10 unlocks six new equipment slots for your mercenary.
+
+
+
+
+
+
+### Endgame Boss Rush, Elysium mode, and the Kill Board
+
+- **Endgame Boss Rush**: unlocks after completing Hell, with 12 stages; stage 11 is Diablo Clone, and stage 12 is the three Uber bosses.
+- **Elysium mode** (chosen at character creation): Unique ×5, Set ×3, Runes ×5; the "no drop" chance is cut to a tenth, and bosses always drop as on a first kill.
+- **Kill Board**: for every boss, the number of kills, the time of the first kill, how many Unique and Set items it has dropped, and your best and average kill times.
+
+
+
+
+
+
+### Storage: a collector's paradise
+
+- **Chronicle stash**: every identified Unique and Set item has its own fixed slot, shared by all characters, searchable, with deposit and withdraw; the Deposit button sends the Unique and Set items in your inventory and Horadric Cube there in one tap.
+- **Stash**: widened to 14 columns, with 5 personal pages and 5 shared pages.
+- **Trove**: the gem, rune and material pages merged into one, with the Horadric Cube's crafting grid in the middle, so finding things and crafting no longer means flipping between pages. Runes, gems and materials you put into the personal or shared pages are filed here automatically.
+- **Pouch**: an extended inventory. Runes and gems found in the field go into it automatically and take up no inventory space.
+
+
+
+
+
+
+### Effortless farming
+
+| | |
+|---|---|
+| Auto-recast buffs | Buff skills you have learned do not need a slot on the skill bar: when a buff runs out, it is recast the moment you stand still; buffs that come from your secondary weapons (such as Battle Orders from Call to Arms) swap weapons, recast and swap back on their own |
+| Potions and belt | Auto-drink has two tiers: a healing potion below 50% Life, a rejuvenation potion below 30%; **your mercenary is fed automatically by the same rule**. Potions on the ground are picked up automatically when the belt has room; double-tap an empty belt slot to refill the whole belt |
+| Loot filter | From Nightmare on, the original loot filter is switched on automatically to hide clutter: light filtering in Nightmare, heavy in Hell |
+| Auto-pickup | Low runes and gems go straight into the Pouch; the high ones are left for you to pick up yourself |
+| Valuable drop alerts | High runes and Unique items raise a light beam and land with a different drop sound; the phone vibrates at one of three strengths — light, medium or heavy — according to value |
+| Runeword helper | Long-press a socketed base to list the Runewords it can make and their stats; once you have the runes, socket them all in one tap |
+| Minimap guidance | Every map marks its Waypoint and exits; every quest goal is on the map; when a target is off screen, its name is written along the screen edge |
+| Chores removed | Free identification, free Town Portal with no scrolls needed, spawning right beside the Waypoint, Quick Restart, refreshable vendor stock |
+| Saves | Saved immediately when you switch apps, swipe the app away or quit; iCloud sync across devices (requires signing with a paid developer account) |
+
+Most features can be toggled one by one in game under Options → Custom.
+
+
+
+
+
+
+
+### English and Chinese
+
+The whole game switches between English and Chinese under Options → Custom; after a restart, both the interface and the voice acting are in the language you chose. In English, items, skills and monsters use the original Diablo II wording, and everything we added — Greater Rift, Chronicle, the settings page, controller prompts — is in English too.
+
+
+
+
+
+
+## How it works
+
+```mermaid
+flowchart LR
+ G["Your game files
(program + resources)"] --> P["Rewriter
changes only a few instructions"]
+ G --> S["Shader translation
original → Metal"]
+ P --> H["Host
system services"]
+ S --> X["Graphics layer
the graphics API on Metal"]
+ H --> A["iOS app
touch and interface"]
+ X --> A
+```
+
+| Part | Where | What it does |
+|---|---|---|
+| Program rewriter | `dm/tools/patch_nso.py` | Rewrites only the few instructions that cannot run unchanged under Apple's kernel (thread-pointer registers, system calls, timers) and leaves the rest of the program byte-for-byte as shipped |
+| Host | `dm/host` | Loads the rewritten program and provides the platform services it calls |
+| Graphics | `dm/gfx` | Implements the game's graphics API on Metal; shaders are translated offline from the game's originals |
+| iOS app | `dm/ios` | The app shell, touch controls and interface |
+| Verification | `dm/verify` | Checks that the rewritten code behaves exactly like the original, plus the regression gates every change goes through |
+
+**Why you can trust it:** the stability is not luck. The test and verification tooling is part of the project — unit tests for the host and graphics layers, an equivalence check for every rewritten instruction, scripted walkthrough regression for the touch interface, and on-device smoke tests. Start with `make -C dm/host/tests run`, `make -C dm/gfx/tests run` and `dm/verify/regress.sh` (run them inside the Python environment prepared in step 2 below; `regress.sh` also needs `brew install llvm`). How to contribute is in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Getting started
+
+Both routes start with **the files of the game you bought** (Switch release 3.3.94012). How to prepare them is in [docs/GAME_FILES.md](docs/GAME_FILES.md).
+
+| | With a Mac | Without a Mac |
+|---|---|---|
+| Computer | An Apple silicon Mac with Xcode installed | Windows / Linux / a Mac without Xcode |
+| Method | A full build from source | Download a "shell" with no game content, use the packaging tool to add your own game content, then install it with a sideloading tool |
+| Status | The main route; everything above comes from it | Works end to end on Windows, from making the package to playing on a device, and the game program produced on the two systems is byte-for-byte identical; the one step nobody has tried yet is signing with a sideloading tool — try it and tell us |
+| Instructions | The three steps below | [docs/NO_XCODE.md](docs/NO_XCODE.md) |
+
+The Apple account used for signing: a paid developer account gives you everything; a free Apple ID works too (no iCloud save sync, and the app has to be re-signed and reinstalled every 7 days). The full list of dependencies is in [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md).
+
+### With a Mac: three steps
+
+1. Put your game files in the workspace (default `~/dm-work`, or set `DM_ROOT`):
+
+ ```
+ ~/dm-work/data/switch/3.3.94012/Update/ExeFS/ main, sdk, subsdk0
+ ~/dm-work/data/switch/3.3.94012/Update/RomFS/ data/…
+ ```
+
+2. Prepare the workspace. This checks your tools, rewrites the game program, and translates the game's shaders to Metal. The first run takes a while; later runs skip what is already done.
+
+ ```
+ ./setup.sh
+ source ~/dm-work/build/cache/dm/venv/bin/activate # run everything after this inside the Python environment setup prepared; if you changed DM_ROOT, use it in place of ~/dm-work
+ ```
+
+3. Fill in your signing details and build the app:
+
+ ```
+ cp dm/ios/local.env.example dm/ios/local.env # set DM_TEAM_ID and DM_BUNDLE_ID; with a free Apple ID also set DM_FREE_ACCOUNT=1 and DM_IOS_UDID, and keep the phone connected while building
+ cd dm/ios && DM_DEVICE_FAMILY=1,2 ./run.sh build # 1,2 = build for both iPhone and iPad; leave it out for iPhone only
+ ```
+
+The first time you open the app on your phone, it asks for the "game resource folder" — the 18 resource archives from your game files. Where to put them is in the section "The "game resource folder" that goes on the phone" of [docs/GAME_FILES.md](docs/GAME_FILES.md).
+
+`./setup.sh check` is a health check: it reports the state of this computer, the tools, the game files and the signing configuration item by item, and for everything missing it says where to get it and which command to run next; it changes nothing. If what you have is a whole game package (`.xci` / `.nsp`), `./setup.sh ` first extracts the game files into place and then carries on (install hactool first). Run `./setup.sh` again after every update to a new commit: it rebuilds the patched binaries and the shader library for the current sources (steps that are already up to date are skipped). It also rewrites three files in the repository that change with your local tool fingerprints (`dm/gfx/tools/dmsh_chain.lock`, `dm/gfx/nvn/dmsh_chain.h`, `dm/gfx/nvn/c1_full.tsv`); that is expected, do not commit them.
+
+### Without a Mac: the shell plus the packaging tool
+
+Download our prebuilt "shell" package (`D2RMobile-shell.ipa`), which contains no game content, from this repository's [Releases page](https://github.com/jhaizhou-ops/d2r-mobile/releases), add your own game files, make the install package on Windows or Linux, then sign and install it with a sideloading tool. On this route only, because the computer making the package has no Apple shader compiler, the **first launch** on the phone spends about 7 minutes compiling shaders (once, with a progress bar); a package built with Xcode has no such step. The steps, and how far each one has been verified, are in [docs/NO_XCODE.md](docs/NO_XCODE.md).
+
+## Known limitations
+
+| Item | Status |
+|---|---|
+| Online play | Out of scope; fully offline |
+| Game packages in `.nsp` format | Not verified (only `.xci` was tested) |
+| Signing and installing with a sideloading tool (Sideloadly, AltStore and the like) | Not verified; open an issue and tell us how it went |
+| Making the package on Linux | Not verified (verified on Windows and Mac) |
+| The "one-line verdict" and "legacy Chinese name" entries in item notes | These two content tables are not shipped with the repository; you can supply your own, see `dm/ios/tools/annot/README.md` |
+
+## Contributing and feedback
+
+- If you hit a problem, open an issue (there is a template); attaching the file exported by Share Diagnostics in the pause menu helps the most.
+- For the items marked not verified, tell us whether they worked or not. Either answer is valuable.
+- To change the code: get the test entry points above passing first. Every change has to pass the regression gates.
+
+**Taking it to other platforms:** this approach is not limited to iPhone and iPad. It ports directly to Apple silicon Macs — our daily regression tests run the very same package on a Mac. Android phones use the same class of processor, so the game program executes natively there as well, and the route is fully open: the only parts to replace are the sides of the host and the graphics layer that face the platform. The author has no Android phone at hand, and would love to see someone bring it to Android.
+
+## Documentation by part
+
+| Document | Covers |
+|---|---|
+| [dm/README.md](dm/README.md) | How the whole thing works, directory layout, common commands, the host's source files |
+| [dm/gfx/README.md](dm/gfx/README.md) | The graphics layer and the shader translation chain |
+| [dm/ios/README.md](dm/ios/README.md) | The iOS shell, building and smoke testing |
+| [dm/verify/README.md](dm/verify/README.md) | What each verification tool checks and what it needs |
+| [docs/GAME_FILES.md](docs/GAME_FILES.md) | Game files: which ones you need, how to get them from your own console, where to put them |
+| [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) | Dependencies and third-party licenses |
+| [docs/NO_XCODE.md](docs/NO_XCODE.md) | Building without Xcode and without a Mac |
+| [docs/DERIVED.md](docs/DERIVED.md) | Game-related material in this repository: what is here, what is not, and why |
+
+## Legal
+
+**You must own the game.** This is an independent, non-commercial project. It is not affiliated with, endorsed by, or sponsored by Blizzard Entertainment or Nintendo. Diablo and Blizzard Entertainment are trademarks of Blizzard Entertainment, Inc.; Nintendo Switch is a trademark of Nintendo. Use it only with a copy of the game that you own.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Third-party code keeps its own license in its own directory; see [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md).
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..510d6b9
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,273 @@
+# D2R Mobile
+
+**开源的《暗黑破坏神 II:狱火重生》iOS 兼容层。** 把你自己购买的 Nintendo Switch 版游戏完整带到 iPhone 和 iPad 上:原版内核原生执行,整套操作为触屏重做,稳定 60 帧,一秒进局。
+
+这不是一个「勉强能跑」的技术演示,而是一个打磨到可以天天玩、从开荒一路玩到终局的移动版。
+
+平台:iPhone / iPad(iOS 26 起)· 游戏版本:Switch 版 3.3.94012 · 中文 / English · 许可证:MIT · **需要自备游戏文件**
+
+English: [README.md](README.md)
+
+
+
+
+
+
+
+
+
+| 100% | 60 帧 | 约 1 秒 | 约 3.8 W |
+|:---:|:---:|:---:|:---:|
+| 原版玩法,跑的就是原版程序 | 稳定,热机不掉帧 | 从主菜单进到局里 | 60 帧时的整机功耗 |
+
+## 这是什么,不是什么
+
+**是:**
+
+- 游戏自己的 aarch64 程序**直接在设备上执行**,没有模拟 CPU。iPhone 和 Switch 是同一类处理器,程序里只有极少数在苹果内核下不能原样执行的指令被改写,其余逐字节保持原样。所有职业、全部符文之语、恐怖地带、首领、掉落规则、任务流程,都和原版一模一样。
+- 游戏需要的平台服务——系统调用、文件系统、图形接口、音频、输入——由一个为苹果平台写的小型宿主提供;图形接口完全在苹果的 Metal 上重新实现,中间不经过任何模拟层,着色器由游戏原版离线翻译。
+- 一次真正为手机做的移植,而且做到了底:整套触屏操作、全面屏与 iPad 真全屏、手柄支持、省电模式、存档同步、中英双语,以及一整套原版没有的终局玩法与便利功能。
+
+**不是:**
+
+- 不是模拟器,也不是云游戏或串流。
+- **不含、也不分发任何游戏内容。** 仓库里没有游戏程序、美术、文字、数据表或着色器,这些都在你自己的机器上、用你自己的文件现做出来(见 [docs/GAME_FILES.zh-CN.md](docs/GAME_FILES.zh-CN.md))。仓库里带着的是我们为适配而记录的接口信息——着色器的接口描述、图形接口的函数表、程序内的地址等——逐项列在 [docs/DERIVED.zh-CN.md](docs/DERIVED.zh-CN.md)。
+- 不支持联机,游戏完全离线运行,不需要任何联网账号。
+
+## 经过实战检验
+
+内测的 **44 台** iPhone 与 iPad——35 台登记设备(25 台 iPhone、10 台 iPad),加上 9 个 TestFlight 账号各一台——**全部顺利完成了普通、噩梦、地狱三个难度的多角色通关**,体验极佳。从 6 GB 内存的 iPhone 14 Pro Max 到最新的 iPad Pro,没有一台掉队。
+
+| | 机型 |
+|---|---|
+| iPhone | 14 Pro Max、15、15 Pro、15 Pro Max、16 Plus、16 Pro、16 Pro Max、17 Pro Max 等 |
+| iPad | iPad Air、iPad mini、iPad Pro 11 寸与 12.9 / 13 寸(含 M2、M4)等 |
+| 最低实测机型 | **iPhone 14 Pro Max(A16,6 GB 内存):60 帧完美运行** |
+
+iPhone 与 iPad 共用一个安装包。
+
+
+
+
+
+
+
+
+
+## 极速、流畅、省电
+
+真机实测(iPhone 17 Pro Max):
+
+| 项 | 读数 |
+|---|---|
+| 局内帧率 | **60 帧**,稳定,热机不掉帧 |
+| App 启动 | 0.15 秒 |
+| 到主菜单 | 约 1 秒 |
+| 从主菜单进到局里 | **约 1 秒** |
+| 一键重开,回到局里 | 约 1.2 秒 |
+| 换幕时最长的一帧 | 约 0.1 秒 |
+| 整机功耗,60 帧 | **约 3.8 W**(营地,亮度 50%),满电可连续玩近 5 小时 |
+| 整机功耗,省电模式 30 帧 | **约 1.85 W**,约为 60 帧时的一半,续航约翻倍 |
+
+测量条件:功耗为 2026-10-10 在 iPhone 17 Pro Max 上量的整机功耗,第一幕营地站立,亮度 50%,60 帧与省电模式同场景;续航由实测功耗与电池容量换算,不是从满电玩到没电。启动与入局时间为 2026-10 同机型实测;帧率与换幕为 2026-10-12 同机型进局后走图、换幕的读数。
+
+安装包只有一百多 MB;游戏资源(约 5.6 GB)单独放进手机,升级 App 时存档和资源都不动。
+
+之所以能这么快:程序是原生执行的,没有一条指令经过模拟;图形直接走 Metal;着色器全部离线翻译、预先编好,进新场景不用现编。旧机型(如 A16)不支持游戏原本的贴图压缩格式,我们为它们另做了一份补充贴图包,同样满帧。
+
+## 为手指重新设计
+
+这不是把手柄按键贴到屏幕上。每一个面板、每一种操作都按手指重新做过,设计原则只有一条:**沿用原版的界面语言,靠手势而不是往屏幕上加按钮**;字号和点击范围按手指大小重新设计。上手就会,玩久了也顺。
+
+
+
+
+
+
+- **走**:摇杆移动,斜推方向精准;点 NPC、点地面自动寻路;门、传送门、洞口整扇都能点中。
+- **打**:技能按钮按下就放、按住连放、**拖动朝任意角度瞄准**,附近有怪自动锁定。两组技能;副手技能一键放——自动换武器、放技能、换回来,按钮上显示剩余次数。
+- **首领血条**固定在屏幕顶部,显示剩余百分比。
+- **物品**:单击、双击、长按、拖放全部跟手。双击装备直接穿上或卸下,拖到商人面板任意位置就能卖;成叠物品双击取 1 个、长按取 3 个;长按背包空格一键整理。
+- **文字**:用系统键盘输入,角色名可以用中文,留空随机取名。
+- **屏幕**:iPhone 19.5:9 全面屏铺满,避开刘海和圆角;iPad 游戏画面铺满整块屏幕,打开功能页时界面自动居中;3D 画面可加亮。
+
+### 手柄
+
+接上手柄、按任意键,界面自动换成原版手柄布局,每个面板底部带按键提示;碰一下屏幕,立刻回到触屏界面。物品栏、储藏箱、技能树、编年史、设置页全程手柄可操作,键位与 Switch 一致。
+
+
+
+
+
+
+## 原版之上的新玩法
+
+原版通关只是开始。我们在不动原版规则的前提下,加了一整套让人刷得停不下来的终局内容。
+
+### 秘境
+
+通关地狱后从哈洛加斯的红门进入。共 100 层,怪物逐层变强;15 分钟内攒满进度、打倒守护者即过关。每过 2 层 +1 技能点、+5 属性点,技能等级上限从 20 提到 40;每 10 层有首通奖励;打通 10 层解锁佣兵的六个新装备位。
+
+
+
+
+
+
+### 终局首领连战、极乐世界、刷怪积分牌
+
+- **终局首领连战**:地狱难度通关后开启,共 12 关;第 11 关是暗黑克隆,第 12 关是超级三首领。
+- **极乐世界模式**(建角时勾选):暗金 ×5、套装 ×3、符文 ×5,「不掉落」的概率缩小十倍,首领每次都按首杀掉落。
+- **刷怪积分牌**:每个首领的击杀次数、首杀时间、出了多少暗金与套装、最快和平均用时。
+
+
+
+
+
+
+### 仓库:装备党的收纳天堂
+
+- **编年史仓库**:每件已鉴定的暗金、套装各有固定一格,所有角色共用,可搜索、存取;「存放」按钮一键把背包和魔盒里的暗金、套装收进去。
+- **储藏箱**加宽到 14 列,个人仓库 5 页,共享仓库 5 页。
+- **珍宝匣**:宝石、符文、材料三页合成一页,中间就是魔盒的合成格,找东西、做合成不用来回翻页。往个人页或共享页里存的符文、宝石、材料会自动归进来。
+- **百宝囊**:扩展背包。野外的符文、宝石自动收进来,不占背包格。
+
+
+
+
+
+
+### 省心刷宝
+
+| | |
+|---|---|
+| 增益技能自动补 | 学了的增益技能不用摆在技能栏上:身上的增益没了,站定的那一刻自动补放;副手武器带的增益(如战争召唤)自动换手、补上、再换回 |
+| 药水与腰带 | 自动喝药分两档:生命低于 50% 喝红药,低于 30% 喝紫药;**佣兵同样自动喂药**。腰带有空位自动捡起地上的药水;双击腰带空格一键补满 |
+| 掉落过滤 | 进噩梦起自动启用原版的战利品过滤器,把杂物藏起来:噩梦轻筛,地狱重筛 |
+| 自动拾取 | 低号符文和宝石自动收进百宝囊,高号的留给你亲手捡 |
+| 高价值掉落提醒 | 高级符文和暗金冒光柱、换一个落地音,手机按价值震动轻、中、重三档 |
+| 符文之语助手 | 长按带孔底材,列出能做的符文之语和属性;符文齐了一键镶嵌 |
+| 小地图指引 | 每张地图标出小站和出入口;所有任务终点上图;目标在画面外时贴着屏幕边写名字 |
+| 省掉的琐事 | 鉴定免费、回城免费、进局直接落在传送小站旁、一键重开、商人货架可刷新 |
+| 存档 | 切后台、划掉、退出都立刻存盘;iCloud 多设备同步(需要付费开发者账号签名) |
+
+多数功能能在游戏里「选项 → 自定义」页逐项开关。
+
+
+
+
+
+
+
+### 中文与英文
+
+整个游戏可在「选项 → 自定义」里切换为英文,重启后界面与语音都是英文:物品、技能、怪物名沿用原版英文,我们新增的内容——秘境、编年史、设置页、手柄提示——也全部配了英文。
+
+
+
+
+
+
+## 怎么做到的
+
+```mermaid
+flowchart LR
+ G["你的游戏文件
(程序 + 资源)"] --> P["改写器
只改少数指令"]
+ G --> S["着色器翻译
原版 → Metal"]
+ P --> H["宿主
系统服务"]
+ S --> X["图形层
Metal 上的图形接口"]
+ H --> A["iOS App
触屏与界面"]
+ X --> A
+```
+
+| 部分 | 位置 | 做什么 |
+|---|---|---|
+| 程序改写器 | `dm/tools/patch_nso.py` | 只改写在苹果内核下不能原样执行的少数指令(线程指针寄存器、系统调用、计时器),程序其余部分逐字节保持原样 |
+| 宿主 | `dm/host` | 装载改写后的程序,提供它调用的平台服务 |
+| 图形 | `dm/gfx` | 在 Metal 上实现游戏用的图形接口;着色器由游戏原版离线翻译 |
+| iOS App | `dm/ios` | App 外壳、触摸操作与界面 |
+| 验证 | `dm/verify` | 核对改写后的代码与原版行为完全一致,以及每次改动都要过的回归闸门 |
+
+**为什么可信:** 稳定不是靠运气。测试与验证工具是项目的一部分——宿主与图形层的单元测试、对每一处改写指令的等价核对、触摸界面的脚本化走查回归、真机冒烟。从 `make -C dm/host/tests run`、`make -C dm/gfx/tests run` 与 `dm/verify/regress.sh` 开始(都在下面第 2 步准备的 Python 环境里跑;`regress.sh` 另需 `brew install llvm`)。怎么参与见 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。
+
+## 开始使用
+
+两条路都要先有**你自己购买的游戏的文件**(Switch 版 3.3.94012),怎么准备见 [docs/GAME_FILES.zh-CN.md](docs/GAME_FILES.zh-CN.md)。
+
+| | 有 Mac | 没有 Mac |
+|---|---|---|
+| 电脑 | Apple 芯片的 Mac,装好 Xcode | Windows / Linux / 没装 Xcode 的 Mac |
+| 做法 | 从源码完整构建 | 下载不含游戏内容的「壳」,用工具把你的游戏内容做进去,再用自签工具装机 |
+| 现状 | 主路,上面的一切都出自它 | Windows 上从做包到真机游玩整条走通,两个系统做出的游戏程序逐字节相同;只剩用自签工具签名这一步等你来反馈 |
+| 说明 | 下面三步 | [docs/NO_XCODE.zh-CN.md](docs/NO_XCODE.zh-CN.md) |
+
+签名用的 Apple 账号:付费的开发者账号功能最全;免费的 Apple ID 也可以(没有 iCloud 存档同步,每 7 天要重新签名重装)。完整的依赖清单见 [docs/DEPENDENCIES.zh-CN.md](docs/DEPENDENCIES.zh-CN.md)。
+
+### 有 Mac:三步
+
+1. 把游戏文件放进工作区(缺省 `~/dm-work`,或设 `DM_ROOT`):
+
+ ```
+ ~/dm-work/data/switch/3.3.94012/Update/ExeFS/ main、sdk、subsdk0
+ ~/dm-work/data/switch/3.3.94012/Update/RomFS/ data/…
+ ```
+
+2. 准备工作区。这一步检查工具、改写游戏程序、把游戏的着色器翻译成 Metal。第一次较久,之后已做过的会跳过。
+
+ ```
+ ./setup.sh
+ source ~/dm-work/build/cache/dm/venv/bin/activate # 之后的命令都在 setup 准备好的 Python 环境里跑;换过 DM_ROOT 的话把 ~/dm-work 换成它
+ ```
+
+3. 填好签名信息,出 App:
+
+ ```
+ cp dm/ios/local.env.example dm/ios/local.env # 填 DM_TEAM_ID 与 DM_BUNDLE_ID;免费 Apple ID 另填 DM_FREE_ACCOUNT=1 与 DM_IOS_UDID,构建时手机连着
+ cd dm/ios && DM_DEVICE_FAMILY=1,2 ./run.sh build # 1,2 = 同时面向 iPhone 与 iPad;只要 iPhone 可以不写
+ ```
+
+装到手机上第一次打开,App 会要「游戏资源文件夹」——就是游戏文件里的 18 个资源档案,怎么放见 [docs/GAME_FILES.zh-CN.md](docs/GAME_FILES.zh-CN.md) 的「手机上要放的那个游戏资源文件夹」一节。
+
+`./setup.sh check` 是体检:逐项报告这台电脑、工具、游戏文件、签名配置的状态,缺的每一项都给出去哪拿和下一步命令,不做任何改动。手上是一整个游戏包(`.xci` / `.nsp`)时,`./setup.sh <游戏包> ` 会先把游戏文件取出来放到位再接着准备(要先装 hactool)。每次更新到新的提交之后都要再跑一遍 `./setup.sh`:它会按当前源码重出改写产物与着色器库(已是最新的步骤会跳过)。它还会改写仓库里三个随工具指纹变化的文件(`dm/gfx/tools/dmsh_chain.lock`、`dm/gfx/nvn/dmsh_chain.h`、`dm/gfx/nvn/c1_full.tsv`),这是预期的,不要提交它们。
+
+### 没有 Mac:壳 + 做包工具
+
+从本仓库的[发布页](https://github.com/jhaizhou-ops/d2r-mobile/releases)下载我们预先做好的、不含游戏内容的「壳」安装包(`D2RMobile-shell.ipa`),加上你自己的游戏文件,在 Windows 或 Linux 上做出安装包,再用自签工具签名装机。只有走这条路时,因为做包的电脑上没有苹果的着色器编译器,手机**第一次启动**要花约 7 分钟把着色器编完(一次性,带进度条);用 Xcode 构建的包没有这一步。步骤与每一步的验证现状见 [docs/NO_XCODE.zh-CN.md](docs/NO_XCODE.zh-CN.md)。
+
+## 已知限制
+
+| 项 | 现状 |
+|---|---|
+| 联机 | 不在范围内,完全离线 |
+| `.nsp` 格式的游戏包 | 没验过(只测过 `.xci`) |
+| 用自签工具(Sideloadly、AltStore 等)签名装机 | 没验过,欢迎开 Issue 告诉我们结果 |
+| Linux 上做包 | 没验过(Windows 与 Mac 上验过) |
+| 物品注释里的「一句点评」与「旧译名对照」 | 两张内容表不随仓库提供,可自备,见 `dm/ios/tools/annot/README.zh-CN.md` |
+
+## 参与与反馈
+
+- 遇到问题请开 Issue(有模板);能附上暂停菜单里「分享诊断日志」导出的文件最好。
+- 没验过的那几项,走通或走不通都值得告诉我们。
+- 想改代码:先跑通上面的测试入口,每次改动都要过回归闸门。
+
+**往别的平台走:** 这套做法不限于 iPhone 和 iPad。Apple 芯片的 Mac 可以直接移植过去——我们每天的回归测试就是把同一个包放在 Mac 上跑的。安卓手机用的是同一类处理器,游戏程序同样可以原生执行,这条路完全走得通:要换的只是宿主和图形层对接的那一侧。作者手边没有安卓手机,非常期待看到有人把它带到安卓上。
+
+## 各部分的说明
+
+| 说明 | 讲什么 |
+|---|---|
+| [dm/README.zh-CN.md](dm/README.zh-CN.md) | 整套东西怎么工作、目录、常用命令、宿主各文件 |
+| [dm/gfx/README.zh-CN.md](dm/gfx/README.zh-CN.md) | 图形层与着色器翻译链 |
+| [dm/ios/README.zh-CN.md](dm/ios/README.zh-CN.md) | iOS 外壳、出包与冒烟 |
+| [dm/verify/README.zh-CN.md](dm/verify/README.zh-CN.md) | 验证工具各自验什么、需要什么前提 |
+| [docs/GAME_FILES.zh-CN.md](docs/GAME_FILES.zh-CN.md) | 游戏文件:要哪些、怎么从自己的主机取、放到哪 |
+| [docs/DEPENDENCIES.zh-CN.md](docs/DEPENDENCIES.zh-CN.md) | 依赖清单与第三方许可证 |
+| [docs/NO_XCODE.zh-CN.md](docs/NO_XCODE.zh-CN.md) | 不用 Xcode、不用 Mac 的做法 |
+| [docs/DERIVED.zh-CN.md](docs/DERIVED.zh-CN.md) | 仓库里与游戏有关的东西:有什么、没有什么、为什么 |
+
+## 声明
+
+**你必须拥有正版游戏。** 这是一个独立的非商业项目,与暴雪娱乐、任天堂没有关联,也未获其认可或赞助。Diablo 与 Blizzard Entertainment 是暴雪娱乐的商标,Nintendo Switch 是任天堂的商标。请只配合你自己拥有的游戏使用。
+
+## 许可证
+
+MIT,见 [LICENSE](LICENSE)。第三方代码各自的许可证在其目录内,见 [docs/DEPENDENCIES.zh-CN.md](docs/DEPENDENCIES.zh-CN.md)。
diff --git a/dm/.gitignore b/dm/.gitignore
new file mode 100644
index 0000000..10b3c4e
--- /dev/null
+++ b/dm/.gitignore
@@ -0,0 +1,10 @@
+host/dmhost
+host/*.dSYM/
+*.bin
+*.pkl
+__pycache__/
+# 着色器翻译工具的编译中间产物(dotnet 在源码目录旁生成)
+gfx/tools/dmsh_xlate/obj/
+gfx/tools/dmsh_xlate/bin/
+third_party/ryujinx/**/obj/
+third_party/ryujinx/**/bin/
diff --git a/dm/PRODUCT b/dm/PRODUCT
new file mode 100644
index 0000000..3d0e755
--- /dev/null
+++ b/dm/PRODUCT
@@ -0,0 +1 @@
+3.3.94012-r40
diff --git a/dm/README.md b/dm/README.md
new file mode 100644
index 0000000..0bb8bc4
--- /dev/null
+++ b/dm/README.md
@@ -0,0 +1,226 @@
+# dm/ — rewriter, host, graphics layer, iOS shell and verification
+
+中文:[README.zh-CN.md](README.zh-CN.md)
+
+This is all of the code of D2R Mobile. This page explains how the whole thing works, what each directory is, the common commands, and what each of the main files in `host/` is responsible for.
+
+The steps for preparing the environment and building the app are not repeated here:
+
+- Overview and the three build steps: [../README.md](../README.md)
+- Dependencies and versions: [../docs/DEPENDENCIES.md](../docs/DEPENDENCIES.md)
+- How to prepare the game files and where to put them: [../docs/GAME_FILES.md](../docs/GAME_FILES.md)
+- One command to prepare the workspace: `../setup.sh`
+
+Below, `$DM_ROOT` is the workspace root directory (default `~/dm-work`): the game files, rewrite build outputs, caches and run logs all live under it and are not committed to the repository.
+
+## How it works
+
+The game program is three NSO files (the Switch executable module format): `main` (the game itself), `sdk` (the Nintendo SDK) and `subsdk0`. They use the same instruction set as the iPhone, so the vast majority of the code can be executed as is; what has to be handled is their dependence on the Switch operating system (Horizon).
+
+### 1. Rewriting the main program (`tools/patch_nso.py`)
+
+Each module is rewritten once, offline, touching only the instructions that cannot be executed as is under the Apple kernel:
+
+| Original instruction | Why it cannot be executed as is | Changed to |
+|---|---|---|
+| Reads and writes of the `x18` register | The Apple kernel modifies this register | Reads and writes of a thread slot (a per-thread storage location) |
+| Reads and writes of `tpidr_el0`, reads of `tpidrro_el0` | The game uses them to find thread-local storage and Horizon's thread-local region; the Apple kernel modifies `tpidr_el0`, and Horizon's thread-local region has no counterpart on Apple platforms | Reads and writes of the corresponding thread slot |
+| `svc #n` (system call) | There is no Horizon kernel on Apple platforms | A jump to the "host gate": an entry point into the host's C code |
+| Reads of `cntpct_el0` (the system counter) | Horizon's timer has no counterpart on Apple platforms | Also goes through the host gate; the host answers as a 19.2 MHz system counter |
+
+In addition there are two tables registered per program build number, both written in `patch_nso.py`:
+
+- **Cuts** (`CUTS`): targeted modifications of individual instructions or data. Each entry carries the original bytes, the new bytes and a reason; before rewriting, the original bytes are checked entry by entry, and the rewrite aborts on any mismatch.
+- **Observation gates** (`OBS`): a gate inserted at the entry of some function that enters a host callback, executes the original instruction and then jumps back, so that the host can read the state at that point.
+
+The rewritten code is never modified again at run time: thread slot numbers are obtained indirectly through a read-only "key page", and gate addresses are fetched from thread slots. The reason is that iOS does not allow executing code written at run time, so the game code must be compiled into the App as a signed code segment.
+
+The output for each module is in the build output directory: `.patched.bin` (the rewritten image, with the key page and the patch area appended), `.fixups.tsv` (layout), `.gates.tsv` (gate table), `.sites.tsv`, `.cuts.tsv`, `.obs.tsv`.
+
+Build outputs have a codename, written as the single line of [PRODUCT](PRODUCT); `tools/product.sh build` uses the same rewriter to produce three kinds of build output in `$DM_ROOT/build/cache/dm/out/-`:
+
+| Kind | Ruleset | Where it is used |
+|---|---|---|
+| `keypage` | `DM_RULESET=native` | `verify/regress.sh` verifies it by default |
+| `rules` | `DM_RULESET=touch-run-v4`, without host-private gates (`DM_PRIVATE_GATES=0`) | `verify/rulegate.sh` uses it by default |
+| `touch` | `DM_RULESET=touch-run-v4`, with host-private gates | The kind that `ios/run.sh` compiles into the App by default |
+
+### 2. Loading and startup (`host/loader.c`, `host/main.c`)
+
+The host `dmhost` plays the role of Horizon's loader:
+
+1. `loader.c` maps each module's rewritten image into memory, creates the thread slots and fills in the key page, registers every gate according to `.gates.tsv`, performs cross-module relocation, and finally sets segment permissions. The code area is read-only plus executable from the moment it is loaded; after that the loader writes only to data areas.
+2. Imported symbols (functions a module requests from outside) are resolved in one of three ways; see the next section.
+3. `main.c` initializes the SDK runtime in the SDK's own startup order, runs each module's `init_array` (the table of global constructors), and then enters the game entry point `nnMain`.
+
+Each game thread is a host pthread. `guest_thread_init` in `host/thread.c` fills in those thread slots for the thread: the gate entry, the stand-in for `x18`, the thread-local storage block, and Horizon's thread-local region.
+
+### 3. Taking over system calls and system libraries (`host/hle*.c`)
+
+The game's dependence on the system has three layers, each connected in its own way:
+
+- **Kernel system calls.** A rewritten `svc` goes through `dm_gate` in `host/entry.S`, which saves the registers, and enters `gate_dispatch` in `host/hle.c`, which looks up by the gate's return address which instruction it originally was; system calls are handed to `svc_dispatch`. `hle_svc.c` implements the memory-related calls (it reserves one whole block of guest address space and carves the heap, stack and other regions out of it), and `hle_thread.c` implements the thread and synchronization calls. The SDK's `nn::os` (threads, locks, events and so on) therefore runs as is; only the kernel beneath it is replaced.
+- **C library functions.** `hle_table.c` connects the C library functions whose calling convention matches and that do not depend on structure layout directly to Apple's libc.
+- **System services.** On a real device the SDK connects to system services such as files, accounts, audio and input through inter-process communication; the host has no such service processes, so it takes over at the SDK interface layer by function name and supplies host implementations directly. Takeovers are registered with two macros in `host/hle.h`: `HLE` fills in imports that no module defines; `HLE_FORCE` is a forced takeover — even if the SDK has a definition, all references resolve to the host implementation. Every such entry must state a reason, and an entry that is registered but referenced by no module aborts at load time.
+
+An import with no implementation at all is connected to a named stub: when called, it prints one line `UNIMPL ` in the log and returns 0.
+
+Online features such as multiplayer, friends and the shop are out of scope: the related interfaces uniformly answer "unavailable", and the game takes its offline branch.
+
+### 4. Graphics layer (`gfx/`)
+
+The game draws with NVN (the Switch graphics interface). `main` imports only one entry that fetches function addresses, `nvnBootstrapLoader`; the host forcibly takes it over, and not a single instruction of the NVN driver in the SDK is executed. `gfx/nvn/hle_nvn.c` records the game's NVN calls as commands, and `gfx/nvn/nvn_mtl.m` replays them as Metal calls. The shaders are not hand-written: the game's original shaders are translated offline into Metal shader libraries by the translation chain under `gfx/tools/` (the last few steps of `../setup.sh`). See [gfx/README.md](gfx/README.md) for details.
+
+### 5. iOS shell (`ios/`)
+
+The App compiles the sources of `host/` and `gfx/` in directly. The front-end interface `host/front.h` is implemented on the Mac by `host/front_mac.m` and on iOS by `ios/Sources/front_ios.m`. The rewritten module images are turned into embedded assembly by `ios/tools/gen_embed.py` and compiled into the executable; the iOS branch of `loader.c` does not copy code, it only maps these blocks back at their original relative positions. Touch controls and the user interface are also in `ios/`. See [ios/README.md](ios/README.md) for details.
+
+## Directories
+
+| Location | Contents |
+|---|---|
+| `PRODUCT` | The codename of the current rewrite build output, one line |
+| `tools/` | The rewriter `patch_nso.py`, the build output script `product.sh`, `dmx.py` for reading the game's resource storage, `casc_overlay.py` for rewriting the resource storage at build time, and a batch of code-reading and analysis scripts |
+| `host/` | The host: loading, system call and system library takeover, the Mac front end, in-game features; `host/tests/` holds the unit tests |
+| `gfx/` | The graphics layer: `nvn/` (interface layer and Metal replay), `tex/` (texture formats and deswizzling), `tools/` (shader translation chain), `tests/` |
+| `ios/` | The iOS App: `Sources/`, the project description `project.yml`, the build-and-install script `run.sh`, `tools/` (asset generation, smoke tests, UI regression), `tests/` |
+| `verify/` | Verification: the rewrite-equivalence regression `regress.sh`, the full acceptance run `accept.sh`, and the scripts and format descriptions its items use |
+| `data/` | Small data shipped with the repository: the registry of borrowed paths for the resource overlay. The startup prefetch list is not in the public repository: without it there is no prefetch, and startup skips one step of decoding ahead of time |
+| `i18n/` | The Chinese-English string table `ui_text.tsv`; `scan_literals.py` checks that all Chinese text the player can see goes through this table, with exceptions registered in `literal_whitelist.tsv` |
+| `third_party/` | Third-party code, see [../docs/DEPENDENCIES.md](../docs/DEPENDENCIES.md) |
+
+## Common workflows
+
+**Rewrite the three modules** (already included in `../setup.sh`; rerun after changing `patch_nso.py` or changing the codename):
+
+```
+dm/tools/product.sh build
+```
+
+To rewrite a single module: `patch_nso.py