feat: macOS port tooling — clang-cl cross-build + Wine/DXVK/MoltenVK runtime

- build-macos.sh: cross-compiles the Windows x64 client on Apple Silicon
  (LLVM clang-cl/lld-link + xwin Windows SDK, fxc via Wine with native
  d3dcompiler DLLs)
- run-client.sh: dedicated Wine prefix with DXVK-macOS (D3D11->Vulkan) on
  MoltenVK (Vulkan->Metal)
- tools/: in-Wine input injectors for automated verification
This commit is contained in:
2026-07-07 03:09:00 -05:00
commit f9b5e53d30
6 changed files with 324 additions and 0 deletions

19
.gitignore vendored Normal file
View File

@@ -0,0 +1,19 @@
# downloaded artifacts (fetched by build-macos.sh / documented in README)
7zip/
dx/
ffx/
ffx32/
dxvk/
firefox.exe
firefox32.exe
firefox.7z
dxredist.exe
sdktools.nupkg
7z.tar.xz
# build outputs
*.exe
*.obj
*.pdb
screenshots/
proof*.png

66
README.md Normal file
View File

@@ -0,0 +1,66 @@
# neoLegacy-mac
Runs the [neoLegacy](https://git.neolegacy.dev/coah80/neoLegacy) Minecraft Legacy
Console Edition client on macOS (Apple Silicon), rendering through
**D3D11 → DXVK (Vulkan) → MoltenVK → Metal**.
The upstream repo stays untouched — this repo holds the build/run tooling and
the patches that make the port work.
## How it works
The game is Windows-native and depends on closed middleware (Iggy flash UI),
so the binary itself stays a Windows x64 PE:
1. **Build**: `build-macos.sh` cross-compiles the client on macOS with
`clang-cl` + `lld-link` (LLVM release toolchain) against the Windows SDK
fetched by [xwin](https://github.com/Jake-Shadle/xwin). HLSL shaders are
compiled by the repo's `fxc.exe` running under Wine with native
`d3dcompiler_43/47` + `d3dx9_43` DLLs.
2. **Run**: `run-client.sh` launches the exe under Wine (Gcenx
wine-crossover build) with
[DXVK-macOS](https://github.com/Gcenx/DXVK-macOS) translating D3D11 to
Vulkan and MoltenVK translating Vulkan to Metal.
## Prerequisites
- Apple Silicon Mac with Rosetta 2 (`softwareupdate --install-rosetta`)
- [Wine Crossover](https://github.com/Gcenx/homebrew-wine) (`brew install --cask wine-crossover`)
- cmake + ninja + rsync
- LLVM release tarball (with `lld-link`) at `~/.local/llvm22` — see `LLVM_DIR` in `build-macos.sh`
- `cargo install xwin`
- DXVK-macOS extracted into `dxvk/` (see `run-client.sh`)
- Native `d3dcompiler_47.dll` (32+64-bit), `d3dcompiler_43.dll`, `d3dx9_43.dll`
in the Wine prefix (fetched from Firefox installers / DirectX Jun2010 redist;
see notes in `run-client.sh`)
## Usage
```bash
git clone https://git.neolegacy.dev/coah80/neoLegacy.git ~/neoLegacy
cd ~/neoLegacy && git submodule update --init --recursive
./build-macos.sh # cross-compile Release client
./run-client.sh # launch under Wine + DXVK + MoltenVK
```
## Tools
- `tools/send_f2.c` / `tools/send_key.c` — tiny Windows helpers, compiled with
the same clang-cl toolchain, that focus the game window *inside* Wine and
inject keys (F2 = the game's built-in screenshot). Used for automated
testing without macOS accessibility permissions.
## Upstream patches carried locally
- `Minecraft.Client/Common/UI/UIController.cpp:671` — upstream commit
`47e5cba3`'s parent (`b5707e88`) committed literal git conflict markers,
which clang rejects. Resolved to a single `skinHDWin.swf` fallback under the
`platformskinHD.swf` import name.
## Status
- [x] Client builds on macOS (clang-cl cross-compile, ~1456 build steps)
- [x] Runs and is playable: menus, worldgen, HUD, chat, death/respawn verified
- [x] Audio is pure OGG on this platform (miniaudio + stb_vorbis; Bink Audio
only ever existed for the console targets, which aren't built)
- [ ] SWF/Iggy UI replaced with PNG-based UI (in progress)

125
build-macos.sh Executable file
View File

@@ -0,0 +1,125 @@
#!/usr/bin/env bash
# neoLegacy macOS build — cross-compiles the Windows x64 client with clang-cl
# and runs it under Wine with DXVK (D3D11 -> Vulkan) on MoltenVK (Vulkan -> Metal).
#
# This script lives OUTSIDE the neoLegacy clone on purpose: the upstream repo
# stays untouched apart from an untracked build/ directory.
set -euo pipefail
SOURCE_DIR="${SOURCE_DIR:-$HOME/neoLegacy}"
BUILD_TYPE="${BUILD_TYPE:-${1:-Release}}"
XWIN_CACHE="${XWIN_CACHE:-$HOME/.cache/neolegacy-xwin}"
INSTALL_DIR="${INSTALL_PREFIX:-$HOME/.local/share/neoLegacy-mac}"
# Toolchain: LLVM release build (has lld-link, clang-cl, llvm-rc, llvm-ml, llvm-lib, llvm-mt)
LLVM_DIR="${LLVM_DIR:-$HOME/.local/llvm22/LLVM-22.1.8-macOS-ARM64}"
export PATH="$LLVM_DIR/bin:$HOME/.cargo/bin:/opt/homebrew/bin:$PATH"
RED='\033[0;31m'; GREEN='\033[0;32m'; CYAN='\033[0;36m'; NC='\033[0m'
info() { echo -e "${CYAN}[info]${NC} $*"; }
success() { echo -e "${GREEN}[ok]${NC} $*"; }
die() { echo -e "${RED}[error]${NC} $*" >&2; exit 1; }
check_deps() {
local missing=()
for dep in clang-cl lld-link llvm-rc llvm-ml llvm-lib llvm-mt cmake ninja xwin rsync wine; do
command -v "$dep" &>/dev/null || missing+=("$dep")
done
[[ ${#missing[@]} -eq 0 ]] || die "Missing dependencies: ${missing[*]}"
arch -x86_64 /usr/bin/true 2>/dev/null || die "Rosetta 2 is required (softwareupdate --install-rosetta)"
success "All dependencies found"
}
fetch_winsdk() {
local splat_dir="$XWIN_CACHE/splat"
if [[ -d "$splat_dir" ]]; then
info "Using cached Windows SDK at $splat_dir"
return
fi
info "Downloading Windows SDK and CRT via xwin..."
mkdir -p "$XWIN_CACHE"
xwin --accept-license splat --output "$splat_dir"
success "Windows SDK downloaded"
}
write_toolchain() {
local toolchain_file="$BUILD_DIR/clang-cl-toolchain.cmake"
cat > "$toolchain_file" <<CMAKE
set(CMAKE_SYSTEM_NAME Windows)
set(CMAKE_SYSTEM_PROCESSOR AMD64)
set(CMAKE_C_COMPILER $LLVM_DIR/bin/clang-cl)
set(CMAKE_CXX_COMPILER $LLVM_DIR/bin/clang-cl)
set(CMAKE_RC_COMPILER $LLVM_DIR/bin/llvm-rc)
set(CMAKE_ASM_MASM_COMPILER $LLVM_DIR/bin/llvm-ml)
set(CMAKE_AR $LLVM_DIR/bin/llvm-lib)
set(CMAKE_LINKER $LLVM_DIR/bin/lld-link)
set(CMAKE_CROSSCOMPILING TRUE)
set(CMAKE_C_LINK_EXECUTABLE "<CMAKE_LINKER> <LINK_FLAGS> <OBJECTS> -out:<TARGET> <LINK_LIBRARIES>")
set(CMAKE_CXX_LINK_EXECUTABLE "<CMAKE_LINKER> <LINK_FLAGS> <OBJECTS> -out:<TARGET> <LINK_LIBRARIES>")
add_compile_options(-fms-compatibility -fms-extensions)
add_compile_definitions(_WIN64 _AMD64_ WIN32_LEAN_AND_MEAN)
CMAKE
echo "$toolchain_file"
}
do_cmake_configure() {
local winsdk="$XWIN_CACHE/splat"
local toolchain
toolchain="$(write_toolchain)"
local c_flags="/MT -w -Wno-non-pod-varargs -fms-compatibility -fms-extensions --target=x86_64-pc-windows-msvc \
-imsvc $winsdk/crt/include \
-imsvc $winsdk/sdk/include/ucrt \
-imsvc $winsdk/sdk/include/um \
-imsvc $winsdk/sdk/include/shared"
local linker_flags="\
-libpath:$winsdk/crt/lib/x86_64 \
-libpath:$winsdk/sdk/lib/um/x86_64 \
-libpath:$winsdk/sdk/lib/ucrt/x86_64"
info "Configuring with CMake ($BUILD_TYPE)..."
cmake -S "$SOURCE_DIR" -B "$BUILD_DIR" \
-G Ninja \
-DCMAKE_BUILD_TYPE="$BUILD_TYPE" \
-DCMAKE_TOOLCHAIN_FILE="$toolchain" \
-DCMAKE_C_COMPILER="$LLVM_DIR/bin/clang-cl" \
-DCMAKE_CXX_COMPILER="$LLVM_DIR/bin/clang-cl" \
-DCMAKE_LINKER="$LLVM_DIR/bin/lld-link" \
-DCMAKE_RC_COMPILER="$LLVM_DIR/bin/llvm-rc" \
-DCMAKE_MT="$LLVM_DIR/bin/llvm-mt" \
-DPLATFORM_DEFINES="_WINDOWS64" \
-DPLATFORM_NAME="Windows64" \
-DIGGY_LIBS="iggy_w64.lib;iggyperfmon_w64.lib;iggyexpruntime_w64.lib" \
-DCMAKE_SYSTEM_NAME=Windows \
-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded \
-DCMAKE_C_FLAGS="$c_flags" \
-DCMAKE_CXX_FLAGS="$c_flags" \
-DCMAKE_ASM_MASM_FLAGS="-m64" \
-DCMAKE_EXE_LINKER_FLAGS="$linker_flags" \
-DCMAKE_RC_FLAGS="/I $winsdk/sdk/include/shared /I $winsdk/sdk/include/um /I $winsdk/sdk/include/ucrt"
success "CMake configuration done"
}
do_build() {
local cores
cores="$(sysctl -n hw.ncpu)"
info "Building with ${cores} cores..."
cmake --build "$BUILD_DIR" --config "$BUILD_TYPE" -j "$cores" --target Minecraft.Client
success "Build complete"
}
main() {
BUILD_DIR="$SOURCE_DIR/build/windows64-clang-mac"
mkdir -p "$BUILD_DIR"
info "neoLegacy macOS cross-build"
info "Source: $SOURCE_DIR | Type: $BUILD_TYPE"
check_deps
fetch_winsdk
do_cmake_configure
do_build
success "Client at: $BUILD_DIR/Minecraft.Client/Minecraft.Client.exe"
}
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
main "$@"
fi

35
run-client.sh Executable file
View File

@@ -0,0 +1,35 @@
#!/usr/bin/env bash
# Launch the neoLegacy client on macOS: Wine + DXVK (D3D11->Vulkan) + MoltenVK (Vulkan->Metal).
set -euo pipefail
GAME_DIR="${GAME_DIR:-$HOME/neoLegacy/build/windows64-clang-mac/Minecraft.Client}"
export WINEPREFIX="${WINEPREFIX:-$HOME/.local/share/neolegacy-wine}"
export WINEDEBUG="${WINEDEBUG:--all}"
DXVK_DIR="$HOME/neoLegacy-mac/dxvk/dxvk-macOS-async-v1.10.3-20230507-repack/x64"
[[ -f "$GAME_DIR/Minecraft.Client.exe" ]] || { echo "client exe not found in $GAME_DIR" >&2; exit 1; }
# One-time prefix setup: create prefix, install DXVK + shader-compiler natives.
if [[ ! -f "$WINEPREFIX/.neolegacy-setup-done" ]]; then
mkdir -p "$WINEPREFIX"
wineboot -u
sys32="$WINEPREFIX/drive_c/windows/system32"
syswow="$WINEPREFIX/drive_c/windows/syswow64"
cp "$DXVK_DIR/d3d11.dll" "$DXVK_DIR/d3d10core.dll" "$sys32/"
# Native HLSL compiler chain (only needed if anything compiles shaders at runtime)
cp "$HOME/neoLegacy-mac/ffx/d3dcompiler_47.dll" "$sys32/" 2>/dev/null || true
cp "$HOME/neoLegacy-mac/ffx32/d3dcompiler_47.dll" "$syswow/" 2>/dev/null || true
cp "$HOME/neoLegacy-mac/dx/x64/d3dx9_43.dll" "$sys32/" 2>/dev/null || true
cp "$HOME/neoLegacy-mac/dx/x86/d3dx9_43.dll" "$syswow/" 2>/dev/null || true
cp "$HOME/neoLegacy-mac/dx/x64/d3dcompiler_43.dll" "$sys32/" 2>/dev/null || true
cp "$HOME/neoLegacy-mac/dx/x86/D3DCompiler_43.dll" "$syswow/d3dcompiler_43.dll" 2>/dev/null || true
wine reg add 'HKCU\Software\Wine\DllOverrides' /v d3d11 /d native /f
wine reg add 'HKCU\Software\Wine\DllOverrides' /v d3d10core /d native /f
wine reg add 'HKCU\Software\Wine\DllOverrides' /v d3dcompiler_47 /d native /f
wine reg add 'HKCU\Software\Wine\DllOverrides' /v d3dcompiler_43 /d native /f
wine reg add 'HKCU\Software\Wine\DllOverrides' /v d3dx9_43 /d native /f
touch "$WINEPREFIX/.neolegacy-setup-done"
fi
cd "$GAME_DIR"
exec wine Minecraft.Client.exe "$@"

38
tools/send_f2.c Normal file
View File

@@ -0,0 +1,38 @@
#include <windows.h>
#include <stdio.h>
static BOOL CALLBACK enumProc(HWND hwnd, LPARAM lParam)
{
if (!IsWindowVisible(hwnd))
return TRUE;
wchar_t title[256] = {0};
GetWindowTextW(hwnd, title, 255);
if (wcsstr(title, L"Minecraft"))
{
*(HWND *)lParam = hwnd;
return FALSE;
}
return TRUE;
}
int main(void)
{
HWND target = NULL;
EnumWindows(enumProc, (LPARAM)&target);
if (!target)
{
printf("no Minecraft window found\n");
return 1;
}
wchar_t title[256] = {0};
GetWindowTextW(target, title, 255);
wprintf(L"found window: %ls\n", title);
SetForegroundWindow(target);
Sleep(300);
keybd_event(VK_F2, 0, 0, 0);
Sleep(60);
keybd_event(VK_F2, 0, KEYEVENTF_KEYUP, 0);
Sleep(300);
printf("sent F2\n");
return 0;
}

41
tools/send_key.c Normal file
View File

@@ -0,0 +1,41 @@
// send_key.exe <hexVk> [hexVk...] — focuses the Minecraft window and sends key taps.
#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
static BOOL CALLBACK enumProc(HWND hwnd, LPARAM lParam)
{
if (!IsWindowVisible(hwnd))
return TRUE;
wchar_t title[256] = {0};
GetWindowTextW(hwnd, title, 255);
if (wcsstr(title, L"Minecraft"))
{
*(HWND *)lParam = hwnd;
return FALSE;
}
return TRUE;
}
int main(int argc, char **argv)
{
HWND target = NULL;
EnumWindows(enumProc, (LPARAM)&target);
if (!target)
{
printf("no Minecraft window found\n");
return 1;
}
SetForegroundWindow(target);
Sleep(400);
for (int i = 1; i < argc; i++)
{
int vk = (int)strtol(argv[i], NULL, 16);
keybd_event((BYTE)vk, 0, 0, 0);
Sleep(80);
keybd_event((BYTE)vk, 0, KEYEVENTF_KEYUP, 0);
Sleep(400);
printf("sent vk 0x%02X\n", vk);
}
return 0;
}