A ZHMModSDK plugin that lets an Epic and a Steam player play HITMAN 3 Ghost Mode together, on every Ghost Mode map of the CrossGhost Assets mod.
To play ghost mode with crossplay enabled, you'll need the following requirements installed. Consult the respective installation guide for each of those:
- Simple Mod Framework
- ZHMModSDK
- CrossGhost Assets (
ramoncc.CrossGhostAssets) deployed with SMF - CrossGhost.dll downloaded from the release page and copied into
<Hitman Install Folder>/Retail/mods/ - The old LocalGhost Patcher is NOT NEEDED!
Activating the mod is easily done by opening the ZHMModSDK Interface by pressing insert. Then open the mod list and enable CrossGhost.
When toggling the mod on or off, you will need to restart the game for smooth operation. It can get buggy otherwise.
To host a lobby, follow these steps:
- Open Ghost Mode from main menu
- Go to Invite Player to the right and select a map
- When in the lobby, press insert to open ZHMModSDK and click the Host Button in the CrossGhost mod.
- Send the 5 Digit code to your friend.
- Both players press ready in Hitman and the match will begin.
To join a lobby, follow these steps:
- Open Ghost Mode from main menu
- Press insert to open ZHMModSDK and enter the 5 Digit Code in the Text field from the CrossGhost mod.
- Click join and wait a few seconds until you're in the lobby and can see the other player.
- Ready up, when you're ready. The match will begin when both players are ready.
host game (RakNet :30000) ⇄ host proxy (127.0.0.1:30001) ⇄ room client
⇄ CrossGhost server relay (UDP 30002) ⇄
room client (127.0.0.1:<random>) ⇄ guest game
- Backend. At startup the DLL patches the game's backend configuration so
both storefronts use the CrossGhost server
(
src/backend/). - Hosting. The game's "create lobby" request (EOS or Steam lobby) is
rewritten to "local host", a plain RakNet lobby. The plugin records the
lobby data the guest will need (map, game mode, host key, version) and
serves it through the host proxy (
src/net/host_proxy.*). - Room. Pressing Host creates a room on the server and shows its code.
The room client (
src/net/room_client.*) keeps an outbound UDP tunnel to the server's relay, so no inbound ports are needed. - Joining. The guest joins the room, fetches the host's lobby metadata
through the tunnel (
src/net/metadata_fetcher.*) and then drives the game's own join flow:- Epic (
src/epic/epic_guest.*): queues a native "accept invite" and serves the metadata through a lobby-data provider. - Steam (
src/steam/): fakes a Steam lobby and Steam P2P session (steam_lobby_shim.*) and dispatches a native invite to it.
- Epic (
- Leaving. When either player leaves, the native RakNet disconnect is relayed before the room closes, so the other side leaves its lobby at once.
src/plugin_entry.cpp SDK exports; picks the Epic or Steam implementation
src/game_build.* Supported executables (SHA-256) and storefront detection
src/backend/ Backend-origin patch (replaces the LocalGhost patcher)
src/common/ Memory access, vtable/IAT hooks, game strings, lobby layout
src/net/ Room client, relay protocol, host proxy, metadata codec
src/epic/ Epic hooks; epic_offsets.h lists every game address used
src/steam/ Steam hooks and lobby shim; steam_offsets.h lists addresses
src/ui/room_panel.* The "CrossGhost" SDK window shared by both builds
tests/ Codec/proxy, room tunnel and installer tests
scripts/ Dependency download and game installation
Game addresses are RVAs for the exact executables above. If the game updates,
every value in epic_offsets.h, steam_offsets.h and the backend layouts in
backend_patch.cpp must be re-derived; hook installation refuses to run if a
vtable slot does not contain the expected function. After updating the hashes
and offsets, check them against the installed executables (no game launch):
python scripts/verify-game-build.py --epic '<Epic>\Retail\HITMAN3.exe' --steam '<Steam>\Retail\HITMAN3.exe'kGameVersion in game_build.h is also the build the room service accepts, so
the CrossGhost server's ghostRooms/service.mjs must be updated and redeployed alongside.
Native Windows requirements: Visual Studio 2022 (x64 C++), CMake 3.20+, Git, PowerShell 7, and Node.js 20+ for the room tunnel test.
./scripts/fetch-deps.ps1 # once: ZHMModSDK 4.2.1 and DirectX-Headers
./build.ps1 -NoPublish # build/Release/CrossGhost.dll
./build.ps1 # also copies the DLL to dist/
ctest --test-dir build -C Release --output-on-failure-PublicOrigin selects the CrossGhost server compiled into the DLL (default
https://hitmanghost.ramon.cc). Close HITMAN before running the tests; they
bind UDP 30000. The room-tunnel test needs a crossghost-server
checkout next to this folder (../localghost, or set GHOST_LOCALGHOST_DIR).
The same MSVC-ABI DLL can be cross-compiled on Linux with clang-cl, lld-link and the MSVC CRT/Windows SDK from xwin:
# once: unpack the CRT and Windows SDK (or set XWIN_ROOT)
xwin --accept-license --cache-dir /root/.xwin-cache splat --output /xwin
bash scripts/fetch-deps.sh
bash scripts/build-linux.sh # dist/CrossGhost.dll
ctest --test-dir build-linux --output-on-failureRequirements: clang/lld 19+, CMake 3.20+, Ninja, Git, unzip, and Wine for the
tests. CONFIG, GHOST_PUBLIC_ORIGIN, BUILD_DIR and XWIN_ROOT can be set as
environment variables. The install-script and room-tunnel tests need a
native Windows host, so only relay-metadata runs here.
Merging to main runs .forgejo/workflows/release.yml on a docker runner in
messense/cargo-xwin:0.23.1 (clang 19, lld, CMake, Ninja and Wine). It installs
the xwin MSVC CRT/Windows SDK, cross-builds dist/CrossGhost.dll, runs the
tests under Wine and publishes a v0.<run_number> release with the DLL
attached. The release notes are generated from the commits since the previous
release, including the merge request numbers referenced in their titles.
Install the same DLL on both PCs. ZHMModSDK 4.2.1 and CrossGhost Assets must already be installed. Close HITMAN, then (elevated for Program Files):
./scripts/install.ps1 -GameRoot 'C:\Program Files\Epic Games\HITMAN3'
./scripts/install.ps1 -GameRoot 'C:\Program Files (x86)\Steam\steamapps\common\HITMAN 3'The script copies dist/CrossGhost.dll into Retail/mods, backs up older
plugin DLLs (including the pre-rename GhostCrossplay.dll) and enables
[CrossGhost] in Retail/mods.ini.
- Host: open Ghost Mode and choose a map. In the CrossGhost SDK window press Host and share the room code.
- Join: open Ghost Mode, enter the code in the CrossGhost window and press Join.
Do not run the Epic and Steam games on the same PC at the same time; both use UDP 30000 and 30001.
The plugin was renamed from GhostCrossplay.dll to CrossGhost.dll. Delete
Retail/mods/GhostCrossplay.dll (or run scripts/install.ps1, which backs it
up) so the old and new plugin never load together, then enable CrossGhost
in the ZHMModSDK mod list.