# Endfield_FineWine Troubleshooting Guide

Comprehensive troubleshooting documentation for running **Arknights: Endfield** on Apple Silicon Macs through the custom-patched CrossOver Wine build.

---

## Table of Contents

1. [Quick Diagnostic Checklist](#quick-diagnostic-checklist)
2. [Installation & Setup Issues](#installation--setup-issues)
3. [Runtime Errors & Crash Solutions](#runtime-errors--crash-solutions)
4. [Graphics & Rendering Problems](#graphics--rendering-problems)
5. [Performance & Memory Issues](#performance--memory-issues)
6. [Anti-Cheat & ACE Related Issues](#anti-cheat--ace-related-issues)
7. [Configuration & Environment Problems](#configuration--environment-problems)
8. [Debugging Procedures & Log Analysis](#debugging-procedures--log-analysis)
9. [System Requirements Troubleshooting](#system-requirements-troubleshooting)
10. [Integration & Compatibility Issues](#integration--compatibility-issues)
11. [Escalation & Support](#escalation--support)

---

## Quick Diagnostic Checklist

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 |

---

## Installation & Setup Issues

### 1. "CrossOver.app is version X, expected 26.3"

**Problem:** The swap script requires CrossOver 26.3 specifically for ABI compatibility.

**Solution:**
```bash

# 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