Repository navigation
running_tests
runner edited this page Oct 16, 2026
·
9 revisions
Endfield_FineWine is a compatibility project that enables Arknights: Endfield to run on Apple Silicon macOS through a custom-patched CrossOver Wine. This project addresses three main challenges:
-
VMProtect/TenProtect ("tpshell") protector layer (
EndfieldBase.dll) -
ACE (Anti-Cheat Expert) Anti-Cheat (
ACE-Base64.dll,ACE-Service64.exe,ACE-BASE.sys) - Graphics translation pipeline (Unity IL2CPP rendering via D3DMetal/DX11)
The project combines novel Rosetta 2 bug fixes, ports of dw-proton anti-cheat patches, surgical module replacement, and dynamic linker corrections to achieve near-native macOS gaming performance.
# macOS
macOS 15 (Sequoia) or newer — tested on 27.0 / 26.5
Apple Silicon (M-series) — Intel not supported
Rosetta 2 required: softwareupdate --install-rosetta --agree-to-license
# CrossOver
CrossOver 26.3 (licensed) — from codeweavers.com
Must match Wine 11.0 ABI exactly
# Development Tools
Xcode Command Line Tools: xcode-select --install
Homebrew: brew.sh
```bash
### Prerequisites
```bash
# Install Homebrew dependencies
brew install bison mingw-w64 meson pkg-config freetype gnutls molten-vk sdl2
# Ensure bison is ahead of system version
which bison # Should point to /opt/homebrew/bin/bison (or similar)
```bash
### Cloning and Initial Setup
```bash
git clone <your-fork-url> Endfield_FineWine && cd Endfield_FineWine
```bash
## Coding Standards and Guidelines
### Language Standards
- **Primary Language**: Shell scripting (`bash`)
- **Build System**: Custom scripts with consistent error handling
- **Documentation**: Markdown with structured hierarchy
### Code Style
```bash
# Scripts follow POSIX sh where possible
# !/bin/bash
# Consistent error handling
set -euo pipefail
# Logging with timestamps
log() {
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >&2
}
# Verbose mode for debugging
verbose() {
if [[ "${DEBUG:-0}" == "1" ]]; then
echo "[VERBOSE] $*" >&2
fi
}
```bash
### File Organization
```text
Endfield_FineWine/
├── scripts/ # Core build/deployment scripts
│ ├── build-wine.sh
│ ├── swap-into-crossover.sh
│ ├── create-bottle.sh
│ └── launch-endfield.sh
├── patches/ # Wine patches (LGPL-2.1-or-later)
│ ├── stage1-macos/ # Rosetta fixes
│ └── stage2-dwproton/ # dw-proton ACE patches
├── docs/ # Documentation
├── .github/ # CI/CD workflows
└── LICENSE
```text
## Project Structure and Architecture
### Core Components
#### 1. Patched Wine Build
- **Minimal 64-bit-only Wine** with surgical module replacement
- **Three core modules swapped** into CrossOver:
- `ntdll.so` - Rosetta 2 signal handling fixes + QPC timing
- `kernel32.dll` - `KiUser*Dispatcher` int3 spoof
- `ntoskrnl.exe` - 17 backported NT kernel functions
#### 2. Anti-Cheat Architecture
```javascript
Endfield.exe (Unity IL2CPP)
├── Protector Armor (VMProtect/TenProtect)
│ ├── Rosetta Fix 1: Decode & skip NOP faults (0F 1F multi-byte)
│ └── Rosetta Fix 2: Deliver EXCEPTION_PRIV_INSTRUCTION (mov cr3)
├── ACE Anti-Cheat
│ ├── kernel32.dll int3 dispatcher spoof
│ ├── ntdll.so NtDelayExecution QPC timing
│ └── ntoskrnl.exe 17 backported functions
└── Graphics Translation
├── DXMT (-force-d3d11) → Metal
├── D3DMetal (GPTK4) → Metal
└── DXVK → MoltenVK (experimental)
```javascript
#### 3. Graphics Backend Options
| Backend | Flag | Performance | Mod Support | Notes |
|---------|------|-------------|-------------|-------|
| **DXMT** | `-force-d3d11` | ⭐ Best | ✅ Full | Recommended |
| **D3DMetal** | `-force-metal` | 🔶 Good | ✅ Full | GPTK4 optional |
| **DXVK** | `-force-d3d11` | 🔴 Slow | ❌ Fails | Experimental |
### Key Technical Innovations
#### Rosetta 2 Bug Fixes
1. **NOP Exception Handling**: Multi-byte `0F 1F` NOPs cause illegal instruction faults under Rosetta 2
2. **Privileged Instruction Classification**: `mov rbx, cr3` generates invalid opcode instead of #GP
#### Surgical Module Swap Architecture
- **Minimal build**: Only 3 Wine modules swapped, preserving CrossOver's proprietary components
- **RPATH injection**: `@loader_path/../../../lib64` rpath in `ntdll.so` for D3DMetal initialization
- **Ad-hoc signing**: Re-sealing the entire CrossOver bundle after module replacement
## Testing Procedures
### Test Suite Structure
```bash
# Core test script
./scripts/01-capture-failure.sh [options]
# Options
DEBUG=light # Wine errors only (cheap)
DEBUG=1 # Full CrossOver log (heavy)
WINEDEBUG=+ntoskrnl,+module,+seh # Specific channels
```bash
### Test Categories
#### 1. Unit Tests (Script Testing)
```bash
# Test individual scripts
./scripts/build-wine.sh deps # Dependencies
./scripts/build-wine.sh fetch # Source download
./scripts/build-wine.sh apply # Patch application
./scripts/build-wine.sh configure # Configuration
./scripts/build-wine.sh build # Build
```python
#### 2. Integration Tests
```bash
# Full pipeline test
./scripts/build-wine.sh all # Complete build
./scripts/swap-into-crossover.sh # Module deployment
./scripts/create-bottle.sh # Bottle creation
./scripts/launch-endfield.sh # Game launch
```bash
#### 3. Hardware Validation
```bash
# Performance measurement
./scripts/measure-performance.sh
# Memory usage tracking
top -l 1 -o mem -n 10 -stats command,mem
# GPU utilization
ioreg -r -d 1 -w 0 -c IOAccelerator | grep -o '"(Device Utilization %|In use system memory)"=[0-9]*'
```python
### Test Coverage
- **Build verification**: Clean compilation, patch application, module swapping
- **Functional testing**: Game launch, ACE bypass, graphics rendering
- **Performance testing**: FPS measurement, memory usage, thermal behavior
- **Compatibility testing**: Different macOS versions, CrossOver versions, hardware variants
## CI/CD Pipeline
### Workflow Overview
```yaml
# .github/workflows/build.yml
name: Build
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: macos-latest
strategy:
matrix:
include:
- name: "M4 Pro (24GB)"
runner: self-hosted
arch: arm64
- name: "M3 (16GB)"
runner: self-hosted
arch: arm64
steps:
- uses: actions/checkout@v3
- name: Setup Environment
run: |
softwareupdate --install-rosetta --agree-to-license
brew install bison mingw-w64 meson pkg-config
- name: Build Wine
run: ./scripts/build-wine.sh all
- name: Deploy to CrossOver
run: ./scripts/swap-into-crossover.sh
- name: Create Bottle
run: ./scripts/create-bottle.sh
- name: Run Tests
run: |
./scripts/launch-endfield.sh --test
./scripts/measure-performance.sh
```yaml
### CI/CD Features
#### 1. Multi-Platform Testing
```yaml
strategy:
matrix:
include:
# macOS versions
- os: macos-13
xcode: 14.2
- os: macos-14
xcode: 15.0
- os: macos-15
xcode: 16.0
# Hardware variants
- arch: arm64
chip: "M4 Pro"
memory: "24GB"
- arch: arm64
chip: "M3"
memory: "16GB"
```yaml
#### 2. Nightly Builds
```yaml
# .github/workflows/nightly.yml
name: Nightly
on:
schedule:
- cron: '0 2 * * *' # 2 AM UTC
workflow_dispatch:
jobs:
nightly-build:
runs-on: macos-latest
steps:
- uses: actions/checkout@v3
- name: Build Nightly
run: |
./scripts/build-wine.sh all
./scripts/swap-into-crossover.sh
./scripts/create-bottle.sh
- name: Upload Artifacts
uses: actions/upload-artifact@v3
with:
name: nightly-build
path: |
build/
CrossOver_Endfield_Patch.app/
```yaml
#### 3. Wiki Documentation Generation
```yaml
# .github/workflows/update-wiki.yml
name: Generate Wiki Documentation
on:
push:
branches: [main]
paths: ['docs/', 'scripts/']
jobs:
generate-wiki:
runs-on: macos-latest
steps:
- uses: actions/checkout@v3
- name: Generate Documentation
run: ./scripts/generate-wiki.py
- name: Commit to Wiki
uses: actions/GhActions-Wiki@actions/upload-wiki@v1
with:
path: docs/
```bash
## Contribution Guidelines
### Branch Strategy
```bash
# Main development branch
git checkout main
# Feature branches
git checkout -b feature/your-feature
# Hotfix branches
git checkout -b hotfix/critical-bug
# Release branches
git checkout -b release/v1.2.3
```bash
### Commit Conventions
```bash
# Feature commits
git add scripts/ docs/ patches/
git commit -m "feat: add mod-chain support to patcher tools
- Implement optional mod-chain phase in swap-into-crossover.sh
- Add ModChain.swift class to patcher-app
- Add comprehensive tests for chain application/reversion
- Closes #123"
# Fix commits
git commit -m "fix: resolve Rosetta NOP exception handling
- Add 0F 1F multi-byte NOP skip in signal_x86_64.c
- Fixes EndfieldBase.dll protector fault on macOS
- Closes #45"
# Documentation commits
git commit -m "docs: update installation guide with GPTK4 steps
- Add detailed GPTK4 installation instructions
- Document macOS 27-specific requirements
- Closes #67"
```text
### Pull Request Process
1. **Pre-requisites**
- All tests passing
- Code reviewed and approved
- Documentation updated
- License headers present
2. **Review Checklist**
```markdown
- [ ] Code follows project conventions
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] No breaking changes
- [ ] License compliance
- [ ] Security considerations addressed
```bash
3. **Merge Process**
```bash
# Rebase onto main
git checkout main
git pull origin main
git merge --squash feature/your-feature
git commit -m "Merge feature branch into main"
# Push to remote
git push origin main
```text
## Debugging and Troubleshooting
### Common Issues and Solutions
#### 1. "CrossOver.app is version X, expected 26.3"
**Problem**: Module swap requires matching Wine ABI
**Solution**:
```bash
# Verify CrossOver version
defaults read /Applications/CrossOver.app/Contents/Info CFBundleShortVersionString
# Install correct version if needed
brew install --cask crossover # or download from codeweavers.com
```bash
#### 2. "CrossOver_Endfield_Patch is damaged and can't be opened"
**Problem**: Broken signature seal
**Solution**:
```bash
# Re-seal the bundle
codesign --force --sign - --preserve-metadata=entitlements /Applications/CrossOver_Endfield_Patch.app
# Verify signature
codesign --verify --deep --strict /Applications/CrossOver_Endfield_Patch.app
```bash
#### 3. ACE "driver error 13"
**Problem**: ACE initialization failure
**Solution**:
```bash
# Verify patched modules are loaded
WINEDEBUG=+ntoskrnl,+module,+loaddll ./scripts/launch-endfield.sh
# Check for import warnings
grep "unimplemented function ntoskrnl.exe" ~/endfield-debug/*/cxlog.txt
```python
### Debugging Scripts
#### Debug Logging
```bash
# Lightweight debugging (errors only)
DEBUG=light ./scripts/launch-endfield.sh
# Full debugging (all channels)
DEBUG=1 ./scripts/launch-endfield.sh
# Specific channels
WINEDEBUG=+ntoskrnl,+module,+seh,+process ./scripts/launch-endfield.sh
```bash
#### Failure Capture
```bash
# Comprehensive failure capture
./scripts/01-capture-failure.sh --full --channels "+ntoskrnl,+module,+seh,+relay"
# Quick capture
./scripts/01-capture-failure.sh --quick
```javascript
#### Performance Monitoring
```bash
# System resource monitoring
./scripts/measure-performance.sh --continuous --output perf_data.json
# Memory pressure tracking
while true; do
memory_pressure | tail -1
sleep 5
done
```bash
## Build and Release Processes
### Build Process
#### 1. Local Build
```bash
# Complete build pipeline
./scripts/build-wine.sh all
# Step-by-step build
./scripts/build-wine.sh deps # Dependencies
./scripts/build-wine.sh fetch # Source download
./scripts/build-wine.sh apply # Patch application
./scripts/build-wine.sh configure # Configuration
./scripts/build-wine.sh build # Build
```bash
#### 2. CrossOver Integration
```bash
# Deploy to CrossOver
./scripts/swap-into-crossover.sh
# With GPTK4 (optional)
GPTK_DIR="/Volumes/GPTK4/redist/lib/external" ./scripts/swap-into-crossover.sh
# With custom backend
BACKEND=dxmt CX_GRAPHICS_BACKEND=dxmt ./scripts/swap-into-crossover.sh
```bash
#### 3. Bottle Creation
```bash
# Standard bottle
./scripts/create-bottle.sh
# With custom settings
MSYNC=0 BACKEND=d3dmetal UPDATE=1 ./scripts/create-bottle.sh
# For testing
./scripts/create-bottle.sh --scratch --test
```bash
### Release Process
#### 1. Pre-Release Checklist
```bash
# Verify build artifacts
./scripts/verify-build.sh
# Run full test suite
./scripts/run-tests.sh --full
# Check documentation
./scripts/generate-wiki.py --validate
# Verify licensing
./scripts/check-licensing.sh
```bash
#### 2. Release Creation
```bash
# Create release branch
git checkout -b release/v1.2.3
# Update version in scripts
sed -i '' 's/VERSION = "1.2.2"/VERSION = "1.2.3"/g' scripts/build-wine.sh
# Build release artifacts
./scripts/build-wine.sh all
./scripts/swap-into-crossover.sh
./scripts/create-bottle.sh
# Create GitHub release
gh release create v1.2.3 \
--title "Version 1.2.3" \
--notes-file CHANGELOG.md \
build/ \
CrossOver_Endfield_Patch.app/ \
Arknights_Endfield.app.zip
```bash
#### 3. Post-Release
```bash
# Update changelog
./scripts/update-changelog.sh
# Push to remote
git push origin release/v1.2.3
git checkout main
git merge --squash release/v1.2.3
git commit -m "Merge release v1.2.3 into main"
git push origin main
# Clean up release branch
git branch -d release/v1.2.3
```bash
## Code Review Procedures
### Review Process
#### 1. Initial Review
```bash
# Check for obvious issues
git diff --check HEAD~1 HEAD
# Run linting
./scripts/lint-code.sh
# Run tests
./scripts/run-tests.sh --quick
```bash
#### 2. Detailed Review
```bash
# Review changes
git diff HEAD~1 HEAD --stat
# Review specific files
git diff HEAD~1 HEAD -- scripts/build-wine.sh
git diff HEAD~1 HEAD -- patches/stage1-macos/
git diff HEAD~1 HEAD -- docs/
```javascript
#### 3. Approval Criteria
```markdown
## Code Review Checklist
### Functionality
- [ ] All existing tests pass
- [ ] New functionality tested
- [ ] Edge cases covered
- [ ] Performance impact assessed
### Code Quality
- [ ] Follows project conventions
- [ ] No linting errors
- [ ] Appropriate comments and documentation
- [ ] Consistent error handling
### Security
- [ ] No sensitive data exposure
- [ ] Input validation present
- [ ] Dependencies vetted
- [ ] License compliance
### Documentation
- [ ] Code documented
- [ ] User guides updated
- [ ] API documentation complete
```bash
### Merge Approval
```bash
# Request review