Skip to content

requirements

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

Requirements — Getting Started with Endfield_FineWine

Overview

This page outlines all the hardware, software, and build requirements needed to run Arknights: Endfield on Apple Silicon macOS using the custom-patched CrossOver Wine from this repository. The project requires specific versions of macOS, CrossOver, and development tools to ensure compatibility with the anti-cheat fixes and graphics optimizations.

System Requirements

Hardware

Component Minimum Recommended Notes
Processor Apple Silicon (M-series) M4 Pro / M3 Pro / M4 Max Intel is not supported
Memory 16 GB 24 GB or more Unified memory; 16 GB is playable but memory-bound
Storage 5 GB free space 10 GB free space For build tree + bottle + game
Graphics Integrated Apple Silicon GPU Integrated Apple Silicon GPU No discrete GPU required
Cooling Actively cooled Mac Actively cooled Mac MacBook Air is OFF-LIMITS (thermal throttling)

⚠️ Thermal Warning: Expect ~90°C thermals under sustained play. Use a MacBook Pro, Mac Studio, or Mac mini for best results.

Operating System

  • macOS 15 (Sequoia) or newer
  • Tested on: macOS 27.0, macOS 26.5, macOS 26.2
  • Rosetta 2 required: softwareupdate --install-rosetta --agree-to-license

Software Dependencies

Required Applications

Application Version Purpose
CrossOver 26.3 (licensed) Wine wrapper; must match build Wine ABI
Xcode Command Line Tools Latest clang, make, git
Homebrew Latest Package manager for dependencies
The Game Licensed copy Arknights: Endfield via Gryphline launcher

⚠️ Critical: CrossOver 26.3 is required. The patched Wine modules are built against this specific ABI.

Installation Commands

# Install Rosetta 2 (required)

softwareupdate --install-rosetta --agree-to-license

# Install Xcode Command Line Tools

xcode-select --install

# Install Homebrew (if not present)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required Homebrew packages

brew install bison git make mingw-w64 pkg-config
```bash

---

## Build Requirements (For Patched Wine)

### Prerequisites for Building

| Package | Command | Notes |
|---------|---------|-------|
| **Bison** | `brew install bison` | Must be ≥3.0; macOS system version is 2.3 |
| **Clang/LLVM** | `brew install gcenx/wine/cx-llvm` | Required for `win32on64` compiler |
| **Mesa** | `brew install mesa` | For Vulkan support |
| **SDL2** | `brew install sdl2` | CrossOver dependency |
| **GNUTLS** | `brew install gnutls` | TLS/SSL for Wine |
| **Freetype** | `brew install freetype` | Font rendering |
| **MoltenVK** | `brew install molten-vk` | Vulkan on Metal |

### Environment Variables

Set these before building:

```bash
export PATH="/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"
export CC="$(brew --prefix cx-llvm)/bin/clang"
export CXX="${CC}++"
export BISON="$(brew --prefix bison)/bin/bison"
export MACOSX_DEPLOYMENT_TARGET=10.14
export BUILDROOT="$PWD/build"
export INSTALLROOT="$PWD/install"
```bash

### Build Commands

```bash

# Clone the repository

git clone <your-fork-url> Endfield_FineWine && cd Endfield_FineWine

# Build the patched Wine (all dependencies → fetch → patch → configure → build)

./scripts/build-wine.sh all

# Or step by step:

./scripts/build-wine.sh deps       # Install Homebrew dependencies
./scripts/build-wine.sh fetch      # Download CrossOver 26.3 Wine source
./scripts/build-wine.sh apply      # Apply all patches
./scripts/build-wine.sh configure  # Configure for 64-bit only
./scripts/build-wine.sh build      # Compile Wine
```yaml

> **⚠️ Build Time:** ~20-60 minutes on a 10-core M4; longer on fewer cores (1.5–2.5 h cold on CI runner)

---

## Runtime Requirements (For Running the Game)

### CrossOver Setup

1. **Install CrossOver 26.3** from [codeweavers.com](https://www.codeweavers.com/crossover)
2. **Create the "Arknights Endfield" bottle** using the provided script:
   ```bash
   ./scripts/create-bottle.sh    # Creates Windows 11 64-bit bottle with D3DMetal + DLSS + MSync
```bash

### Game Installation

1. **Download the Gryphline launcher** from [endfield.gryphline.com](https://endfield.gryphline.com)
2. **Install into the bottle** using CrossOver GUI or command line:
   ```bash

# Using CrossOver GUI:

# 1. Open CrossOver_Endfield_Patch.app

# 2. Select "Arknights Endfield" bottle

# 3. Choose "Install Application into Bottle"

# 4. Point to the downloaded GRYPHLINK launcher
   
# Or using command line:

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

### Launch Options

**Recommended:** Use the Gryphline launcher with **"Launch with DirectX 11"** (dropdown next to Start button)

**Or launch directly:**
```bash

# Easy launcher script (handles wineserver cleanup, graphics args, debug logging)

./scripts/launch-endfield.sh

# Or invoke wine directly:

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

---

## Optional Requirements

### Apple's Game Porting Toolkit 4 (GPTK4)

> **⚠️ Evaluation-only software** — download from Apple yourself; you may not redistribute it.

**Purpose:** Upgrades D3DMetal from 3.0 → 4 (DirectX 12 → Metal 4), adds MetalFX frame generation and HDR support.

**Installation Steps:**

```bash

# 1. Download from Apple

# Visit https://developer.apple.com/games/game-porting-toolkit/

# Download "Evaluation environment for Windows games 4.x" DMG

# 2. Mount the DMG and apply to patched CrossOver

GPTK_VOL="/Volumes/<mounted GPTK volume>"
APP="/Applications/CrossOver_Endfield_Patch.app"
cd "$APP/Contents/SharedSupport/CrossOver/lib64/apple_gptk/external"
mv D3DMetal.framework D3DMetal.framework-old
mv libd3dshared.dylib libd3dshared.dylib-old
ditto --noextattr --noqtn "$GPTK_VOL/redist/lib/external/" .
cd - >/dev/null

# 3. Re-seal the bundle

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

**Alternative (scripted):**
```bash
GPTK_DIR="/Volumes/<mounted GPTK volume>/redist/lib/external" ./scripts/swap-into-crossover.sh
```bash

> **⚠️ macOS 27-era software:** GPTK4 targets macOS 27 (beta). On macOS 26, stay on the bundled D3DMetal 3.0.

---

## Troubleshooting Common Issues

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

**Problem:** The swap needs a matching Wine ABI.  
**Solution:** Install CrossOver 26.3 specifically.

### "CrossOver_Endfield_Patch is damaged and can't be opened"

**Problem:** The patched bundle's signature seal is missing or broken.  
**Solution:**
1. Click **Cancel** (not *Move to Trash*)
2. Re-run `./scripts/swap-into-crossover.sh` to re-seal it
3. If manually edited files, re-seal: `codesign --force --sign - --preserve-metadata=entitlements /Applications/CrossOver_Endfield_Patch.app`

### "ACE 'driver error 13' comes back"

**Problem:** The patched `ntdll.so`/`ntoskrnl.exe` aren't loading.  
**Solution:** Verify swap paths and that you launched the *patched* app.

### "Start programs from the CrossOver window"

**Problem:** Per-program app stubs have broken signatures.  
**Solution:** Start programs from the CrossOver window, not from `~/Applications/CrossOver/` stubs.

### "GRYPHLINK isn't listed in the bottle"

**Problem:** Launcher shortcuts weren't registered.  
**Solution:** Re-register them: `cxmenu --bottle "Arknights Endfield" --install`

### "White / blank screen (very common after a game update)"

**Problem:** Game reset renderer to Vulkan/DX12, neither works well.  
**Solution:** Run in DirectX 11 mode:
- Use launcher\'s **"Launch with DirectX 11"** (dropdown next to Start)
- Or launch with `-force-d3d11`
- Do NOT overwrite CrossOver's `d3d11/d3d12/dxgi.dll` with apple_gptk copies

### "High Resolution Mode renders a white screen"

**Problem:** Bottle\'s Advanced Settings "High Resolution Mode" causes issues.  
**Solution:** Leave it **off** (see issue #2 in repository).

### "Black screen on later launches"

**Problem:** Delete game\'s registry data and log in again.  
**Solution:**
```bash

# via CrossOver → Run Command → regedit

reg delete "HKCU\\Software\\Gryphline\\Endfield" /f
reg delete "HKCU\\Software\\Gryphline\\sdk_data\\..." /f
```bash

---

## Related Documentation

- **[Installation Guide](installation.md)** — Detailed step-by-step setup instructions
- **[Graphics Performance](graphics-performance.md)** — Graphics backend selection and GPTK4 setup
- **[Troubleshooting](troubleshooting.md)** — Common failures and their solutions
- **[Technical Architecture](technical.md)** — Under-the-hood technical details
- **[Performance on 16 GB Macs](14-performance-on-16gb-macs.md)** — Optimization for memory-constrained systems

---

## Quick Reference Commands

```bash

# 1. Clone and build

git clone <your-fork-url> Endfield_FineWine && cd Endfield_FineWine
./scripts/build-wine.sh all

# 2. Deploy into CrossOver

./scripts/swap-into-crossover.sh

# 3. Create bottle

./scripts/create-bottle.sh

# 4. Run the game

open /Applications/CrossOver_Endfield_Patch.app

# In launcher: select "Arknights Endfield" → Launch with DirectX 11

```sql

---

## License and Ethics

- **Scripts and documentation:** [MIT](LICENSE)
- **Patches:** Modifications to Wine, so **LGPL-2.1-or-later** (Wine's license)
- **This repo does NOT contain:** CrossOver, Wine, Apple's GPTK, or the game — you bring your own licensed copies of each
- **Scope:** Compatibility work (same category as Valve's Proton on Linux) — no in-game advantage, no modified game logic, no DRM circumvention

---

## Support

For issues and troubleshooting, refer to the **[Troubleshooting Guide](troubleshooting.md)** and check the repository's **[CONTRIBUTING.md](CONTRIBUTING.md)** for reporting guidelines.

Clone this wiki locally