feat(macos): Apple Silicon patcher with macOS platform WAD protection#242
Open
RealDoc06 wants to merge 10 commits into
Open
feat(macos): Apple Silicon patcher with macOS platform WAD protection#242RealDoc06 wants to merge 10 commits into
RealDoc06 wants to merge 10 commits into
Conversation
Skin mods designed for Windows were having their chunk hashes cross-matched into Bootstrap.macos.wad.client and ShaderCache.metal.wad.client via the overlay builder's cross-WAD distribution. This corrupted macOS-specific assets (Metal shaders, platform config) and crashed the game at loading screen. Automatically block these platform WADs from overlay patching on macOS. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds the macOS overlay post-processing the codex sketch had left uncommitted (`canonicalize_macos_wad`, `repair_macos_wad_header`, `create_blocked_wad_passthroughs`, the `shaders.wad.client` blocklist entry) and layers on two fixes that came out of the Aatrox/Vayne investigation: - `canonicalize_macos_wad` now passes ZstdMulti chunks with `frame_count > 1` or `start_frame != 0` through raw and preserves per-chunk subchunk metadata in the dedup branch. The previous code decompressed every ZstdMulti chunk from frame 0 via `load_chunk_decompressed` and lost `start_frame` on dedup, which silently collapsed every subchunk to the first frame's data. - New `restore_subchunk_overrides` pass runs before canonicalize. It walks each overlay WAD's TOC against the original game WAD: when the source has subchunk metadata for a path_hash and the overlay no longer carries it, the entry is rewritten back to the source's bytes + metadata. This is the actual Aatrox crash root cause: the shock-blade-talon mod owns hash `afcf66c1d4cc7b27` as a standalone Zstd chunk; ltk_overlay's cross-WAD distribution routes it into Aatrox.wad.client, where that hash is a subframe of a multi-frame zstd stream. The mod override rewrites the entry's `frame_count`/`start_frame`/`uncompressed_size` to 0/0/21884, and the macOS game's WAD mount fails with `ALE-18967994 Inconsistent`. Reverting the entry lets Aatrox load cleanly. Vayne still crashes after the loading screen — its overrides don't touch subchunked entries, so the mechanism is different and the next commit will tackle it. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…N overrides macOS Wwise loader crashes on mod-added audio banks above ~16 MB (e.g. Vayne's 36 MB BKHD bank). Strip such new .bnk/.wpk chunks from the overlay so the visual portion of the mod still applies, and revert any PROP/PTCH override BIN that references a stripped audio path by hash so the game loads its original audio config instead of issuing dead Wwise lookups that crash downstream. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reconcile upstream's external-host patcher rewrite with the fork's
cross-platform `patcher::backend` abstraction (the foundation of the
macOS ARM64 patcher).
Resolution strategy — preserve the fork's backend architecture so macOS
keeps working, while folding in upstream's platform-agnostic, frontend-
wired additions:
- patcher/mod.rs, commands/patcher.rs: keep the fork's backend-dispatch
flow (selected_backend → preflight → run with a BackendEvent sink).
Windows continues to use the in-process cslol-dll FFI via
`legacy_patcher`; upstream's new `patcher::{host,injector}` external
patcher is not adopted here. Restored `legacy_patcher` source and
cslol-dll.dll, which upstream had removed.
- Gate `legacy_patcher`, `patcher_dll_path`, and the cslol-dll diagnostics
to `#[cfg(target_os = "windows")]` — upstream had un-gated code that
would fail to compile on macOS.
- Graft upstream's `check_linked_bins` command + LinkedBinReport types
(the new frontend depends on them) and keep the WAD-scan payload types
for binding/event-contract consistency (only emitted on Windows hosts).
- StoredPatcherConfig/PatcherConfig: restore `log_file`/`timeout_ms`,
which the backend PatcherContext and hot-reload path require.
- PatchingSection.tsx: union of the fork's macOS preflight card and
upstream's injector-elevation card.
- Regenerated TS bindings.
Verified on macOS: cargo check, tsc, eslint, prettier, and the full
vitest suite (281) all pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The elevated macOS patcher helper sends its CARGO_PKG_VERSION in the hello frame, which the backend validates against the app's version. The upstream v1.10.1 merge bumped the app crate but left macos-patcher at 1.9.0, so every elevated session failed validation right after the password prompt. Hoist version to [workspace.package] and inherit it in both crates so they can no longer drift.
Adopt upstream cslol-host injector as the Windows PatcherBackend (replacing the legacy DLL backend) and re-port macOS overlay behaviors (platform WAD blocking, Wwise chunk stripping, dangling BIN revert) onto the new optimized overlay builder.
Three macOS-specific incompatibilities in mod content, found by in-game bisection with the silvervayne Vayne skin: - Block-compressed .tex files with non-power-of-two dimensions and a mip chain segfault the macOS client during champion load (the engine's mip-offset math assumes POT; Windows survives the out-of-bounds read by allocator luck). Repair by stripping the chain down to the full-res level, which is stored last (.tex mips are smallest-first). - A mod's voice-over shipped under the base WAD collides by path-hash with the pristine locale WAD and the client rejects the locale WAD at mount (ALE-18967994 Inconsistent). Instead of dropping the VO, repath it: rewrite the referencing bin strings' locale directory to zz_zz (same length, never a real locale) and re-add the chunk under the mutated hash — the collision disappears and the mod's VO plays. Unreferenced colliding chunks still fall back to being dropped. - Remove the oversized-bank (>16 MB) stub/drop machinery: the intact 36 MB bank loads fine in-game; the crash it was blamed for was the NPOT texture all along.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
cslol-tools (commit 23f230858). Runs as an elevated helper process
communicating over a Unix socket with token-based authentication.
signature validation, and session cleanup on all exit paths.
bootstrap.macos.wad.clientandshadercache.metal.wad.clientfrom overlay patching on macOS. Cross-WAD hash matching was distributing
Windows skin mod chunks into these platform-specific WADs, corrupting
Metal shaders and macOS bootstrap assets — crashing the game at load.
Known limitations
in the macOS game WADs. The overlay builder treats these as new entries
and injects them into the patched WAD, which can crash the macOS client
at loading screen. This has been observed intermittently — the same mod
sometimes loads successfully, suggesting a potential race condition or
load-order dependency. Investigating a fix, likely an
ltk_overlayoption to skip new WAD entries on macOS. For now, users will need to
disable the affected skin mod if it causes crashes.