Skip to content

quick_start

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

Endfield_FineWine — Quick Start Guide

Overview

Endfield_FineWine enables Arknights: Endfield to run on Apple Silicon Macs through a custom-patched CrossOver Wine. This project provides the necessary compatibility edits to bring the game to a near-native macOS gaming experience, based on the dw-proton anti-cheat patches and optimized for Apple's D3DMetal graphics.

⚠️ Important: This project does NOT bypass anti-cheat. It adjusts the CrossOver environment to allow Endfield's anti-cheat services to run uninterrupted.

Prerequisites

Hardware & System Requirements

  • Mac: Apple Silicon (M-series) — Intel not supported
  • macOS: 15 (Sequoia) or newer — tested on macOS 27.0 / 26.5
  • Rosetta 2: Required (softwareupdate --install-rosetta --agree-to-license)
  • CrossOver: Licensed version 26.3 from codeweavers.com
  • Development Tools: Xcode Command Line Tools (xcode-select --install) and Homebrew (brew.sh)
  • Disk Space: ~5 GB for the build tree
  • Game: Licensed copy of Arknights: Endfield

Optional but Recommended

  • Apple's GPTK4: For best performance (requires mounting the "Evaluation environment for Windows games …" DMG)
  • Backup: Original CrossOver installation (we'll create a patched copy)

Quick Start: Using the Patcher.app

The easiest way to get started is with the FineWine Patcher.app:

  1. Download the latest release patcher from the releases page
  2. Run the patcher app
  3. If you have Apple's GPTK4 DMG mounted, the patcher can install it automatically
  4. The patcher will create /Applications/CrossOver_Endfield_Patch.app — this is the app you launch

Quick Start: Manual Build and Installation

Step 1: Clone and Prepare

# Clone the repository

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

# Build the patched Wine (this takes ~20-60 minutes)

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

### Step 2: Deploy into CrossOver

```bash

# This creates the patched app at /Applications/CrossOver_Endfield_Patch.app

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

### Step 3: Create the Bottle

```bash

# Creates "Arknights Endfield" bottle with D3DMetal + DLSS + MSync

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

### Step 4: Install the Game

1. Download the Gryphline launcher from [endfield.gryphline.com](https://endfield.gryphline.com)
2. In CrossOver → **Arknights Endfield** bottle → *Install Application into Bottle*
3. Or use command line:
   ```bash
   /Applications/CrossOver_Endfield_Patch.app/Contents/SharedSupport/CrossOver/bin/wine \
     --bottle "Arknights Endfield" \
     --wait-children ~/Downloads/GRYPHLINK_<version>.exe
```javascript
4. Log in and let the launcher download the game

### Step 5: Launch the Game

**From the Gryphline launcher (recommended):**
1. Open **`CrossOver_Endfield_Patch`** (not the stock `CrossOver`)
2. Select the **Arknights Endfield** bottle
3. Double-click **GRYPHLINK**
4. In the launcher, use the **dropdown next to Start → "Launch with DirectX 11"**

**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

---

## Key Configuration Notes

### Graphics Backend

- **Recommended**: DirectX 11 mode (use "Launch with DirectX 11" in launcher)
- **Why DX11?**: DX12 fails with white screen; Vulkan is experimental
- **Backend**: D3DMetal (default), DXMT, or DXVK in bottle settings

### Performance Tips

- **Close background apps** before playing (browsers, Discord, etc.)
- **Use `-force-d3d11`** launch flag (or DX11 launcher option)
- **Set in-game resolution** to 1080p or use 70-80% render scale
- **Enable MSync** in bottle settings (already configured by `create-bottle.sh`)

### Common Issues & Solutions

| Issue | Solution |
|---|---|
| **"CrossOver.app is version X, expected 26.3"** | Install CrossOver 26.3 specifically |
| **"CrossOver_Endfield_Patch is damaged"** | Re-run `./scripts/swap-into-crossover.sh` (it re-seals) |
| **ACE "driver error 13"** | Verify swap paths and launch the *patched* app |
| **White/blank screen** | Use DirectX 11 mode (`-force-d3d11` or launcher option) |
| **Vulkan mode black screen after FPS change** | Use DirectX 11 or upgrade MoltenVK to 1.4.2+ |
| **GRYPHLINK not listed in bottle** | Re-register: `cxmenu --bottle "Arknights Endfield" --install` |

---

## Debug Logging

To capture debug information:

```bash

# Lightweight logging (Wine errors only)

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

# Full logging (CrossOver log - heavy)

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

# Or invoke wine directly with debug channels

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

---

## Advanced Options

### Installing GPTK4 (Optional)

If you have Apple's GPTK4 DMG mounted:
```bash
GPTK_DIR="/Volumes/<GPTK volume>/redist/lib/external" ./scripts/swap-into-crossover.sh
```bash

### Building with Specific Options

```bash

# Build only dependencies

./scripts/build-wine.sh deps

# Build only Wine

./scripts/build-wine.sh build

# Apply patches only

./scripts/build-wine.sh apply
```text

---

## Troubleshooting Guide

### Most Common Problems

1. **White Screen on Launch**
  - **Cause**: Game defaults to Vulkan/DX12, which fail under CrossOver
  - **Fix**: Use `-force-d3d11` or "Launch with DirectX 11" in launcher
  - **Note**: Game updates may reset renderer — re-select DX11

2. **App Says "Damaged and Can't Be Opened"**
  - **Cause**: Bundle signature seal is missing/broken
  - **Fix**: Click **Cancel** (not *Move to Trash*), then re-run `./scripts/swap-into-crossover.sh`
  - **Manual fix**: `codesign --force --sign - --preserve-metadata=entitlements /Applications/CrossOver_Endfield_Patch.app`

3. **ACE "Driver Error 13"**
  - **Cause**: Patched ntdll/ntoskrnl modules aren't loading
  - **Fix**: Verify you're launching the *patched* app, not stock CrossOver

4. **Graphics Issues**
  - **White screen**: Use DX11 mode
  - **Black screen after FPS change**: Use DX11 or upgrade MoltenVK
  - **Error 1114**: Don't overwrite CrossOver's D3D DLLs with apple_gptk copies

### Getting Help

1. **Check the logs**: Use `DEBUG=1 ./scripts/launch-endfield.sh`
2. **Review troubleshooting.md** for detailed solutions
3. **Check performance.md** for optimization tips
4. **Use the failure capture script**: `./scripts/01-capture-failure.sh`

---

## Related Documentation

- **[Installation Guide](docs/installation.md)**: Full setup instructions and engineering background
- **[Graphics Performance](docs/graphics-performance.md)**: Backend selection and GPTK4 setup
- **[Troubleshooting](docs/troubleshooting.md)**: Common issues and solutions
- **[Performance on 16GB Macs](docs/14-performance-on-16gb-macs.md)**: Optimization for memory-constrained systems
- **[Technical Architecture](docs/technical.md)**: Deep dive into how this works under the hood

---

## Quick Commands Summary

```bash

# One-command setup (if you have the game installed)

git clone <repo> Endfield_FineWine && cd Endfield_FineWine
./scripts/build-wine.sh all
./scripts/swap-into-crossover.sh
./scripts/create-bottle.sh
open /Applications/CrossOver_Endfield_Patch.app

# Launch with DX11

./scripts/launch-endfield.sh

# Debug mode

DEBUG=1 ./scripts/launch-endfield.sh
```text

---

## Support & Community

- **GitHub Issues**: Report bugs and ask questions
- **Wiki Documentation**: Comprehensive guides and research notes
- **Community**: Join discussions for tips and shared experiences

---

**Enjoy running Arknights: Endfield on your Apple Silicon Mac!** 🎮

Clone this wiki locally