-
-
Notifications
You must be signed in to change notification settings - Fork 21
automated_deployment
runner edited this page Oct 5, 2026
·
15 revisions
# Required system tools
xcode-select --install # Xcode command line tools
softwareupdate --install-rosetta --agree-to-license # Rosetta 2 for x86_64 Wine
# Package management
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Homebrew
brew update && brew upgrade
# Essential development tools
brew install git cmake make pkg-config bison@3.0 mingw-w64 meson freetype gnutls molten-vk sdl2
```bash
#### CrossOver Development Environment
```bash
# Licensed CrossOver installation (required)
# Download from: https://www.codeweavers.com/crossover
# Must be version 26.3 specifically for Wine ABI compatibility
# Verify installation
ls -la /Applications/CrossOver.app
```bash
### Development Workspace Setup
```bash
# Clone the repository
git clone https://github.com/stoicswe/Endfield_FineWine.git
cd Endfield_FineWine
# Create development directory structure
mkdir -p ~/dev/Endfield_FineWine/{build,scripts,patches,docs,tests}
cd Endfield_FineWine
# Configure environment variables
export ENDFIELD_FINEWINE_ROOT="$PWD"
export WINE_BUILD_PATH="$ENDFIELD_FINEWINE_ROOT/build/wine-build64"
export CROSSOVER_PATH="/Applications/CrossOver.app"
```python
## 2. Coding Standards and Guidelines
### Code Style Guidelines
#### Python Scripts (Scripts Directory)
```python
# PEP 8 compliant with project-specific modifications
import os
import sys
import logging
from pathlib import Path
from typing import Optional, Dict, Any, List
# Configure logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[
logging.FileHandler('~/dev/Endfield_FineWine/logs/debug.log'),
logging.StreamHandler()
]
)
def main() -> None:
"""Main entry point with type hints and documentation."""
try:
# Implementation here
pass
except Exception as e:
logging.error(f"Error in main: {e}")
sys.exit(1)
if __name__ == "__main__":
main()
```bash
#### Shell Scripts (Scripts Directory)
```bash
# !/usr/bin/env bash
# Bash 4+ with strict error handling
set -euo pipefail
IFS=$'\n\t'
# Logging function
log() {
local level="$1"
shift
echo "[$(date '+%Y-%m-%d %H:%M:%S')] [$level] $*" | tee -a "$LOG_FILE"
}
# Error handling
error_exit() {
log "ERROR" "$1"
exit 1
}
# Usage function
usage() {
cat << EOF
Usage: $0 [OPTIONS]
Options:
--help Show this help message
--verbose Enable verbose output
EOF
exit 1
}
```text
### Documentation Standards
#### Markdown Documentation
- Use consistent heading hierarchy (H1, H2, H3)
- Include code blocks with syntax highlighting
- Use tables for structured data
- Include examples and usage notes
- Add cross-references to related documentation
#### Code Comments
```c
/**
- @file signal_x86_64.c
- @brief Rosetta 2 signal handling fixes for Endfield compatibility
-
- This file contains two critical Rosetta 2 bug fixes:
- 1. Multi-byte NOP (0F 1F) exception handling
- 2. Privileged instruction classification for mov cr3
*
- @author Endfield_FineWine Team
- @date 2026-07-14
- @license LGPL-2.1-or-later
*/
/**
- @brief Handle Rosetta 2's erroneous multi-byte NOP exceptions
*
- VMProtect emits hundreds of thousands of 0F 1F NOP instructions.
- Under Rosetta 2, some forms incorrectly raise EXC_BAD_INSTRUCTION,
- triggering Wine\'s SEH exception handling and causing infinite recursion.
*
- @param info Signal information structure
- @param context Signal context
- @return NTSTATUS Status code
*/
static NTSTATUS handle_cet_nop( const EXCEPTION_REGISTRATION_RECORD *info,
CONTEXT *context )
{
// Implementation here
}
```javascript
## 3. Project Structure and Architecture
### Directory Structure
```yaml
Endfield_FineWine/
├── scripts/ # Build and deployment scripts
│ ├── build-wine.sh # Wine build automation
│ ├── swap-into-crossover.sh # Module deployment
│ ├── create-bottle.sh # Bottle configuration
│ ├── launch-endfield.sh # Game launch wrapper
│ └── README.md # Scripts documentation
│
├── patches/ # Wine patches (LGPL-2.1-or-later)
│ ├── stage1-macos/ # Rosetta 2 fixes
│ │ ├── 0001-rosetta-nop-fix.patch
│ │ └── 0002-rosetta-privileged-instr.patch
│ ├── stage2-dwproton/ # dw-proton ACE patches
│ │ ├── 0001-em-backports/
│ │ ├── 0002-misc/
│ │ └── README.md
│ └── README.md
│
├── docs/ # Technical documentation
│ ├── README.md
│ ├── installation.md
│ ├── technical.md
│ ├── graphics-performance.md
│ ├── troubleshooting.md
│ └── performance.md
│
├── patcher-app/ # GUI patcher (MIT License)
│ ├── Sources/
│ │ ├── FineWinePatcher/
│ │ │ ├── PatcherEngine.swift
│ │ │ └── ContentView.swift
│ │ └── FineWinePatcherTests/
│ └── README.md
│
├── mod-injection/ # Mod loading research (MIT License)
│ ├── README.md
│ ├── 01-xxmi-efmi-mod-loading.md
│ ├── 02-wine-dll-loading-and-mod-dlls.md
│ └── ... (additional research docs)
│
└── LICENSE # Project license
```text
### Architecture Overview
#### Core Components
**1. Patched Wine Build**
- Minimal 64-bit-only Wine build
- Surgical module replacement (3 core modules only)
- Rosetta 2 compatibility fixes
- ACE anti-cheat support
**2. Module Swap Architecture**
```c
// Patched modules swapped into CrossOver
// Location: Contents/SharedSupport/CrossOver/lib/wine/
// ntdll.so - Rosetta fixes + QPC timing
x86_64-unix/ntdll.so
// kernel32.dll - KiUser*Dispatcher int3 spoof
x86_64-windows/kernel32.dll
// ntoskrnl.exe - 17 em-backported functions
x86_64-windows/ntoskrnl.exe
```python
**3. Graphics Pipeline**
- DirectX 11 → Metal translation
- D3DMetal backend (GPTK 3.0/4.0)
- Optional DXMT/DXVK backends
- DLSS/MetalFX support
#### Technical Architecture Diagram
```mermaid
flowchart TD
A[Game] --> B[Endfield.exe]
B --> C[Unity IL2CPP Engine]
C --> D[DirectX 11 Mode]
D --> E[CrossOver D3DMetal]
E --> F[Apple D3DMetal Framework]
F --> G[Apple Silicon GPU]
A --> H[ACE Anti-Cheat]
H --> I[ACE-Base64.dll]
I --> J[ACE-Service64.exe]
J --> K[ACE-BASE.sys]
A --> L[VMProtect/TenProtect]
L --> M[EndfieldBase.dll]
M --> N[Rosetta 2 Fixes]
style A fill:#e1f5fe
style B fill:#e1f5fe
style C fill:#e1f5fe
style D fill:#e1f5fe
style E fill:#e1f5fe
style F fill:#e1f5fe
style G fill:#e1f5fe
style H fill:#fff3e0
style I fill:#fff3e0
style J fill:#fff3e0
style K fill:#fff3e0
style L fill:#fff3e0
style M fill:#fff3e0
style N fill:#ffebee
```css
## 4. Testing Procedures
### Testing Strategy
**Note:** The project currently has no unit tests (`Has Tests: False`). Testing focuses on integration and manual verification.
#### Manual Testing Procedures
**1. Build Verification**
```bash
# Verify Wine build
./scripts/build-wine.sh --verify
# Check module swap
./scripts/swap-into-crossover.sh --verify
# Validate bottle configuration
./scripts/create-bottle.sh --validate
```bash
**2. Game Launch Testing**
```bash
# Basic launch test
./scripts/launch-endfield.sh --test
# Debug logging test
DEBUG=1 ./scripts/launch-endfield.sh --capture
# Graphics backend test
GFXARGS="-force-d3d11" ./scripts/launch-endfield.sh --test
```bash
**3. ACE Compatibility Testing**
```bash
# ACE initialization test
./scripts/test-ace.sh --check
# Anti-cheat module loading
./scripts/test-ace.sh --modules
```bash
#### Automated Testing Scripts
**01-capture-failure.sh** - Failure capture and logging
```bash
# !/bin/bash
# Capture failure logs for debugging
# Usage: ./scripts/01-capture-failure.sh [options]
set -euo pipefail
LOG_DIR="$HOME/endfield-debug"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
LOG_PATH="$LOG_DIR/$TIMESTAMP"
mkdir -p "$LOG_PATH"
# Capture CrossOver logs
export CX_LOG="$LOG_PATH/cxlog.txt"
export WINEDEBUG="+seh,+virtual,+process,+module,+loaddll"
# Launch with capture
"$@"
# Generate failure report
./scripts/generate-failure-report.sh "$LOG_PATH"
```bash
**Test Script Template**
```bash
# !/bin/bash
# Test script template for Endfield_FineWine
TEST_NAME="$1"
TEST_SCRIPT="$ENDFIELD_FINEWINE_ROOT/tests/${TEST_NAME}.sh"
if [[ ! -f "$TEST_SCRIPT" ]]; then
echo "Error: Test script $TEST_NAME not found"
exit 1
fi
echo "Running test: $TEST_NAME"
bash "$TEST_SCRIPT"
if [[ $? -eq 0 ]]; then
echo "✓ Test $TEST_NAME passed"
else
echo "✗ Test $TEST_NAME failed"
exit 1
fi
```python
## 5. CI/CD Pipeline
### GitHub Actions Workflow
**build.yml** - Main build pipeline
```yaml
name: Endfield_FineWine Build
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
workflow_dispatch:
jobs:
build-wine:
runs-on: macos-14 # macOS Sonoma (required for CrossOver 27)
strategy:
matrix:
target: [x86_64]
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up environment
run: |
export ENDFIELD_FINEWINE_ROOT="$GITHUB_WORKSPACE"
export MACOSX_DEPLOYMENT_TARGET=10.14
export PATH="$HOME/.local/bin:$PATH"
- name: Install dependencies
run: |
brew update
brew install git cmake make pkg-config bison@3.0 mingw-w64 meson
- name: Build Wine
run: |
./scripts/build-wine.sh all
./scripts/swap-into-crossover.sh
./scripts/create-bottle.sh
- name: Verify build
run: |
./scripts/verify-build.sh
- name: Upload artifacts
uses: actions/upload-artifact@v4
if: always()
with:
name: wine-build-${{ matrix.target }}-${{ github.run_number }}
path: |
build/wine-build64/
CrossOver_Endfield_Patch.app/
retention-days: 7
nightly:
runs-on: macos-14
if: github.event_name == 'schedule'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run nightly tests
run: |
./scripts/nightly-test.sh
- name: Generate reports
run: |
./scripts/generate-nightly-report.sh
```python
**nightly.yml** - Nightly testing pipeline
```yaml
name: Endfield_FineWine Nightly
on:
schedule:
- cron: '0 2 * * *' # Daily at 2 AM UTC
workflow_dispatch:
jobs:
nightly-test:
runs-on: macos-14
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup environment
run: |
export ENDFIELD_FINEWINE_ROOT="$GITHUB_WORKSPACE"
./scripts/setup-nightly.sh
- name: Run comprehensive tests
run: |
./scripts/run-nightly-tests.sh
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: nightly-test-results-${{ github.run_number }}
path: |
test-results/
nightly-reports/
retention-days: 30
```python
**update-wiki.yml** - Documentation update pipeline
```yaml
name: Update Wiki Documentation
on:
push:
branches: [ main ]
workflow_dispatch:
jobs:
update-wiki:
runs-on: macos-14
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Update wiki
run: |
./scripts/generate-wiki.py
./scripts/generate-release-notes.py
- name: Commit and push
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add docs/
git commit -m "Auto-update wiki documentation" || exit 0
git push
```python
### Pipeline Configuration
**cxbottle.conf** - Bottle configuration
```ini
# Bottle configuration for Arknights Endfield
[Bottle Defaults]
Name = Arknights Endfield
Version = Windows 11 64-bit
Graphics = D3DMetal
DLSS = 1
MSync = 1
[EnvironmentVariables]
CX_GRAPHICS_BACKEND = d3dmetal
D3DM_ENABLE_METALFX = 1
WINEMSYNC = 1
ROSETTA_ADVERTISE_AVX = 1
[AppDefaults]
Endfield.exe =
DllOverrides = d3d11=n,b;dxgi=n,b;d3dcompiler_47=n,b
Graphics = D3DMetal
```bash
## 6. Contribution Guidelines
### Contribution Process
#### 1. Fork and Branch
```bash
# Fork the repository
git clone https://github.com/your-username/Endfield_FineWine.git
cd Endfield_FineWine
# Create feature branch
git checkout -b feature/your-feature-name
```bash
#### 2. Development Workflow
```bash
# Create a topic branch for your changes
git branch feature/awesome-fix
# Make your changes
# ... (development work)
# Stage your changes
git add scripts/ patches/ docs/
# Commit with conventional commit message
git commit -m "feat: add awesome feature
Co-authored-by: openhands <openhands@all-hands.dev>"
# Push to your branch
git push origin feature/awesome-fix
```yaml
#### 3. Pull Request Process
```yaml
# Pull Request Template
title: "[FEATURE] Brief description of changes"
description: |
Detailed description of changes and motivation
## What changes?
- List of changes
## Why are these changes needed?
- Context and reasoning
## How does this affect the project?
- Impact assessment
## Testing performed
- List of tests performed
## Related issues
- Closes #123 (if applicable)
labels: "feature, needs-review"
assignees: openhands
```text
### Code Review Standards
#### Review Checklist
- [ ] Code follows project coding standards
- [ ] All changes have appropriate documentation
- [ ] Tests pass (if applicable)
- [ ] No linting errors
- [ ] Security considerations addressed
- [ ] Performance impact evaluated
- [ ] Dependencies updated appropriately
- [ ] License compliance maintained
#### Review Process
```bash
# Request review from maintainer
git checkout main
git pull origin main
git merge feature/awesome-fix
# Create pull request
gh pr create --title "feat: add awesome feature" \
--body "Detailed description..." \
--base main \
--head your-username:feature/awesome-fix
# Add reviewers
gh pr edit --add-reviewer openhands
# Wait for review feedback
# Address comments and push updates
git add .
git commit --amend --no-edit
git push