Repository navigation
risks_and_roadmap
runner edited this page Oct 10, 2026
·
18 revisions
Status: ✅ Working – Arknights: Endfield runs on Apple Silicon macOS under a custom‑patched CrossOver Wine (2026‑07‑14).
Goal of this page: capture the known risks, open questions, contradictions, and the ordered roadmap that de‑risks the project.
- Overview
- Risk Register
- Open Questions & Unknowns
- Contradictions & Source Conflicts
-
Roadmap (Milestones 0‑14)
5.1 Milestone 0 – Inventory
5.2 Milestone 1 – Capture the real failure signature
5.3 Milestone 2 – Free user‑space spoofs
5.4 Milestone 3 – Linux baseline & patch bisect
5.5 Milestone 4 – Toolchain & swap pipeline proof
5.6 Milestone 5 – Graphics payload (optional)
5.7 Milestone 6 – Port minimal patch subset
5.8 Milestone 7 – Graphics & timing tuning - Implementation Details & Step‑by‑Step Guides
- 4.1 Build the patched Wine
- 4.2 Deploy the patched Wine into CrossOver
- 4.3 Create the Endfield bottle
- 4.4 Launch the game (debug logging)
- 4.5 Graphics backend selection
- 4.6 ACE anti‑cheat & stage‑1 protector fixes
- 4.7 Graphics & GPTK4 integration
- 4.8 Performance on 16 GB Macs
Arknights: Endfield (Gryphline / Tencent) uses ACE (Anti‑Cheat Expert), a re‑branded TenProtect kernel driver. On macOS, the game fails to launch under CrossOver because:
- The protector (
EndfieldBase.dll) triggers a colliding‑unwind exception loop before ACE even loads. - The ACE kernel driver cannot be loaded by Wine, but the user‑mode ACE component can run if the environment is spoofed correctly.
The dw‑proton patches (commit b816be489…) solve the Linux problem, but on macOS the blocker is stage‑1 (the protector) and stage‑2 (missing ntoskrnl exports).
The roadmap below shows how to de‑risk each stage, from inventory to a fully functional launch.
| # | Risk | Severity | Description | Mitigation |
|---|---|---|---|---|
| 1 | Categorical ACE force‑quit | Critical | ACE may decide to terminate the process with no fixable abort (e.g., due to Rosetta‑specific fingerprinting). | Run Milestone 1 to capture the exact failure; if ACE force‑quits, the project is likely dead‑ended. |
| 2 | Build‑toolchain unavailability | High |
win32on64 requires CodeWeavers‑patched clang/LLVM; the gcenx/wine/cx-llvm bottle is currently unavailable (issue #51). |
Use the DIY FOSS build (scripts/build-wine.sh) or compile bundled clang/LLVM from the CrossOver source tarball. |
| 3 | Rosetta 2 timing / sync mismatch | Medium | ACE is timing‑sensitive; the QPC busy‑wait and MSync may diverge under Rosetta translation, causing intermittent failures. | Validate timing on a Linux baseline (Milestone 3) and test on macOS after stage‑1 is cleared. |
| 4 | Code‑signing / SIP / quarantine | Medium | Swapped Wine binaries must be re‑signed or have the bundle seal stripped; macOS may block execution. | Follow the Verified recipe in 05‑swapping-into-crossover.md (strip quarantine, ad‑hoc sign the outer bundle). |
| 5 | Graphics backend incompatibility | Low‑Medium | Endfield defaults to Vulkan; DX12 → vkd3d fails; DX11 → D3DMetal works but may need GPTK4 for best performance. |
Use DXMT (CX_GRAPHICS_BACKEND=dxmt) + -force-d3d11; enable GPTK4 if macOS 27+ is available. |
| 6 | Stage‑1 protector fault (0x6CD268 loop) | High | The protector’s exception‑dispatch loop is macOS‑specific; dw‑proton patches do not address it. |
Milestone 1 captures the signature; Milestone 6 applies the int3 KiUser*Dispatcher spoof (stage‑1 candidate). |
| 7 | Wine version drift | Medium | CrossOver 26/27 bundles Wine 11.0; older patches may not apply cleanly. | Verify the exact Wine base version (Milestone 0) and ensure patches target that version. |
| 7 | Future native‑arm64 CrossOver | Medium | CrossOver is moving to native arm64, dropping Rosetta 2 and win32on64. The #ifdef __x86_64__ int3 hack will disappear. |
Target an x86_64 CrossOver base for now; plan for a future arm64‑compatible int3 implementation if needed. |
| # | Question | Why it matters | Current evidence |
|---|---|---|---|
| A | What is the exact failure signature on stock CrossOver? | Determines whether the blocker is a missing function, a timing issue, or a generic exception‑dispatch loop. | Captured in Milestone 1 (see 10‑milestone-1-results.md). |
| B | Does the dw‑proton int3 spoof (KiUser*Dispatcher) apply to the macOS build? |
The int3 hack is #ifdef __x86_64__; a native arm64 CrossOver would lack it. |
Confirmed in 02‑dwproton‑ace‑patches.md and 07‑rosetta‑and‑windows‑spoofing.md. |
| B | Which specific ntoskrnl.exe function aborts first on macOS? |
The only documented abort is msimg32.dll.AlphaBlend; if a ntoskrnl function is the real blocker, dw‑proton’s em‑backports are required. |
Not yet captured – Milestone 1 must record the aborting function. |
| C | Is the ACE environment detection based on Rosetta‑specific CPUID (VirtualApple) or other signals? |
If ACE checks for VirtualApple or missing AVX‑512, the int3 hack may be insufficient. |
No primary RE confirms this; only Linux/Proton evidence exists. |
| D | Can the stage‑1 protector loop be eliminated without a rebuild? | If the fault is purely a Rosetta translation bug, a Wine‑side patch (e.g., handle_cet_nop fix) may suffice. |
The fault is reproduced on macOS; see Milestone 1 and 12‑stage1‑protector‑fault.md. |
| E | Is the PROTON_ENABLE_INT3_HACK=1 gate sufficient for Endfield on macOS? |
The gate matches Endfield.exe or EM‑Win64‑Shipping.exe; the game may use a different process name. |
The int3 gate is verified in 02‑dwproton‑ace‑patches.md; a +relay trace (Milestone 1b) will confirm whether the dispatcher is actually called. |
| F | Will the stage‑2 dw‑proton patches (ntoskrnl em‑backports) compile against CrossOver’s winecx + win32on64 fork? |
Rebase conflicts could make the patches non‑applicable. | The patches live in dawn-winery/wine-dwproton; rebase against CrossOver’s Wine base (Milestone 4) will reveal compatibility. |
| G | Will the custom Wine build (x86_64 under Rosetta) remain buildable after CrossOver retires 32‑bit bottles? | Future CrossOver releases may drop win32on64 support, breaking the build path. |
CrossOver 27 plans to retire 32‑bit bottles (see 08‑risks‑unknowns‑open‑questions.md). |
The roadmap is ordered by information gain → low‑cost experiments → higher‑cost integration. Each milestone produces evidence that decides whether the next step is worthwhile.
Goal: Establish exactly what you are working with.
# CrossOver version & Wine base version
/Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine --version
# Is the bundled Wine x86_64 or arm64?
file /Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wineserver
# macOS + hardware
sw_vers
uname -m
sysctl -n machdep.cpu.brand_string
```python
*Record:* CrossOver version, Wine base version, wine binary arch (x86_64 vs arm64), macOS version.
*Why:* Determines whether the int3 hack (`#ifdef __x86_64__`) is applicable and which toolchain you need.
---
### Milestone 1 – Capture the real failure signature (⭐)
*Goal:* Record the exact failure on **stock** CrossOver (no dw‑proton patches).
**Procedure** (use `scripts/01-capture-failure.sh`):
```bash
# Full log with all relevant channels
CX_LOG="$HOME/endfield-debug/$(date +%Y%m%d-%H%M%S)/cxlog.txt"
<CrossOver wine> --bottle "Arknights Endfield" \
--debugmsg "+loaddll,+module,+ntoskrnl,+seh,+relay" \
--wait-children \
"C:/Program Files/GRYPHLINK/Launcher.exe" &> "$CX_LOG"
```bash
*Key observations to note:*
- Whether the game dies **before** ACE loads (protector loop) or **after** ACE is initialized.
- The exact exception code (`c0000005` execute‑fault) and address (`0x6CD268`).
- Any `KiUser*Dispatcher` `GetProcAddress` calls (look for `+relay`).
*Decision points:*
- **If** you see `unimplemented function ntoskrnl.exe.<X>, aborting` → the blocker is a missing kernel export → proceed to **Milestone 6** (port dw‑proton patches).
- **If** you see a **colliding‑unwind** loop (`detected collided unwind` → `stack overflow`) → the blocker is the protector (stage‑1). This is the **primary focus** of the roadmap.
*Reference:* [10‑milestone-1-results.md](#milestone-1).
---
### Milestone 2 – Free user‑space spoofs (no rebuild)
Isolate “environment detection” from “kernel‑API surface” with cheap OS‑level tweaks.
```bash
# 1️⃣ Set Windows version (bottle config)
<CrossOver winecfg> # GUI → Windows Version → Windows 10 (or 11)
# 2️⃣ Hide Wine exports (registry)
<CrossOver wine> reg add "HKCU\\Software\\Wine" /v HideWineExports /d Y /f
# or per‑app:
<CrossOver wine> reg add "HKCU\\Software\\Wine\\AppDefaults\\Endfield.exe" /v HideWineExports /d Y /f
# 3️⃣ Retest and compare to Milestone 1 baseline
```json
*Decision:*
- **ACE gets further** → environment detection is the blocker → continue with **Milestone 2** (free spoofs) → **Milestone 3** (Linux baseline).
- **If ACE still aborts identically** → the kernel‑API surface (missing `ntoskrnl` exports or timing) is the blocker → proceed to **Milestone 3** and later **Milestone 6** (patch subset).
*Reference:* [07‑rosetta‑and‑windows‑spoofing.md](#07-rosetta-and-windows-spoofing).
---
### Milestone 3 – Linux baseline & patch bisect
1. **Install Endfield on a Linux box** using a pre‑built **dw‑proton** (Heroic, Lutris, or ProtonPlus). Verify it launches – this is the known‑good baseline.
2. **Bisect the 4 patches** in commit `b816be489` (int3 spoof, int3 gate, `NtDelayExecution` QPC, wintrust bypass).
- Remove the int3 hack → does it still launch?
- Remove em‑backports subsets → which `ntoskrnl` functions are actually reached?
- Remove the QPC patch → does timing break?
*Output:* the **minimal patch set** that must be ported to macOS (the exact files to apply in Milestone 6).
*Reference:* [02‑dwproton‑ace‑patches.md](#02-dwproton-ace-patches).
---
### Milestone 4 – Toolchain & swap pipeline proof (first build, no patch risk)
Validate that you can **build a vanilla 64‑bit CrossOver Wine**, **swap it into a copy of CrossOver**, **re‑sign**, and **run a trivial app** (e.g., `winecfg`).
**Steps**
1. **Obtain the CrossOver source** that:
<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk>.<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk>... \",: (, \,,'s,,,, ( ,,,,,,,,,,,,,,」,,1.,, field End,,,,, anti,- -, (fieldfield, Arfield's (,terfield,1s, (s, - (ing'sa, End,fieldfield :field, End End,o, End,,,,i ,, End5,field- 1<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk> errors, ( (\ ( ( ( ( (,, (,,, (" (<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk> Cross,ro (,, the field, the,field,, \ (n the the \\n,6 1.\n\n1 (n,n)111111 of \2 \,\d,1,,<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk> Cross theant's (,<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk> Cross the,,1\n1,00,,1,1, , 3:, the, the, the, the, a\n \n ( ) 1, (" \ \,).,1\n =\n,1=1,1. ation, the\n , 111600 ", \n\n 113.1g1.100000 120/)31010 1<unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk><unk> Crosses 1, and,, the the, the, (,660010, the\n the, the n oot 11111) fieldfield,