Skip to content

bottle_and_game_install

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

Endfield_FineWine — Installation & Setup Guide

Arknights: Endfield can be run on Apple‑Silicon macOS via a custom‑patched CrossOver Wine.
This guide walks you through every step: system requirements, dependency installation, three supported installation methods, verification, and troubleshooting.

Table of Contents

  1. Quick Overview
  2. System Requirements
  3. Installation Methods
  1. Dependencies
  2. Platform‑Specific Instructions
  1. Verification
  2. Troubleshooting
  3. Related Documentation & Links

Quick Overview

Endfield_FineWine is not a pip/conda package. It is a collection of Wine patches, scripts, and documentation that let you build a patched CrossOver Wine capable of running Arknights: Endfield on macOS. The core workflow is:

  1. Build a minimal 64‑bit Wine (x86_64 under Rosetta 2).
  2. Swap three patched modules (ntdll.so, kernel32.dll, ntoskrnl.exe) into a copy of CrossOver.
  3. Create a Windows‑11 64‑bit bottle named “Arknights Endfield.”
  4. Install the Gryphline launcher and the game into the bottle.
  5. Launch the game with -force-d3d11 (DirectX 11) to render through Apple’s D3DMetal.

All of the above is automated by the scripts/ folder or by the FineWine Patcher.app GUI.

System Requirements

Component Minimum Recommended
Hardware Apple Silicon Mac (M1/M2/M3/M4) Mac Pro/Book Pro (12‑core CPU, 24 GB RAM)
macOS 15 (Sequoia) or newer 27.0 (or 26.5)
Rosetta 2 Required (softwareupdate --install-rosetta --agree-to-license) —
CrossOver Licensed copy, v26.3 (matching the patched Wine ABI) —
Disk ~5 GB for the build tree —
Time Build ~10 min on a 10‑core M4; full workflow ~30 min —
Game Licensed Arknights: Endfield (Gryphline) —
Optional Apple’s Game Porting Toolkit 4 (GPTK4) for D3DMetal 4 / DLSS frame‑generation —

Note: Intel‑based Macs are not supported. The patched Wine is x86_64 and must run under Rosetta 2.

Installation Methods

3.1 Using the FineWine Patcher.app (recommended)

The patcher-app/ bundle provides a one‑click GUI that performs the entire build‑and‑deploy pipeline, including code‑signing and bundle re‑sealing.

Steps

# 1. Clone the repository (if you haven't already)

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

# 2. Open the Patcher.app (it is a SwiftPM‑built macOS app)

open patcher-app/FineWine\ Patcher.app
```text

The app will:

- Fetch CrossOver 26.3 source and build the patched Wine.  
- Swap the three core modules (`ntdll.so`, `kernel32.dll`, `ntoskrnl.exe`).  
- Re‑sign the bundle with an ad‑hoc signature and remove quarantine.  
- Prompt you to mount Apple’s GPTK4 DMG (optional) and inject D3DMetal 4.  
- Create the `Arknights Endfield` bottle and set `CX_GRAPHICS_BACKEND = d3dmetal`.  
- Generate a launch script (`scripts/launch-endfield.sh`) that passes `-force-d3d11`.

**What you need first**

- A licensed copy of **CrossOver 26.3** installed at `/Applications/CrossOver.app`.  
- Rosetta 2 already installed (the app will verify this).  
- ~5 GB free disk space.

---

### 3.2 Manual Scripted Build & Deploy

If you prefer to run every step from the command line (or to audit the process), use the provided shell scripts.

#### 3.2.1 Clone & Initialise

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

#### 3.2.2 Install Build Dependencies (macOS)

```bash

# Homebrew (Apple Silicon)

brew install bison flex mingw-w64 pkg-config git make \
               freetype gnutls sdl2

# Ensure bison ≥ 3.0 (macOS ships bison 2.3)

which bison               # must NOT be /usr/bin/bison
```bash

#### 3.2.3 Build the Patched Wine

```bash

# Full one‑shot (fetches source, applies 24 patches, configures, builds)

./scripts/build-wine.sh all

# → produces a minimal x86_64 Wine under Rosetta 2 in ./build/wine-build64

```bash

*Or step‑by‑step (useful for debugging):*

```bash
./scripts/build-wine.sh deps       # install bison, mingw-w64, meson, etc.
./scripts/build-wine.sh fetch      # download CrossOver 26.3 Wine source (~142 MB)
./scripts/build-wine.sh apply      # git apply all 24 patches
./scripts/build-wine.sh configure  # 64‑bit only, under `arch -x86_64`
./scripts-build-wine.sh build      # make -j$(sysctl -n hw.ncpu)
```bash

#### 3.2.4 Deploy the Patched Wine into CrossOver

```bash

# Copies /Applications/CrossOver.app → /Applications/CrossOver_Endfield_Patch.app

# and swaps the three patched modules + optional GPTK4 D3DMetal

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

*Environment variables you may set:*

| Variable | Meaning |
|----------|---------|
| `GPTK_DIR` | Path to the mounted GPTK4 DMG’s `redist/lib/external/` folder (optional). |
| `MOD_CHAIN=1` | Enable the mod‑chain (EFMI → CrossOver `d3d11.dll`) step (see `mod-integration-plan.md`). |
| `MOD_BOTTLE` | Bottle name, default `Arknights Endfield`. |

The script will:

- Copy the original CrossOver app.  
- Move the three original modules aside as `.cxorig` backups.  
- Copy the patched `ntdll.so`, `kernel32.dll`, `ntoskrnl.exe` into the appropriate `lib/` directories.  
- Add the `@loader_path/../../../lib64` rpath to `ntdll.so` (required for D3DMetal).  
- Re‑sign the outer bundle (`codesign --force --sign - --preserve-metadata=entitlements`).  
- Verify the bundle (`codesign --verify --deep --strict`).  

#### 3.2.5 Create the Bottle & Install the Game

```bash

# Creates a Windows‑11 64‑bit bottle named "Arknights Endfield"

# with D3DMetal, DLSS, and MSync enabled.

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

Then install the game:

```bash

# Using CrossOver’s GUI:

# 1. Open CrossOver_Endfield_Patch.app

# 2. Bottle “Arknights Endfield” → “Install Application”

# 3. Point at the Windows launcher exe (e.g. GRYPHLINK_<ver>.exe)

# 4. Log in, let the launcher download the game.

# Or via CLI:

/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver/bin/wine \
    --bottle "Arknights Endfield" --wait-children \
    ~/Downloads/GRYPHLINK_<ver>.exe
```bash

#### 3.2.6 Launch the Game

```bash

# Recommended: use the provided launch script (adds -force-d3d11, debug logging, CX_LOG handling)

./scripts/launch-endfield.sh

# Or manually:

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

---  

### 3.3 Source‑Only (for auditors & contributors)

If you only need the raw source (patches, scripts, docs) without running the build:

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

# The repository contains:

# patches/          – LGPL‑2.1+ Wine patches + dw‑proton stage‑2 set

# scripts/          – build/swap/bottle/launch helpers

# docs/             – full engineering write‑up

# patcher-app/      – SwiftPM GUI (optional)

# mod-injection/    – mod‑loading research (not required for launch)

```text

No further installation is required; just follow the *Manual Scripted Build & Deploy* section above.

---  

## Dependencies

| Category | Packages (macOS Homebrew) | Reason |
|----------|--------------------------|--------|
| **Build tools** | `bison` (≥ 3.0), `flex`, `mingw-w64`, `pkg-config`, `git`, `make` | Compile Wine from source |
| **Libraries** | `freetype`, `gnutls`, `sdl2` | Wine runtime dependencies |
| **Optional** | `molten-vk` (via `brew install molten-vk`) | Provides the system‑wide MoltenVK if you want to experiment with Vulkan |
| **Rosetta 2** | `softwareupdate --install-rosetta --agree-to-license` | Required to run the x86_64 Wine on Apple Silicon |
| **CrossOver** | Licensed copy, **v26.3** | The patched modules are built against CrossOver 26.3’s Wine ABI |

*On Windows or Linux the same Wine source can be built, but the project’s primary target is macOS; the dw‑proton patches are validated on Linux first.*

---  

## Platform‑Specific Instructions

### 5.1 macOS (Apple Silicon)

1. **Rosetta 2** – already required; the build scripts enforce `arch -x86_64`.  
2. **CrossOver 26.3** – download from <https://www.codeweavers.com/crossover> and install to `/Applications/CrossOver.app`.  
3. **Follow one of the installation methods** above (Patcher.app or scripts).  
4. **Graphics backend** – the bottle is pre‑configured with `CX_GRAPHICS_BACKEND = d3dmetal`. If you wish to switch to DXMT or DXVK, run:

   ```bash

# Example: switch to DXMT

   defaults write ~/Library/Application\ Support/CrossOver/Bottles/Arknights\ Endfield/cxbottle.conf \
       CX_GRAPHICS_BACKEND -string "dxmt"
```text

5. **Launch** via `./scripts/launch-endfield.sh` or the Gryphline launcher’s “Launch with DirectX 11” dropdown.

### 5.2 Windows (CrossOver on Intel / AMD)

The repository is **macOS‑centric**, but the same patched Wine can be used on Windows under CrossOver (or plain Wine). If you want to try the dw‑proton baseline on Windows:

1. Install **CrossOver** (any recent version).  
2. Build the patched Wine (same `./scripts/build-wine.sh all`).  
3. Swap modules as in `swap-into-crossover.sh` (adjust paths for Windows).  
4. Create a bottle and install the game; however, **Endfield will fall back to Vulkan/DX12** and may exhibit the white‑screen issue unless you force DirectX 11 (`-force-d3d11`).  

*Note: Full ACE anti‑cheat support on Windows is already achieved by dw‑proton; this repo’s additional Rosetta‑2 fixes are only relevant on macOS.*

### 5.3 Linux (dw‑proton baseline)

The dw‑proton patches are developed for Linux Proton. If you wish to verify the patch set:

1. Install a recent **Proton‑GE** or **dw‑proton** (via Heroic/Lutris).  
2. Apply the four patches from `b816be489` (int3 spoof, ntoskrnl em‑backports, NtDelayExecution QPC, wintrust bypass – the latter removed).  
3. Launch Endfield; it should reach the login screen.  

The macOS workflow re‑uses these same patches, but the build environment (Rosetta 2, CrossOver bundle) is what differs.

---  

## Verification

After installation, run the following checks:

| Check | Command | Expected result |
|-------|---------|-----------------|
| **Patched Wine version** | `/Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver/bin/wine --version` | `wine-26.3` (or the version your build produced) |
| **Patched modules present** | `ls /Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver/lib/wine/x86_64-unix/ntdll.so` |

Clone this wiki locally