Skip to content

installation

Jump to bottom
runner edited this page Oct 5, 2026 · 15 revisions

Endfield_FineWine Installation Documentation

Overview

Endfield_FineWine enables running Arknights: Endfield on Apple Silicon Macs through a custom-patched CrossOver Wine. This project provides patches to CrossOver's Wine, plus scripts and documentation to build and deploy them.

⚠️ Important Disclaimer: These patches are provided as-is. While they allow Endfield's anti-cheat to operate on macOS like it does on Windows, you assume all risks associated with using this tool. Running the game in an unsupported configuration may violate its Terms of Service.

Table of Contents

  1. System Requirements
  2. Installation Methods
  3. Method 1: Using the FineWine Patcher.app (Recommended)
  4. Method 2: Manual Build and Installation
  5. Post-Installation Setup
  6. Verification Steps
  7. Troubleshooting
  8. Related Documentation

System Requirements

Hardware Requirements

Component Requirement Notes
Mac Apple Silicon (M-series) Intel Macs are NOT supported
CPU M1 Pro/Max/Ultra, M2 Pro/Max/Ultra, M3 Pro/Max, M4 Pro/Max recommended MacBook Air (any chip) is NOT recommended — no active cooling
RAM 24 GB+ recommended 16 GB works but is memory-constrained (see Performance on 16 GB Macs)
Storage ~15 GB free space ~5 GB for build tree + game installation

Software Requirements

Software Version Installation
macOS 15 (Sequoia) or newer Tested on macOS 27.0 and 26.5
Rosetta 2 Required softwareupdate --install-rosetta --agree-to-license
CrossOver 26.3 (licensed) From codeweavers.com
Xcode Command Line Tools Latest xcode-select --install
Homebrew Latest (Apple Silicon) brew.sh — installs to /opt/homebrew
Game Licensed Arknights: Endfield Installed via Gryphline launcher

Performance Expectations

Mac Tier Settings Expected FPS
M4 Pro / M3 Pro / M4 Max (24 GB+) Medium, 100% render scale ~60 FPS
Base M1/M2/M3/M4 (16 GB) Low / Very Low 30–45 FPS
MacBook Air (any chip) ❌ Not recommended —

⚠️ Thermal Warning: Expect ~90°C thermals and fully maxed CPU on any Mac. Performance is CPU + RAM bound, not GPU. Actively cooled Macs (MacBook Pro, Mac Studio, Mac mini) required.

Installation Methods

This project offers two installation approaches:

Method Difficulty Time Best For
FineWine Patcher.app Easy 5–10 min Most users; no developer tools needed
Manual Build Advanced 20–60 min Developers; auditing; customization

Method 1: Using the FineWine Patcher.app (Recommended)

The FineWine Patcher.app is a GUI tool that automates the entire process: it copies CrossOver, applies the patched Wine modules, optionally installs Apple's GPTK4/D3DMetal, re-seals the bundle, and creates the game bottle.

Step 1: Download the Patcher

  1. Go to the Releases page
  2. Download the latest FineWine Patcher.app.zip
  3. Unzip and place FineWine Patcher.app in your /Applications folder

Step 2: Prepare CrossOver and GPTK4 (Optional)

  1. Install CrossOver 26.3 from codeweavers.com (licensed copy required)
  2. Optional: Download GPTK4 for best performance:
  • Go to Apple Developer Downloads
  • Sign in with Apple ID (free Apple Developer account works)
  • Download "Evaluation environment for Windows games 4.x" DMG
  • Mount the DMG (it will appear under /Volumes/)

Step 3: Run the Patcher

  1. Launch FineWine Patcher.app from /Applications
  2. The app will detect your CrossOver 26.3 installation
  3. Optional: If you mounted the GPTK4 DMG, click "Install GPTK4 / D3DMetal" and select the mounted volume
  4. Click "Patch CrossOver" — this creates /Applications/CrossOver_Endfield_Patch.app
  5. Click "Create Bottle" — creates the "Arknights Endfield" bottle with optimal settings
  6. Click "Install Game" — launches CrossOver to install the Gryphline launcher

Step 4: Install the Game

  1. In the opened CrossOver_Endfield_Patch window, select the Arknights Endfield bottle
  2. Click Install Application → choose the downloaded Gryphline launcher (GRYPHLINK_<version>.exe)
  3. Keep default install location, log in, and let the launcher download the game

Step 5: Launch the Game

  1. Open CrossOver_Endfield_Patch.app (NOT the stock CrossOver.app)
  2. Select the Arknights Endfield bottle
  3. Double-click GRYPHLINK
  4. In the launcher: click the dropdown next to Start → "Launch with DirectX 11"

Critical: Always use "Launch with DirectX 11" (passes -force-d3d11). The plain Start button uses Vulkan/DX12 which don't work well.

Method 2: Manual Build and Installation

For developers or those who want full control/auditability.

Step 1: Clone the Repository

git clone https://github.com/stoicswe/Endfield_FineWine.git
cd Endfield_FineWine
```bash

### Step 2: Install Build Dependencies

```bash

# Install Homebrew dependencies

brew install bison mingw-w64 meson pkg-config git make flex

# Ensure bison 3.0+ is first in PATH (macOS ships 2.3)

echo 'export PATH="/opt/homebrew/opt/bison/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

# Verify

which bison  # Should be /opt/homebrew/opt/bison/bin/bison
bison --version  # Should be 3.8+
```bash

### Step 3: Build the Patched Wine

**One-shot build (recommended):**

```bash
./scripts/build-wine.sh all
```bash

This runs all stages (~20–60 minutes on M4 Pro):
1. `deps` — Install Homebrew dependencies
2. `fetch` — Download CrossOver 26.3 Wine source (~142 MB)
3. `apply` — Apply all 24 patches (verified clean)
4. `configure` — Configure 64-bit-only build under `arch -x86_64`
5. `build` — Compile with `make -j`

**Step-by-step (for debugging):**

```bash
./scripts/build-wine.sh deps       # Install dependencies
./scripts/build-wine.sh fetch      # Download Wine source
./scripts/build-wine.sh apply      # Apply patches
./scripts/build-wine.sh configure  # Configure build
./scripts/build-wine.sh build      # Compile
```bash

> **Note**: This builds a **minimal 64-bit-only Wine** (no bundled fonts/TLS/graphics libs). We only swap 3 core modules into CrossOver, which provides everything else.

### Step 4: Deploy into CrossOver

**Scripted (recommended):**

```bash
./scripts/swap-into-crossover.sh
```bash

**With GPTK4 (optional):**

```bash

# Mount GPTK4 DMG first, then:

GPTK_DIR="/Volumes/<GPTK volume>/redist/lib/external" ./scripts/swap-into-crossover.sh
```bash

This script:
1. Copies `/Applications/CrossOver.app` to a staging area
2. Swaps 3 patched modules:
  - `lib/wine/x86_64-unix/ntdll.so` (Rosetta fixes + QPC timing)
  - `lib/wine/x86_64-windows/kernel32.dll` (KiUser*Dispatcher int3 spoof)
  - `lib/wine/x86_64-windows/ntoskrnl.exe` (17 kernel backports)
3. Adds `@loader_path/../../../lib64` rpath to `ntdll.so`
4. Re-seals the bundle with ad-hoc signature
5. Moves to `/Applications/CrossOver_Endfield_Patch.app`

**Manual deployment (for auditing):**

```bash
APP="/Applications/CrossOver_Endfield_Patch.app"
ditto --noextattr --noqtn /Applications/CrossOver.app "$APP"
CXR="$APP/Contents/SharedSupport/CrossOver"
B="$PWD/build/wine-build64"

# Backup and swap modules

for f in x86_64-unix/ntdll.so x86_64-windows/kernel32.dll x86_64-windows/ntoskrnl.exe; do
  mv "$CXR/lib/wine/$f" "$CXR/lib/wine/$f.cxorig"
done

cp "$B/dlls/ntdll/ntdll.so"                           "$CXR/lib/wine/x86_64-unix/ntdll.so"
cp "$B/dlls/kernel32/x86_64-windows/kernel32.dll"     "$CXR/lib/wine/x86_64-windows/kernel32.dll"
cp "$B/dlls/ntoskrnl.exe/x86_64-windows/ntoskrnl.exe" "$CXR/lib/wine/x86_64-windows/ntoskrnl.exe"

# Fix ntdll.so rpath for D3DMetal

install_name_tool -add_rpath "@loader_path/../../../lib64" "$CXR/lib/wine/x86_64-unix/ntdll.so"
codesign --force --sign - "$CXR/lib/wine/x86_64-unix/ntdll.so"

# Re-seal outer bundle

xattr -drs com.apple.quarantine "$APP"
xattr -rd com.apple.FinderInfo "$APP"
codesign --force --sign - --preserve-metadata=entitlements "$APP"
codesign --verify --deep --strict "$APP" && echo "✅ Patched app verifies"
```bash

### Step 5: Create the Bottle

```bash
./scripts/create-bottle.sh
```bash

This creates a bottle named **"Arknights Endfield"** with:
- Windows 11 64-bit
- Graphics: D3DMetal
- DLSS (MetalFX): Enabled
- MSync: Enabled

**To update an existing bottle:**

```bash
UPDATE=1 ./scripts/create-bottle.sh
```bash

### Step 6: Install the Game

```bash

# Download Gryphline launcher from https://endfield.gryphline.com

# Then install via CrossOver GUI or command line:

CXR="/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver"
"$CXR/bin/wine" --bottle "Arknights Endfield" --wait-children ~/Downloads/GRYPHLINK_<version>.exe
```javascript

Keep default install location, log in, and let the launcher download the game.

### Step 7: Launch the Game

**Using the launch script (handles cleanup, args, logging):**

```bash

# Standard launch (DirectX 11)

./scripts/launch-endfield.sh

# With debug logging

DEBUG=light ./scripts/launch-endfield.sh   # Wine errors only
DEBUG=1 ./scripts/launch-endfield.sh       # Full CrossOver log (heavy)

# Experimental Vulkan (requires patched MoltenVK)

GFXARGS=-force-vulkan ./scripts/launch-endfield.sh
```bash

**Direct wine invocation:**

```bash
CXR="/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver"
"$CXR/bin/wine" --bottle "Arknights Endfield" \
  --cx-app "C:/Program Files/GRYPHLINK/games/Arknights Endfield/Endfield.exe" -force-d3d11
```bash

**Or via GUI:** Open `CrossOver_Endfield_Patch.app` → select bottle → run GRYPHLINK → "Launch with DirectX 11"

---

## Post-Installation Setup

### Graphics Configuration

The bottle is pre-configured with optimal settings. To verify or change:

1. Open `CrossOver_Endfield_Patch.app`
2. Select **Arknights Endfield** bottle
3. Click **Advanced Settings** → **Graphics**
4. Ensure:
  - **Graphics Backend**: D3DMetal (recommended) or DXMT
  - **DLSS (MetalFX)**: ON
  - **MSync**: ON
  - **High Resolution Mode**: OFF (causes white screen)

### Game Renderer Setting

**Critical**: Endfield must run in **DirectX 11** mode.

- **Via Launcher**: Dropdown next to Start → "Launch with DirectX 11"
- **Via Command Line**: Add `-force-d3d11` (handled by `launch-endfield.sh`)
- **Game updates may reset this** — re-select DirectX 11 if white screen returns

### Optional: Mod Support (EFMI/XXMI)

Experimental mod chain support is available. See [Mod Injection Research](mod-injection/README.md) and [Patcher Integration Plan](mod-injection/08-patcher-integration-plan.md).

```bash

# Enable mod chain (after EFMI installed in bottle)

MOD_CHAIN=1 ./scripts/swap-into-crossover.sh
```bash

---

## Verification Steps

### 1. Verify Patched App Signature

```bash
codesign --verify --deep --strict /Applications/CrossOver_Endfield_Patch.app

# Should output: "valid on disk" and "satisfies its Designated Requirement"

```bash

### 2. Verify Patched Modules Load

```bash

# Launch with debug logging

DEBUG=light ./scripts/launch-endfield.sh

# Check log for:

# - "set_graphics_backend using d3dmetal as the graphics backend"

# - No "error loading cxcompatdb.so" messages

# - Game reaches login screen

```javascript

### 3. Verify Anti-Cheat Passes

In the debug log, confirm:
- `ACE-Base64.dll`, `ACE-Service64.exe`, `ACE-BASE.sys` load without "driver error 13"
- No `unimplemented function ntoskrnl.exe.*` aborts

### 4. Verify Graphics Backend

In the log, look for:
```javascript
set_graphics_backend using d3dmetal as the graphics backend
```text
Or for DXMT:
```text
set_graphics_backend using dxmt as the graphics backend
```text

### 5. Performance Baseline

On M4 Pro (24 GB), expect:
- ~60 FPS on Medium at 100% render scale
- CPU at ~100% on one core (Rosetta + Unity main thread)
- GPU at 55–65% utilization
- ~5–6 GB GPU memory in use

---

## Troubleshooting

### Setup & Deployment Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| **"CrossOver.app is version X, expected 26.3"** | Version mismatch | Install CrossOver 26.3 exactly |
| **"CrossOver_Endfield_Patch is damaged"** | Broken code signature | Click **Cancel** (not Move to Trash), re-run `./scripts/swap-into-crossover.sh`

Clone this wiki locally