Repository navigation
contributing
runner edited this page Nov 20, 2026
·
55 revisions
- Overview
- Development Environment Setup
- Project Structure and Architecture
- Coding Standards and Guidelines
- Build Process
- Testing Procedures
- CI/CD Pipeline
- Debugging and Troubleshooting
- Release Process
- Contribution Guidelines
- Code Review Procedures
- Development Tools and Links
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 |
- 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
-
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
win32on64or custom Clang -
Rosetta 2 signal fixes: Two novel fixes in
dlls/ntdll/unix/signal_x86_64.cfor multi-byte NOP handling and privileged instruction classification -
ACE anti-cheat port: Ported from Linux dw-proton, including
ntoskrnl.exebackports,KiUser*Dispatcherint3 spoof, andNtDelayExecutionQPC 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.
| 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 | — |
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 →