Repository navigation
known_issues
runner edited this page Oct 5, 2026
·
15 revisions
This page documents all known issues, their root causes, and verified solutions for running Arknights: Endfield through the patched CrossOver Wine build (Endfield_FineWine). Issues are categorized by deployment phase and symptom type for easy reference.
⚠️ Scope: This page covers issues encountered after the game reaches the login screen. If the game fails to launch past the protector loop, see the Stage 1 Protector Fault and Milestone 1 Results documentation.
💡 Usage: Browse by category or search (⌘/Ctrl+F) for your specific symptom. Each entry includes a brief technical note, the verified fix, and links to deeper documentation.
Symptom: The swap script reports a version mismatch, or the patched app fails to launch.
Root Cause: The patched Wine modules are built against CrossOver 26.3's Wine 11.0 ABI. Using a different CrossOver version (e.g., 25.x or 27-Preview) causes ABI incompatibilities.
Solution:
- Ensure you are using CrossOver 26.3 (licensed from CodeWeavers).
- If you have a newer CrossOver, install 26.3 alongside it (e.g.,
/Applications/CrossOver_26.3.app) and use that as the base for swapping. - Verify:
file /Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wineservershould report Mach-O x86_64 (Rosetta 2 translated).
Links: 05-swapping-into-crossover.md · 04-building-crossover-wine.md
Symptom: macOS repeatedly flags the patched app as damaged, requiring moving to Trash, or binaries are killed with exit code 137.
Root Cause: The bundle's code signature seal is broken after module swaps. macOS validates the nested CodeWeavers signatures, and any corruption triggers a full re-seal requirement.
Solution:
- Click Cancel (not Move to Trash) when the dialog appears.
- Re-run the swap script:
./scripts/swap-into-crossover.sh— this re-seals the bundle properly. - If you manually edited files inside the patched app, re-seal manually:
codesign --force --sign - --preserve-metadata=entitlements \ /Applications/CrossOver_Endfield_Patch.app
4. Verify before first launch:
```bash
codesign --verify --deep --strict \
/Applications/CrossOver_Endfield_Patch.app && echo "patched app verifies"
```bash
**⚠️ Critical:** Never delete the quarantine xattr or the CodeSignature folder manually. The script handles this via `xattr -drs com.apple.quarantine` and selective signature removal.
**Links:** [05-swapping-into-crossover.md → Verified recipe](05-swapping-into-crossover.md#verified-recipe-2026-09-crossover-2620--macos-270--m4)
---
### 3. ACE "driver error 13" comes back
**Symptom:** Game launches but immediately reports "driver error 13" or crashes with ACE-related errors.
**Root Cause:** The patched `ntdll.so`/`ntoskrnl.exe` aren't loading correctly, or the swap wasn't applied to the active CrossOver copy.
**Solution:**
- Verify you launched via **`CrossOver_Endfield_Patch.app`**, not the stock `CrossOver.app`.
- Check the swap paths: the three modules must be in `Contents/SharedSupport/CrossOver/lib/wine/`:
- `x86_64-unix/ntdll.so`
- `x86_64-windows/kernel32.dll`
- `x86_64-windows/ntoskrnl.exe`
- If using the manual swap method, ensure `install_name_tool -add_rpath "@loader_path/../../../lib64"` was applied to `ntdll.so`.
**Links:** [05-swapping-into-crossover.md](05-swapping-into-crossover.md)
---
### 4. Start programs from the CrossOver window, not per-program stubs
**Symptom:** Launching `Endfield.exe` from `~/Applications/CrossOver/` (Spotlight/Launchpad) causes "code has no resources but signature indicates they must be present" errors.
**Root Cause:** CrossOver creates per-program app stubs in `~/Applications/CrossOver/` whose signatures don't verify on macOS.
**Solution:**
- Always launch the game **from the CrossOver_Endfield_Patch.app window** (the bottle list).
- Alternatively, use the Gryphline launcher inside the bottle, or run:
```bash
CXR="/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver"
"$CXR/bin/wine" --bottle "Arknights Endfield" --wait-children <exe>
```bash
**Links:** [troubleshooting.md → General](troubleshooting.md#general)
---
## 🖥️ In-Game Graphics
### 5. White / blank screen (very common after a game update)
**Symptom:** Game shows a white or blank screen, often after an Endfield update.
**Root Cause:** The game shipped an update that reset its renderer to **Vulkan** or **DirectX 12**, neither of which works well under CrossOver 26.3:
- **DX12** → `vkd3d` can't compile the game's DXIL/SM6 shaders → `Cannot load DXIL conversion library` → white screen.
- **Vulkan** → Needs a newer MoltenVK than CrossOver ships (1.2.10 has a swapchain recreation bug).
**Fix:** Set the game to **DirectX 11** mode:
- In the Gryphline launcher: use the **dropdown next to Start → "Launch with DirectX 11"**.
- Or launch with `-force-d3d11`: `./scripts/launch-endfield.sh` or `GFXARGS=-force-d3d11 ./scripts/launch-endfield.sh`.
- **Do NOT** overwrite CrossOver's `d3d11/d3d12/dxgi.dll` with `apple_gptk` copies — that breaks `unityplayer.dll` init (Windows error **1114**).
**Links:** [graphics-performance.md](graphics-performance.md) · [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics)
---
### 6. Vulkan mode: screen goes black after changing FPS or V-Sync
**Symptom:** Game keeps running but the window turns black; can't close normally.
**Root Cause:** CrossOver's bundled MoltenVK (1.2.10) doesn't survive the game recreating its swapchain.
**Fix:**
1. Force-close the game:
```bash
CXR="/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver"
WINEPREFIX="$HOME/Library/Application Support/CrossOver/Bottles/Arknights Endfield" CX_ROOT="$CXR" "$CXR/bin/wineserver" -k
```python
2. Install **MoltenVK 1.4.2** (or the patched one from `patches/moltenvk`), or play in DirectX 11.
3. If using patched MoltenVK, delete the pipeline cache:
```bash
rm "$HOME/Library/Application Support/CrossOver/Bottles/Arknights Endfield/drive_c/users/crossover/AppData/LocalLow/Gryphline/Endfield/vulkan_pso_cache.bin"
```python
**Links:** [graphics-performance.md → Experimental: the Vulkan renderer](graphics-performance.md#experimental-the-vulkan-renderer) · [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics)
---
### 7. Vulkan mode: logged out with every app closed after teleporting to Snowy Forest
**Symptom:** GPU hang that makes macOS kill WindowServer (logs you out).
**Root Cause:** A GPU hang in stock MoltenVK when teleporting to the Snowy Forest area.
**Fix:** The patched MoltenVK from `patches/moltenvk` is meant to fix this. Ensure you're using the patched version (the FineWine Patcher ships it from 1.1.0 on). If using stock MoltenVK 1.4.2, play that area in DirectX 11.
**Links:** [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics) · [graphics-performance.md](graphics-performance.md)
---
### 8. Vulkan mode: bushes/grass render as odd, stretched polygons after updating patched MoltenVK
**Symptom:** The game's Vulkan pipeline cache is stale; meshes draw with wrong shader/descriptor data.
**Root Cause:** `vulkan_pso_cache.bin` was compiled under the previous module build; after module changes (or `MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS` changes), the game reuses mismatched entries.
**Fix (manual):** Quit the game, delete the cache, and let it rebuild:
```bash
rm "$HOME/Library/Application Support/CrossOver/Bottles/Arknights Endfield/drive_c/users/crossover/AppData/LocalLow/Gryphline/Endfield/vulkan_pso_cache.bin"
```python
The next launch is slower while pipelines recompile (same cold-cache behavior as shader warm-up).
**Note:** This project deliberately does **not** delete the cache automatically.
**Links:** [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics)
---
### 9. Vulkan mode: a few pipelines fail to compile (`VkShaderModule ... 'sampler' attribute parameter is out of bounds: must be between 0 and 15`)
**Symptom:** MoltenVK binds descriptors for push-descriptor sets individually (Metal argument buffers are disabled for them), so a shader using more than 16 combined image samplers exceeds Metal's 16-slot limit.
**Root Cause:** Upstream MoltenVK limitation — a known constraint with certain material permutations.
**Mitigation:** These are usually unused material permutations. If a visible object is missing or black, this is the cause. Capture with `MVK_CONFIG_LOG_LEVEL=3` in a `diagnose-vulkan.sh` capture for upstream reporting.
**Links:** [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics)
---
### 10. `unityplayer.dll` "missing or corrupt" (error 1114)
**Symptom:** DLL-init failure, usually from swapping graphics DLLs or launching `Endfield.exe` directly without the launcher's working directory.
**Root Cause:** Swapping `d3d11/d3d12/dxgi.dll` with `apple_gptk` copies breaks `unityplayer.dll` initialization.
**Fix:** Restore CrossOver's default `d3d11/d3d12/dxgi.dll` and launch via the Gryphline launcher.
**Links:** [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics)
---
### 11. High Resolution Mode (bottle's Advanced Settings) renders a white screen
**Symptom:** Enabling High Resolution Mode causes a white screen.
**Fix:** Leave **High Resolution Mode off** (this project's known issue [#2](https://github.com/stoicswe/Endfield_FineWine/issues/2); it would also quadruple the pixel count, causing performance issues).
**Links:** [troubleshooting.md → In-game graphics](troubleshooting.md#in-game-graphics) · [14-performance-on-16gb-macs.md](14-performance-on-16gb-macs.md)
---
### 12. Black screen on later launches
**Symptom:** The game launches once but shows a black screen on subsequent launches.
**Workaround:** Delete the game's registry data and log in again:
- Via CrossOver → **Run Command** → `regedit`
- Delete `HKCU\Software\Gryphline\Endfield` and `...\Gryphline\sdk_data\...` (settings and login cache).
- This resets in-game settings; you'll need to reconfigure them.
**Links:** [troubleshooting.md → General](troubleshooting.md#general)
---
### 13. Two copies of the game running
**Symptom:** A direct `launch-endfield.sh` start plus one from the launcher fight over the same files ("The process cannot access the file..." in `Player.log`).
**Fix:** Quit both instances and start one. Ensure only one launch path is active (either the launcher or a manual script, not both).
**Links:** [troubleshooting.md → General](troubleshooting.md#general)
---
### 14. Freeze with sound still playing on a 16 GB Mac
**Symptom:** The picture freezes while sound keeps playing; the game never recovers.
**Root Cause:** Memory-pressure freeze — one game thread at ~99–100% CPU, GPU memory collapses,