Skip to content

executive_summary

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

Executive Summary

Project Overview

Endfield_FineWine is a compatibility project that enables Arknights: Endfield to run on Apple Silicon macOS through a custom-patched CrossOver Wine environment. This project solves a previously considered impossible compatibility challenge, as CodeWeavers rated the game "Installs, Will Not Run" on macOS.

Core Problem Solved

The game was blocked by three independent layers:

  1. VMProtect/TenProtect ("tpshell") protector layer (EndfieldBase.dll)
  2. ACE (Anti-Cheat Expert) Anti-Cheat (ACE-Base64.dll, ACE-Service64.exe, kernel driver ACE-BASE.sys)
  3. Graphics translation pipeline (Unity IL2CPP rendering via D3DMetal/DirectX 11)

Key Achievements

✅ Working Components

  • VMProtect/TenProtect protector (EndfieldBase.dll) - fully operational
  • ACE anti-cheat - passes completely (ACE-Base64.dll, ACE-Service64.exe, ACE-BASE.sys)
  • Unity engine - loads and initializes (unityplayer.dll, GameAssembly.dll)
  • Graphics via Apple D3DMetal - renders correctly
  • Login screen - fully functional and playable

⚠️ Known Limitations

  • One residual ACE thread abort on ntoskrnl.exe.PsGetProcessExitStatus (non-fatal)
  • Endfield must run in DirectX 11 mode (default Vulkan/DX12 fails)
  • Requires actively cooled Mac (MacBook Air is off-limits due to thermal constraints)

Technical Architecture

Two Novel Rosetta 2 Bug Fixes

  1. NOP Exception Handling: Rosetta 2 incorrectly faults on multi-byte 0F 1F NOP instructions emitted by VMProtect. Fixed by decoding and skipping these instructions in dlls/ntdll/unix/signal_x86_64.c.

  2. Privileged Instruction Classification: Rosetta misclassifies privileged mov rbx, cr3 as invalid opcode instead of general protection fault. Fixed by calling Wine's is_privileged_instr() before defaulting to EXCEPTION_ILLEGAL_INSTRUCTION.

Anti-Cheat Port (from dw-proton)

  • 17 ntoskrnl.exe kernel backports for ACE driver communication
  • KiUser*Dispatcher int3 spoof in kernel32.dll to defeat tpshell dispatcher probes
  • NtDelayExecution QPC timing in ntdll.so for ACE timing checks

Surgical Module Swap Architecture

Only three core modules are swapped into CrossOver:

  • ntdll.so - Rosetta fixes + QPC timing
  • kernel32.dll - int3 dispatcher spoof
  • ntoskrnl.exe - 17 kernel backports

All other libraries remain stock CodeWeavers binaries, preserving licensing and compatibility.

Current Status

✅ Verified Platforms

  • Apple M4 Pro (24 GB, macOS 27.0, CrossOver 26.3) - ~60 FPS on Medium
  • Apple M3 (macOS 26.5) - working
  • Apple M4 (16 GB) - playable, memory-limited

⚠️ Platform Restrictions

  • Apple Silicon only (Intel not supported)
  • macOS 15+ (Sequoia or newer)
  • Actively cooled Macs required (MacBook Air off-limits)
  • CrossOver 26.3 specifically (Wine 11.0 ABI match required)

Performance Characteristics

Bottleneck Analysis

Gameplay performance is overwhelmingly CPU and RAM bound, not GPU:

  • Rosetta 2 JIT overhead - every x86_64 instruction block translated to ARM64
  • Unity IL2CPP single-threaded render dispatch - main thread heavily utilized
  • Unified memory pressure - 5-6 GB GPU allocations compete with system RAM

Optimization Tips

  1. Close background applications before launching
  2. Use DirectX 11 mode (-force-d3d11) for best performance
  3. Set in-game resolution to 1080p or use 70-80% render scale
  4. Enable MSync in CrossOver bottle settings
  5. Use DLSS/MetalFX for frame generation when available

Technical Details

Graphics Backend Selection

  • D3DMetal (recommended) - DirectX 11/12 → Metal translation
  • DXMT - DirectX 11 → Metal implementation
  • DXVK - DirectX 11 → Vulkan → MoltenVK (experimental)
  • Vulkan - experimental, requires newer MoltenVK than CrossOver ships

Build Requirements

# Dependencies

brew install bison mingw-w64 meson pkg-config

# Build steps

./scripts/build-wine.sh all          # Build patched Wine
./scripts/swap-into-crossover.sh     # Deploy into CrossOver copy
./scripts/create-bottle.sh           # Create "Arknights Endfield" bottle
```text

## Integration with XXMI/EFMI Modding

### Current Status

The project does **not** include XXMI/EFMI mod-loading support. This is a separate research area documented in `mod-injection/`:

- **EFMI** (Endfield Modding Interface) is a 3DMigoto-based modding framework
- **XXMI Launcher** provides the injection infrastructure
- **Current focus** is on getting the base game to launch, not modding support

### Future Considerations

Modding integration would require:
1. **Chain-loading support** for 3DMigoto to work with CrossOver\'s D3DMetal backend
2. **DLL injection compatibility** with CrossOver\'s process model
3. **Graphics backend coordination** between mods and D3DMetal

## Licensing and Ethics

### License Information

- **Scripts and documentation**: MIT License
- **Patches**: LGPL-2.1-or-later (modifications to Wine)
- **CrossOver, Wine, GPTK, game**: User-provided under their respective licenses

### Ethical Considerations

- **No in-game advantages** or modified game logic
- **No DRM circumvention** - this is compatibility work
- **Risk is user\'s responsibility** - running in unsupported configurations may violate ToS
- **Not affiliated** with Gryphline/Hypergryph, Tencent, CodeWeavers, or Apple

## Future Roadmap

### Immediate Goals

1. **Upstream Rosetta fixes** to CodeWeavers
2. **Add `PsGetProcessExitStatus` stub** to eliminate residual ACE abort
3. **Play-test past login** (combat/rendering stability)

### Long-term Considerations

1. **Native arm64 CrossOver compatibility** - current fix only works under Rosetta 2
2. **Modding integration** - XXMI/EFMI support
3. **GPTK4 integration** - Apple\'s newer Game Porting Toolkit 4

## References

### Key Sources

- **dw-proton** - Linux ACE patches that formed the basis for this port
- **CodeWeavers CrossOver** - Foundation for compatibility layer
- **Apple Game Porting Toolkit** - D3DMetal graphics backend
- **Khronos MoltenVK** - Vulkan-on-Metal layer
- **WineHQ Bug 45083** - Prior art for Rosetta VMProtect problem

### Documentation Resources

- [Installation Guide](installation.md) - Step-by-step setup instructions
- [Graphics Performance](graphics-performance.md) - Backend selection and optimization
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
- [Technical Architecture](technical.md) - Deep dive into implementation details

## Conclusion

Endfield_FineWine represents a significant achievement in macOS compatibility engineering. By combining novel Rosetta 2 bug fixes, anti-cheat patch ports, and surgical module replacement, the project successfully enables Arknights: Endfield to run on Apple Silicon macOS where it was previously considered impossible.

The solution maintains ethical compatibility standards, provides clear documentation, and establishes a foundation for future improvements including native arm64 support and modding integration.

Clone this wiki locally