Repository navigation
troubleshooting
runner edited this page Oct 5, 2026
·
15 revisions
Comprehensive troubleshooting documentation for running Arknights: Endfield on Apple Silicon Macs through the custom-patched CrossOver Wine build.
- Quick Diagnostic Checklist
- Installation & Setup Issues
- Runtime Errors & Crash Solutions
- Graphics & Rendering Problems
- Performance & Memory Issues
- Anti-Cheat & ACE Related Issues
- Configuration & Environment Problems
- Debugging Procedures & Log Analysis
- System Requirements Troubleshooting
- Integration & Compatibility Issues
- Escalation & Support
Before diving into specific issues, verify these basics:
| Check | Command / Action | Expected Result |
|---|---|---|
| macOS Version | sw_vers |
macOS 15 (Sequoia) or newer |
| Architecture | uname -m |
arm64 (Apple Silicon) |
| Rosetta 2 | softwareupdate --install-rosetta --agree-to-license |
Installed successfully |
| CrossOver Version | /Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine --version |
26.3 exactly |
| Patched App Exists | ls /Applications/CrossOver_Endfield_Patch.app |
Bundle present |
| Bottle Exists | ls ~/Library/Application\ Support/CrossOver/Bottles/Arknights\ Endfield/ |
Bottle directory present |
| Game Installed | Check Gryphline launcher in bottle | Game files present |
Problem: The swap script requires CrossOver 26.3 specifically for ABI compatibility.
Solution:
# Verify installed version
defaults read /Applications/CrossOver.app/Contents/Info CFBundleShortVersionString
# If not 26.3, download and install CrossOver 26.3 from:
# https://www.codeweavers.com/crossover
```text
**Root Cause:** The patched Wine modules (`ntdll.so`, `kernel32.dll`, `ntoskrnl.exe`) are built against Wine 11.0 (CrossOver 26.3's base). Version mismatch breaks the module swap.
---
### 2. "CrossOver_Endfield_Patch is damaged and can't be opened" / Exit code 137
**Problem:** The patched bundle's code signature seal is missing or broken. macOS kills all binaries in a bundle with a broken seal (SIGKILL = exit 137).
**Solution:**
```bash
# Click "Cancel" (NOT "Move to Trash") on the damaged dialog
# Then re-run the swap script which re-seals the bundle:
./scripts/swap-into-crossover.sh
# If you manually edited files inside the app, re-seal manually:
codesign --force --sign - --preserve-metadata=entitlements /Applications/CrossOver_Endfield_Patch.app
codesign --verify --deep --strict /Applications/CrossOver_Endfield_Patch.app
```html
**Root Cause:** Modifying binaries inside a signed `.app` invalidates the bundle seal. The swap script handles this automatically, but manual edits require manual re-sealing.
> **Critical:** Never just strip the signature (`xattr -cr` + remove `CodeResources`). On macOS 27+, a provenance-tagged bundle with a stripped seal gets every binary SIGKILLed on launch. Always **re-seal ad-hoc** preserving entitlements.
---
### 3. ACE "driver error 13" Returns After Update
**Problem:** Game update may have reset something, or the patched modules aren't loading.
**Solution:**
1. Verify you're launching **`CrossOver_Endfield_Patch.app`**, not stock `CrossOver.app`
2. Re-run the swap script: `./scripts/swap-into-crossover.sh`
3. Check the bottle's `cxbottle.conf` has `CX_GRAPHICS_BACKEND = "d3dmetal"`
**Root Cause:** The patched `ntdll.so`/`ntoskrnl.exe` aren't loading — either the swap didn't persist or you're using the wrong CrossOver binary.
---
### 4. GRYPHLINK Not Listed in Bottle (Only "Uninstall GRYPHLINK")
**Problem:** Launcher shortcuts weren't registered with CrossOver's menus (common after CLI install).
**Solution:**
```bash
/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver/bin/cxmenu \
--bottle "Arknights Endfield" --install
```bash
Then reopen the bottle's page in CrossOver.
---
### 5. Starting from Spotlight/Launchpad/~/Applications/CrossOver/ Stubs Fails
**Problem:** CrossOver creates per-program app stubs in `~/Applications/CrossOver/` whose signatures don't verify (`codesign`: "code has no resources but signature indicates they must be present").
**Solution:** **Always start programs from the CrossOver window** (the patched `CrossOver_Endfield_Patch.app`), not from stubs or Spotlight.
---
## Runtime Errors & Crash Solutions
### 1. White / Blank Screen (Very Common After Game Update)
**Problem:** Game update reset renderer to **Vulkan or DirectX 12**, which don't work well under CrossOver 26.3.
**Solution:** **Force DirectX 11 mode:**
- In Gryphline launcher: **Dropdown next to Start → "Launch with DirectX 11"**
- Or launch with `-force-d3d11` flag (handled by `scripts/launch-endfield.sh`)
**Why:**
- DX12 → `vkd3d` can't compile game's DXIL/SM6 shaders → `Cannot load DXIL conversion library`
- Vulkan needs newer MoltenVK than CrossOver ships
- DX11 uses mature D3DMetal/DXMT path and renders correctly
> **Do NOT** try to fix by overwriting CrossOver's `d3d11/d3d12/dxgi.dll` with `apple_gptk` copies — that breaks `unityplayer.dll` init (Windows error **1114**).
---
### 2. `unityplayer.dll` "Missing or Corrupt" (Error 1114)
**Problem:** DLL-init failure from swapping graphics DLLs or launching `Endfield.exe` directly without launcher's working directory.
**Solution:**
1. Restore CrossOver's default `d3d11/d3d12/dxgi.dll` from stock `CrossOver.app`
2. Launch via Gryphline launcher (sets up working directory)
3. Use `scripts/launch-endfield.sh` which adds `-force-d3d11`
---
### 3. Two Copies of Game Running Simultaneously
**Problem:** Direct `launch-endfield.sh` start + launcher start fight over same files ("The process cannot access the file…" in `Player.log`).
**Solution:**
```bash
# Kill both and start one:
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
# Then launch once via launcher or script
```bash
---
### 4. Freeze with Sound Still Playing (16 GB Macs)
**Problem:** Memory-pressure freeze — unified memory exhaustion.
**Solution:**
1. Force-quit `Endfield.exe`
2. Free memory (quit browsers, Discord, heavy apps)
3. Relaunch
**Details:** See [14-performance-on-16gb-macs.md](14-performance-on-16gb-macs.md#the-memory-pressure-freeze) — swap climbing past ~6 GB with free memory near zero is the early warning.
---
## Graphics & Rendering Problems
### 1. Vulkan Mode: Black Screen After Changing FPS/V-Sync
**Problem:** CrossOver's bundled MoltenVK 1.2.10 doesn't survive swapchain recreation ([KhronosGroup/MoltenVK#2722](https://github.com/KhronosGroup/MoltenVK/pull/2722)).
**Solution:**
```bash
# Force-close the game:
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
# Then either:
# A) Play in DirectX 11 (recommended)
# B) Install MoltenVK 1.4.2+ (see graphics-performance.md)
```text
---
### 2. Vulkan Mode: Logged Out After Teleporting to Snowy Forest
**Problem:** GPU hang makes macOS kill WindowServer ([#22](https://github.com/stoicswe/Endfield_FineWine/issues/22)).
**Solution:** Play that area in **DirectX 11 mode**. The patched MoltenVK (in `patches/moltenvk/`) aims to fix this; FineWine Patcher 1.1.0+ ships it.
---
### 3. Vulkan Mode: Bushes/Grass Render as Stretched Polygons After MoltenVK Update
**Problem:** Stale Vulkan pipeline cache (`vulkan_pso_cache.bin`) compiled under previous module build.
**Solution:**
```bash
rm "$HOME/Library/Application Support/CrossOver/Bottles/Arknights Endfield/drive_c/users/crossover/AppData/LocalLow/Gryphline/Endfield/vulkan_pso_cache.bin"
```python
Next launch rebuilds pipelines (slower first run). Only affects Vulkan renderer.
---
### 4. Vulkan Mode: Pipeline Compilation Failures (`sampler attribute parameter out of bounds`)
**Problem:** MoltenVK binds push-descriptor sets individually (Metal argument buffers disabled), exceeding Metal's 16-slot limit for combined image samplers.
**Impact:** Usually unused material permutations; if visible object is missing/black, this is the cause. Upstream MoltenVK limitation.
**Workaround:** Use DirectX 11 mode.
---
### 5. High Resolution Mode (Bottle Advanced Settings) → White Screen
**Problem:** Known issue [#2](https://github.com/stoicswe/Endfield_FineWine/issues/2).
**Solution:** Leave **High Resolution Mode OFF** in bottle settings.
---
### 6. Black Screen on Later Launches
**Problem:** Corrupted game registry/settings cache.
**Solution:** Delete game's registry data and log in again:
```bash
# Via CrossOver → Run Command → regedit
# Delete: HKCU\Software\Gryphline\Endfield
# Delete: HKCU\Software\Gryphline\sdk_data\...
```text
This resets in-game settings.
---
## Performance & Memory Issues
### 1. MacBook Air — NOT SUPPORTED
**Problem:** No active cooling → severe thermal throttling → stuttering, freezes, stalls.
**Solution:** **Use actively cooled Mac only** (MacBook Pro, Mac Studio, Mac mini). This is a hard hardware limitation.
---
### 2. Low FPS / Stuttering on 16 GB Macs
**Problem:** Unified memory pressure — game's 5–6 GB GPU allocations share physical RAM with OS/apps.
**Solutions:**
| Setting | Recommendation |
|---------|----------------|
| **Texture Quality** | Low or Medium (main memory lever) |
| **Shadows / Scene Details / Vegetation** | Very Low (reduces draw calls on bottlenecked main thread) |
| **Resolution / Render Scale** | 1080p or 70–80% (GPU has headroom) |
| **DLSS / DLAA** | Enable (MetalFX upscaling works via NVIDIA spoof) |
| **Background Apps** | **Quit all** (browsers, Discord, Creative Cloud, AI assistants) |
| **Frame Cap** | 60 FPS for steadier pacing |
**Measured Data (M4 16 GB):**
- With apps open: 6.8 GB swap, froze on area load
- With apps closed: 2.4→4.9 GB swap, "seriously very playable"
See [14-performance-on-16gb-macs.md](14-performance-on-16gb-macs.md) for full breakdown.
---
### 3. CPU at 100%, ~90°C Thermals
**Expected Behavior:** This is **normal** for this workload.
- Rosetta 2 JIT translation overhead + Unity IL2CPP single-threaded render dispatch
- Apple Silicon chips designed to operate up to 100–105°C before hard throttling
- Performance is **CPU + RAM bound**, not GPU bound
**Mitigation:** Ensure active cooling (MacBook Pro, not Air), quit background apps.
---
## Anti-Cheat & ACE Related Issues
### 1. Game Crashes at Launch with `0x80000003` / `0xC0000005` in `UnityPlayer.dll`
**Problem:** ACE killed process before/during hooking.
**Diagnosis:** Check for `3DM-*.dmp` files — if none, ACE likely blocked injection.
**Status:** This is an **anti-cheat integrity check** issue. The patched modules handle ACE's kernel API requirements, but runtime module integrity checks may still trigger. See [project-information/13-working-solution.md](project-information/13-working-solution.md) — one residual `ntoskrnl.exe.PsGetProcessExitStatus` abort exists but doesn't block login.
---
### 2. "Failed to inject d3d11.dll" (XXMI/EFMI Mod Loader)
**Problem:** Mod loader injection fails under Wine.
**Root Causes (in order of likelihood):**
1. **Module-name collision** — Wine serves builtin `d3d11.dll` instead of mod's (see [mod-injection/02-wine-dll-loading-and-mod-dlls.md](mod-injection/02-wine-dll-loading-and-mod-dlls.md))
2. **ACE blocking injection** — Anti-cheat detects remote thread creation
3. **Injection race** — Game loads `d3d11` before mod injects
**Solutions:**
```bash
# 1. Try d3dcompiler_47 override first (safest, fixes known EFMI flat-mesh issue):
WINEDLLOVERRIDES="d3dcompiler_47=n,b"
# 2. If collision persists, try d3d11/dxgi overrides (may fight backend):
WINEDLLOVERRIDES="d3d11=n,b;dxgi=n,b;d3dcompiler_47=n,b"
# 3. Switch bottle backend to DXMT (structurally closest to Linux/Proton):
# CrossOver → Bottle → Advanced Settings → Graphics → DXMT
# 4. Use XXMI's "Custom Launch → Bypass + Inject Libraries" workaround
# (GameBanana thread 228030)
```yaml
> **Note:** Mod injection research is in [mod-injection/](mod-injection/) — experimental, not yet integrated.
---
## Configuration & Environment Issues
### 1. Bottle Settings Not Persisting / Backend Reverts
**Problem:** `cxbottle.conf` not updated correctly.
**Solution:**
```bash
# Re-apply bottle settings:
UPDATE=1 ./scripts/create-bottle.sh
# Or manually verify ~/Library/Application Support/CrossOver/Bottles/Arknights Endfield/cxbottle.conf:
# "CX_GRAPHICS_BACKEND" = "d3dmetal"
# "CX_ACTIVE_GRAPHICS_BACKEND" = "d3dmetal"
# "DXMT_ENABLE_NVEXT" = "1"
# "WINEMSYNC" = "0"
```bash
---
### 2. GPTK4 / D3DMetal 4 Not Working
**Problem:** GPTK4 requires macOS 27 (beta) + Metal 4. On macOS 26, stay on bundled D3DMetal 3.0.
**Solution:**
```bash
# Verify macOS version:
sw_vers
# If macOS 27+, install GPTK4:
# 1. Download "Evaluation environment