# 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](#system-requirements)
2. [Installation Methods](#installation-methods)
3. [Method 1: Using the FineWine Patcher.app (Recommended)](#method-1-using-the-finewine-patcherapp-recommended)
4. [Method 2: Manual Build and Installation](#method-2-manual-build-and-installation)
5. [Post-Installation Setup](#post-installation-setup)
6. [Verification Steps](#verification-steps)
7. [Troubleshooting](#troubleshooting)
8. [Related Documentation](#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](docs/14-performance-on-16gb-macs.md)) |
| **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](https://www.codeweavers.com/crossover) |
| **Xcode Command Line Tools** | Latest | `xcode-select --install` |
| **Homebrew** | Latest (Apple Silicon) | [brew.sh](https://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](https://github.com/stoicswe/Endfield_FineWine/releases)
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](https://www.codeweavers.com/crossover) (licensed copy required)
2. **Optional: Download GPTK4** for best performance:
  - Go to [Apple Developer Downloads](https://developer.apple.com/download/all/?q=game%20porting%20toolkit)
  - 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

```bash
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`