Skip to content

contributing

runner edited this page Nov 20, 2026 · 55 revisions

Endfield_FineWine Development Documentation

Table of Contents

  1. Overview
  2. Development Environment Setup
  3. Project Structure and Architecture
  4. Coding Standards and Guidelines
  5. Build Process
  6. Testing Procedures
  7. CI/CD Pipeline
  8. Debugging and Troubleshooting
  9. Release Process
  10. Contribution Guidelines
  11. Code Review Procedures
  12. Development Tools and Links

1. Overview

Endfield_FineWine enables Arknights: Endfield and other Windows games to run on Apple Silicon macOS through compatibility-layer technology. The repository contains two projects that share this goal:

Project Description Needs CrossOver Needs Rosetta 2 macOS State
FineWine (standalone) Menu bar app with its own Wine runtime (native ARM64 Wine, FEX for x64, DXMT for Direct3D 10/11, MoltenVK for Vulkan/D3D12) No No 26 or newer Beta
FineWine Patcher Patches a licensed copy of CrossOver 26.3 so ACE anti-cheat and game protection run on macOS Yes (26.3, licensed) Yes (x64 variant) 15 or newer Established

Core Technologies

  • Wine 11.0 — Windows API compatibility layer, built from CrossOver 26.3 source
  • FEX — x86_64-to-ARM64 CPU emulation for Windows programs under FineWine standalone
  • DXMT — Direct3D 10/11 to Metal translation layer
  • MoltenVK — Vulkan to Metal translation
  • Rosetta 2 — Apple's x86_64-to-ARM64 translation (used by FineWine Patcher)
  • MSync — Mach-semaphore synchronization for Wine primitives

Key Architectural Decisions

  • Surgical module swap: Only three core Wine modules are replaced in CrossOver (ntdll.so, kernel32.dll, ntoskrnl.exe); all other libraries remain stock CodeWeavers binaries
  • 64-bit-only Wine build: Endfield is 64-bit only, so the build uses the standard toolchain without win32on64 or custom Clang
  • Rosetta 2 signal fixes: Two novel fixes in dlls/ntdll/unix/signal_x86_64.c for multi-byte NOP handling and privileged instruction classification
  • ACE anti-cheat port: Ported from Linux dw-proton, including ntoskrnl.exe backports, KiUser*Dispatcher int3 spoof, and NtDelayExecution QPC timing

⚠️ Ethics & Scope: Both projects are provided as-is. Neither bypasses anti-cheat; they change the Wine environment so the game's own anti-cheat services run uninterrupted. Users must own the game. This is compatibility work (same category as Valve's Proton on Linux) — no in-game advantage, no modified game logic, no DRM circumvention. Not affiliated with Gryphline/Hypergryph, Tencent, CodeWeavers, or Apple.


2. Development Environment Setup

Prerequisites

Component Requirement Installation
Mac Apple Silicon (M-series) —
macOS 15 (Sequoia) or newer; tested on 26.5 and 27.0 —
Rosetta 2 Required for FineWine Patcher softwareupdate --install-rosetta --agree-to-license
Xcode Command Line Tools Required xcode-select --install
Homebrew Apple Silicon, /opt/homebrew brew.sh
CrossOver 26.3 specifically (licensed) codeweavers.com
Disk space ~5 GB for build tree —
Build time ~20–60 minutes —

1. Clone the Repository

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

### 2. Install Homebrew Dependencies

```bash

# Core build tools

brew install bison mingw-w64 meson pkg-config

# Runtime libraries (as needed)

brew install freetype gnutls molten-vk sdl2

# Verify bison version (must be ≥ 3.0 and ahead of system bison 2.3)

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

### 3. Environment Configuration

```bash
export PATH="/opt/homebrew/bin:$PATH"
export CC=clang
export CXX=clang++
export MACOSX_DEPLOYMENT_TARGET=10.14
export BUILDROOT="$PWD/build"
export INSTALLROOT="$PWD/install"
```bash

### 4. Verify Setup

```bash

# Check Rosetta 2

pkgutil --pkg-info=com.apple.pkg.RosettaUpdateAuto

# Check Xcode CLT

xcode-select -p

# Check CrossOver version

defaults read /Applications/CrossOver.app/Contents/Info.plist CFBundleShortVersionString

# Should report 26.3

```text

---

## 3. Project Structure and Architecture

### Directory Layout

```python
Endfield_FineWine/
├── .github/
│   ├── scripts/                    # Python automation scripts
│   │   ├── generate-wiki.py
│   │   ├── generate-release-notes.py
│   │   ├── validate-issue-version.py
│   │   ├── update-issue-version-dropdowns.py
│   │   ├── announce-discord-release.py
│   │   └── post-bluesky-thread.py
│   └── workflows/
│       ├── build.yml               # CI build workflow
│       ├── nightly.yml             # Nightly builds
│       └── update-wiki.yml         # Wiki documentation generation
├── finewine-app/                   # FineWine standalone app
│   └── README.md
├── patcher-app/                    # FineWine Patcher GUI (SwiftPM)
│   ├── README.md
│   └── scripts/
│       └── verify-app-payload.py
├── scripts/
│   ├── build-wine.sh               # Wine build orchestrator
│   ├── swap-into-crossover.sh      # Module swap into CrossOver
│   ├── create-bottle.sh            # CrossOver bottle creation
│   ├── launch-endfield.sh          # Game launch helper
│   ├── notproton-register.sh       # NotProton integration
│   ├── lib/
│   │   └── fex-pkg_resources.py
│   └── ...
├── tests/
│   ├── test-msync-waitall.py
│   └── runtime/
│       └── make-icons.py
├── patches/
│   ├── README.md                   # Patch inventory and licensing
│   ├── x64/
│   │   ├── stage1-macos/           # Rosetta 2 fixes
│   │   ├── stage2-dwproton/        # dw-proton ACE patches
│   │   └── moltenvk/
│   └── ARM/
├── docs/
│   ├── installation.md
│   ├── troubleshooting.md
│   ├── technical.md
│   ├── performance.md
│   ├── graphics-performance.md
│   ├── finewine-runtime-format.md
│   └── project-information/        # Engineering write-ups (00-30)
├── CONTRIBUTING.md
└── README.md
```javascript

### FineWine Standalone Architecture

FineWine is a menu bar application that manages Wine prefixes and runs Windows programs:

- **Runtime**: A Wine build plus `runtime.json` describing the build (format version 2)
- **Prefix Management**: Creates, moves, snapshots, and deletes Wine prefixes
- **Program Execution**: Runs installed programs with appropriate environment variables
- **Shortcut Apps**: Creates macOS app bundles in `~/Applications/FineWine`
- **Graphics Backends**: DXMT (default), with configurable MetalFX upscaling, DLSS, MSync, Game Mode

#### Runtime Format (`runtime.json`)

Key fields include `id`, `name`, `version`, `architecture`, `graphics`, `formatVersion` (must be `2`), `root`, `loader`, `server`, `libraryPath`, `environment`, `capabilities`, and `prefixSetup`.

### FineWine Patcher Architecture

The patcher transforms a licensed CrossOver 26.3 into a patched build:

1. **Build**: Compile a minimal 64-bit-only Wine from CrossOver 26.3 source with patches
2. **Swap**: Replace three modules in a copy of CrossOver:
  - `lib/wine/x86_64-unix/ntdll.so` — Rosetta signal fixes + QPC timing
  - `lib/wine/x86_64-windows/kernel32.dll` — `KiUser*Dispatcher` int3 spoof
  - `lib/wine/x86_64-windows/ntoskrnl.exe` — 17 backported NT kernel functions
3. **Re-seal**: Ad-hoc code-sign the bundle with `--preserve-metadata=entitlements`
4. **LC_RPATH**: Add `@loader_path/../../../lib64` to `ntdll.so` for `cxcompatdb.so` dependency

### Patch System

Patches are organized in `patches/`:

- `patches/x64/stage1-macos/` — Novel Rosetta 2 signal handling fixes
- `patches/x64/stage2-dwproton/` — dw-proton ACE anti-cheat patches (em-backports, int3 spoof, QPC timing)
- `patches/x64/stage2-dwproton/ace-core/` — ACE-CORE regression fixes (return address bits, lsass stub, MDL implementations)
- `patches/ARM/` — CrossOver ARM (Wine 11.21) ports
- `patches/moltenvk/` — MoltenVK ray tracing extensions

See `patches/README.md` for the complete inventory and licensing information.

---

## 4. Coding Standards and Guidelines

### Language-Specific Standards

#### Python (`.github/scripts/`, `scripts/lib/`, `tests/`)

- Follow [PEP 8](https://pep8.org/) style guidelines
- Use type hints where practical
- Document functions with docstrings
- Scripts must be executable (`chmod +x`)
- Handle errors gracefully with descriptive messages

#### Shell Scripts (`scripts/`)

- Use `#!/usr/bin/env bash` shebang
- Set `set -euo pipefail` for safety
- Quote all variable expansions
- Use `[[ ]]` for conditionals
- Provide `--help` output for user-facing scripts
- Log to both stdout and `CX_LOG` when applicable

#### Swift (`patcher-app/`)

- Follow Swift API Design Guidelines
- Use Swift Package Manager (SwiftPM)
- Ad-hoc sign with `--preserve-metadata=entitlements`
- Keep GUI logic separate from patching engine (`PatcherEngine.swift`)

#### C (Wine patches in `patches/`)

- Follow Wine coding style
- Use `#ifdef __x86_64__` guards for x86_64-specific code
- Document the purpose of each patch in comments
- Keep patches minimal and focused

### Naming Conventions

| Element | Convention | Example |
|---------|------------|---------|
| Python functions | `snake_case` | `generate_release_notes()` |
| Shell variables | `UPPER_CASE` for exports, `lower_case` for local | `CX_LOG`, `bottle_name` |
| Swift types | `PascalCase` | `PatcherEngine`, `ChainPlan` |
| Swift functions | `camelCase` | `applyModChain()` |
| Patch files | `NNNN-description.patch` | `0001-ntoskrnl-Implement-ACE-CORE.patch` |
| Bottle names | Descriptive, spaces allowed | `Arknights Endfield` |

### Documentation Standards

- All user-facing features must have documentation in `docs/`
- Engineering write-ups in `docs/project-information/` numbered `00`–`30`
- Confidence tags inline: `[confidence: high/medium/low]`
- `⚠️ VERIFIER CAUTION` marks corrected or refuted findings
- macOS-specific unknowns explicitly called out

### Commit Conventions

- Descriptive commit messages explaining *why*, not just *what*
- Reference issue numbers when applicable
- Keep commits atomic (one logical change per commit)
- Do not commit secrets, API keys, or licensed software (CrossOver, GPTK, game files)

### Ethics and Scope Guidelines

- **No anti-cheat bypass**: Patches enable ACE to run, not to evade it
- **No game modification**: No changes to game logic or assets
- **No redistribution**: Do not bundle CrossOver, GPTK, or game files
- **User responsibility**: Clearly document that usage is at the user's own risk and may violate ToS

---

## 5. Build Process

### Building the Patched Wine

The primary build script is `scripts/build-wine.sh`:

```bash

# Full build (deps →

Clone this wiki locally