orfeasz / zhmmodsdk

A modding SDK for Hitman 3

ZHM Mod SDK

A modding SDK and mod loader for HITMAN 3.

Description

This is a community-made modding SDK and mod loader for HITMAN 3. Its purpose is to allow users to easily download and use mods, and make the creation of more complex runtime mods easier for developers.

Right now it's at a very early stage, with only a few aspects of the engine exposed, but the plan is to further extend it to support basic entity, AI, and item manipulation.

Usage (mod loader & mods)

1. Download the latest version of the mod loader and the mods by going here, and downloading ZHMModSDK-Release.zip. This zip file contains the mod loader and a few sample mods.

2. Extract the contents of the ZHMModSDK-Release.zip archive to <drive>:\Path\To\HITMAN3\Retail, where <drive>:\Path\To\HITMAN3 is the path to your Hitman 3 installation directory. This will be at C:\Program Files\EpicGames\HITMAN3 or C:\Program Files (x86)\Steam\steamapps\common\HITMAN 3 by default. Make sure that you extract the files in the Retail folder and not the root HITMAN3 folder.

3. Run the game like you normally would.

4. When the game opens, you'll see a dialog asking you which mods you'd like to use. Select them and press OK. You might need to restart your game for some of them to work.

5. Open the SDK panel with the ~ key (^ on QWERTZ layouts) to change loaded mods at runtime and to use the menus of certain mods.

6. ...

7. Profit?

NOTE: Some mods might require additional setup. For mods bundled with the SDK, refer to the table below. For any other mod, make sure to consult its installation instructions.

NOTE: You can at any time change the mods you're using by pressing the ~ key (^ on QWERTZ layouts) and selecting them, or by editing the mods.ini file inside your game's Retail folder.

NOTE: If you are trying to use this on a Steam Deck or under Proton / Linux, you might need to follow these additional steps.

Sample mods

There are a few sample mods included in this repository that can be used either as reference or for regular gameplay.

Mod name	Description
NoPause	Prevents the game from automatically pausing after losing focus (eg. when alt-tabbing or minimizing).
SkipIntro	Skips the intro sequence and starts the game directly at the main menu.
WakingUpNpcs	Makes pacified NPCs wake up after a random interval between 4 and 8 minutes.
CertPinBypass	Disables SSL certificate pinning, allowing the game to connect to any trusted server instead of only IOI's.
MaxPatchLevel	Dynamically sets the RPKG patchlevel to 1000, making the game discover patch chunks without having to modify the packagedefinition.txt file.
DebugMod	Adds a debug menu to test different SDK functionalities, like 3D rendering and entity information display.
FreeCam	Adds support for an in-game free camera that works with both KB+M and controllers. Can be toggled either from the SDK menu or by pressing P. For more details on available controls see here.
DiscordRichPresence	Sends rich presence updates to Discord with details such as level name, gamemode, etc. Requires additional setup!
Editor	A WIP in-engine "editor". Currently supports viewing spawned entities alongside basic lookup and manipulation. Requires additional setup!
Clumsy	Makes 47 very clumsy. He just can't seem to figure out how to take cover... Requires additional setup!

Uninstalling

To de-activate / uninstall the mod loader, simply delete the extracted dinput8.dll from your HITMAN3\Retail directory. You can also delete all the other files / folders you previously extracted, and the mods.ini file (if present).

Usage (for developers)

To find out how to create your own mods or how to extend the SDK, check out the wiki. Here are some guides to get you started:

Making mods with the SDK

Building & debugging the SDK

You can also check out the sample mods for reference.

Contributing

If you'd like to contribute to the SDK, feel free to open a pull request or an issue. If you're not sure where to start, check out the issues tab.

zhmmodsdk's Issues

feat(editor): Allow reading (& writing) of value floats/bools/ints/...

I'd would be really useful if you could see the value of those. If it then also allowed you to write values it would be perfect.

Cannot open menu on non QWERTY keyboard

I do not have a dedicated ~ key as I use a QWERTZ keyboard. ´

Using ALT GR + + (which is the combination to access the ~ key) does not open the menu.

Would it be possible to use a key that is present on all keyboard layouts or make the SDK recognize the combination to access the menu?

Npcs in containers

Passified npcs put into containers will pop out after their time to wake up and will stand infront of the container and not move but can still react to suspicious actions.

Patch 3.110.0

Latest Hitman 3 patch seems to have broken the loader. Add support for the latest game version.

Third-party overlays can override the SDK's causing no UI to be rendered

Some third-party overlays can override the SDK's UI hooks, resulting in the SDK UI not being rendered / visible.

Overlays that break the UI:

• MangoHUD
• RTSS

Original comment:

Someone already asked this, but the dialog doesn't appear for me. I'm running the latest version of the game (3.140.0) on Epic Games, but it still doesn't appear. I followed the steps completely. Did it twice, still doesn't appear. Any way I can fix this? Thanks in advance!

[Suggestion] Value to Disable ingame pause in Map

This suggestion is tied to having a Live Map in which NPC's need to move while using the map, and this is also controlled by the game engine

Just turning on FreeCam crashes the game

FreeCam - First-Time controls popup configuration

FreeCam now pops up with on-screen controls dialog on first use. For those familiar with the controls, this is just an extra thing to close. It also stays open after leaving free cam mode. Configuration to disable this behaviour would be appreciated.

How to install mods from nexusmods

How would I install mods from here: https://www.nexusmods.com/hitman3/mods/ ?

DebugMod blocks freecam movement

Enabling DebugMod blocks the freecam from moving when you use WASD and the other input controls, only mouse movement works.
I suspect this is due to the recent npc tracking feature, it must be disabling input even when no NPC is being tracked.

[How-To]: Enabling ZHM SDK on Steam Deck and Proton

Just making this a little How-To for getting this Mod SDK to work with Steam Deck and Proton to help folks who come looking. After playing around with it a bit to see what works here's how to get it running on Steam Deck and Proton.

Extract mod contents to the games install directory, the Retail directory as instructed;

/steamapps/common/HITMAN 3/Retail

With use of an application called Protontricks you will be able to modify your wineprefix for the game.

Run Protontricks and select HITMAN 3: 1659040 from the list

You may get a few popup warnings by Winetricks about prefix arch type, but you can ignore these warnings. The next window that pops up will ask you to select which prefix, just make sure it's selected on the default option and hit OK.

Next you want to select Run winecfg and press OK, to then be greeted with the Wine Configuration

Here you want to go to Libraries tab, your DLL overrides list may already be populated, but that's fine, just add these DLL overrides dinput8 and zhmmodsdk, it's lower-case sensitive when you type in the New override for library field box, and you don't need to type the .dll part when adding, just so long the name matches the DLL files. Make sure they're both set to (Native,Builtin), you can check this by clicking on the DLL name in the list and click Edit.

Once you've done all that hit Apply and close everything and launch the game as normal and it should work.

Nothing is working.

Hello developers. Your mod doesn't seem to want to work. I downloaded it before, but had to delete it because of a conflict. Redownloading has proven to be tricky. I have no idea why it isn't working this time around, and any insight you might have would be appreciated.

[Suggestion] Minimap Radius Detection values

I aim to recreate Live Map but the Minimap detection radius values is not controlled by the game entity data but is within the engine , which makes live map impossible without stretching it to the whole map

moded.mp4

[FreeCam] "Keeps camera still while you control 47" doesn't work

About what it says on the tin; there's no way to move 47 while the free camera is enabled. The readme says Left Bumper is assigned to this but it doesn't do anything as far as I can tell. I tried to dig through some files but I'm out of my depth haha.
If it's relatively easy to modify, it'd also be awesome to have a KBM binding or the ability to toggle/hold.

This tool is awesome though, I've been looking for a nice H3 freecam. Thanks!

AdvancedRating access violation when minimizing window

ImGui::TableNextRow ->
AdvancedRating::OnDrawUI ->
ModSDK::OnDrawUI

00007ff8`19380ba0 48895c2408      mov     qword ptr [rsp+8],rbx
00007ff8`19380ba5 57              push    rdi
00007ff8`19380ba6 4883ec30        sub     rsp,30h
00007ff8`19380baa 488b0557b31700  mov     rax,qword ptr [advancedrating!GImGui (00007ff8`194fbf08)]
00007ff8`19380bb1 8bf9            mov     edi,ecx
00007ff8`19380bb3 0f29742420      movaps  xmmword ptr [rsp+20h],xmm6
00007ff8`19380bb8 0f28f1          movaps  xmm6,xmm1
00007ff8`19380bbb 488b98e81f0000  mov     rbx,qword ptr [rax+1FE8h]
00007ff8`19380bc2 80bb4902000000  cmp     byte ptr [rbx+249h],0 ds:00000000`00000249=??

last line is the access violation, rbx is null
rax is 66ef40
66ef40+1fe8 = nullptr

// [Public] Starts into the first cell of a new row
void ImGui::TableNextRow(ImGuiTableRowFlags row_flags, float row_min_height)
{
    ImGuiContext& g = *GImGui;
    ImGuiTable* table = g.CurrentTable;

    if (!table->IsLayoutLocked)
        TableUpdateLayout(table);
    if (table->IsInsideRow)
        TableEndRow(table);

I'm guessing it's testing IsLayoutLocked but table is null, because the g.CurrentTable variable is null. Not sure why that would happen on minimization but that's all I've got

Uninstall instructions missing

There are no uninstall / update instructions in the README.md or anywhere else I could find. Please add them for clarity, thanks!

UI Overlay messed up

Hello,

I'm new to modding Hitman 3, and unfortunately it feels really jankey, but I got ZHM, this ReShader program, and simple framework.

As I understand it, 'home' opens the ReShader program and '' opens the overlay on ZHM. Unfortunately, when I press it, nothing happens except my cursor changes. I have to press it again to be able to navigate Hitman3. If I spam it enough times, I get a little glimpse of what it looks like (or hold '' down). It looks red, and I see some mod options and an OK button. Unfortunately, I can't get it to stay up like the ReShader overlay easily does.

Any help?

Newest release version
Windows 11
Geforce 4090

PS: I tried to search for this answer, and it looked like someone had this before, but I didn't get a solution.

EDIT: Actually, during the loading screen, it was working fine. After that, I can't access it at StartUp, Intro, MainMenu, Game. Just loading screen which is pretty fast.

DebugMod Assets Spawner No Longer Works

A few days ago it still allowed for both searching & spawning assets but now it neither suggests assets nor allows me to spawn them via e.g. their repo ID or name/title.

How to Deselect or Clone an Item in Debug?

(see title.)

Unable to move 47 even when using the left bumper

"Keeps camera still while 47 moves" feature doesn't work

[Suggestion] Unlimited ammo mod

I think a mod which gives you unlimited ammo would be pretty cool

[Suggestion] Pause game when use free camera

Make free camera like Ansel, no fitlers or something else, just make game stop when use the freecamera. Add settings like off HUD, this settings can edit in mods. Like free camera without HUD, using free camera stop game time.

Game doesn't get past launcher on Epic

After installing 1.7.0, the game opens the launcher like normal, and then crashes when the game tries to open.
I have no overlays enabled, no controllers plugged in and I've tried compatibility settings.

Steam version is unsupported (black screen on startup, no UI)

After unpacking the mod loader to the retail folder and mods to the mods folder, the game shows black screen when i try to run it.
Im playing on 3.100 steam version.

[Editor] ZRenderMaterialEntity causes a crash

Most ZRenderMaterialEntity entities cause the game/sdk to crash when selected in the tree view.

I have found some that don't cause a crash like entity 522ee344354b4a4a in scenario_gecko.brick under Scenario_Gecko -> Environment -> Material_Overrides -> atrium_wallpaper_stuccotrowel_a but the entity directly below it 3bf2038c565cd0f0 (backdrop_building_miami_near_b) causes a crash.

A lot of the property names are corrupted as well in the non-crashing entities but the property values seem to be fine.

Suggestion: complete all tasks

I wanted to write a suggestion. and this seems like the only place to do it.

Just a way to trick the game to think you finished all the tasks.
This can be interpreted as finished all "hits"
OR
Finished all possible challenges before escaping

I mainly wish for the second one to help speed up my process of unlocking everything after my migration to hitman 3 failed and I need to now replay everything if I wanna unlock anything again.

The game permanently freezes when I try to stop recording with Nvidia Shadowplay

The game for some reason permanently freezes when I try to stop recording with Nvidia Shadowplay. It only happens when ZHMModSDK is installed.

Game Freeze when starting on steam with last version

Hello there, i tried to install the last version of the SDK, but when I launch the game, it freezes, then I'm forced to quit the game with an ALTF4. I also installed the debug version the check if there is a problem while loading the game. But it show no errors :/

SDK UI renderer causes crashes and freezes

I installed SDK release 1.7 to the retail folder. Whenever I try to launch the game through steam, it cuts to black like it’s launching, and then crashes quickly back to desktop.

Also there isn’t a mods.ini file in the release. Does it generate if the sdk successfully launches with the game? Trying to play the new freelancer mod but the SDK is preventing my game from working. It’s only when I remove the files that the game launches.

Adjustable controls in FreeCam?

Using a controller, I find the control layout for FreeCam to be very awkward to use when compared to nVidia Ansel. It would be great to be able to customise the controls, including making raise/lower camera bound to triggers rather than a more difficult combination of inputs.

most frequent crashes ive experienced

no null check for s_Action

s_GlobalOutfitKit pointer sometimes points to invalid memory

Some Questions

Sorry if this is the wrong place I didn't see a forum to ask these questions.
I understand this is new so there isn't much explanation on some of the mods

1. CertPinBypass : Does this mod do anything at the moment? Is the intention that we could make a fake spoofed IoI server so we could play offline but let the game think we are online and level up etc?

2. As for the mod loader does it currently only support the mods listed here? Do the mods require dll. Will this allow for downloading of mods off of nexus and placing them here in a folder and the mod loader does the job of putting them in the proper place?

Sorry I am not a modder but am very interested in where this project is going.
It would be ideal if we could play this game offline and still unlock items and be able to see our SA icon and even getting a rating even if it wasn't published to the leaderboards. Besides the leaderboards are already plagued with cheaters so they aren't of actual use.

Once again sorry in advance if this isn't where this should go and keep up the good work its thanks to people like you that games like this can live on past when the devs decide to support it.

Change console key

Is there a way I can change the hotkey to open the overlay?

Lower FPS while using the SDK

The SDK unfortunately lowers the framerate by a long shot. In a spot where I'd usually have 106 fps, I now have only 76. So the SDK causes a loss of around 25-30 fps. The SDK is currently a must to use the Freelancer Variations mod. I hope it's possible to fix or attenuate this performance issue.

Functions::ZDynamicObject_ToString not escaping quoted values

DECLARE_PLUGIN_DETOUR(Stealthometer, void, ZAchievementManagerSimple_OnEventSent, ZAchievementManagerSimple* th, uint32_t eventId, const ZDynamicObject& event)
{
	ZString s_EventData;
	Functions::ZDynamicObject_ToString->Call(const_cast<ZDynamicObject*>(&event), &s_EventData);

	Logger::Debug("Achievement Event Sent: {} - {}", eventId, s_EventData);

	auto s_JsonEvent = nlohmann::json::parse(s_EventData.c_str(), s_EventData.c_str() + s_EventData.size());
	// ...
}

This code will crash in the event that an event value has quotes, due to those quotes not being double escaped. For example, on killing or KOing Marv "Slick" Gonif in Holiday Hoarders.

[Debug Mod] Many assets crash the game

Adding/giving specific props using the asset menu crashes the game. This mostly happens with but isn't exclusive to S3 items.

[Suggestion] Configurable min/max times and chance of death for WakingUpNpcs

I'd like WakingUpNpcs to have configurable min/max times in its INI section.

47 just bashed their heads in with a crowbar; that's going to do a lot of damage. So a related idea I just had is for a configurable percentage chance (maybe 1% to 5% by default) that NPCs don't wake up and can eventually die from their injuries after a longer period of time (maybe 30mins by default). That could encourage either hiding the bodies or finishing the mission faster.

Please Update the SDK for Hitman III

The mod hasn't worked since patch 3.110.0
I've installed it properly, and it used work before that patch, but now the only thing pressing the tilde key does is bring up the cursor, which implies that certain aspects of the SDK still work, but the menu to turn any options on, or using any hotkeys does absolutely nothing. I've labelled this as a new issue hopefully to get your attention, I don't know if you plan on maintaining this mod anymore, but please if this could be updated when Hitman III gets its "freelancer mode" update, as that'll bring a lot of players, myself included, back to the game, and I want to record some cinematics that are only possible with your SDK camera mod.

Discord Rich Presence doesn't work

I have downloaded the 'mods' and 'mods-loader' folders and placed them accordingly. The other mods are being detected correctly. Additionally, I have downloaded the DLL file (discord_game_sdk.dll) into my Retail folder but still, it's not working, Am I doing something wrong? @OrfeasZ

Advanced Rating mod is not mentioned in the Documentation + Game Crashing bug when is used

As the title says. I would post this on the github page for the Advanced Ratings mod, but it's not linked.

When playing with Advanced Ratings enabled, placing, throwing, dropping, or retrieving the Bubble Queen sedative gum (from 7 Deadly Sins; Gluttony) from a briefcase instantly crashes the game.

Add ability to see / copy local entity transform in Editor

That

Broken controls after restarting without exiting FreeCam

Using a controller. When entering FreeCam, the game is still running, so I will sometimes pause the game, resulting in the usual pause menu but still allowing me to adjust the camera. If I then restart the level, some of the game controls are broken until I enter free cam and exit again.

Ideally FreeCam should automatically restore the controls when the level is restarted.

Unclear instructions on how to download it

I am finding the instructions hard to understand could you make them clearer or even make a video tutorial because I could seem to find any .dlls in the files for the mod pack

[Suggestion] NoPause Mod with Steam Overlay

The NoPause currently only works if you alt-tab or minimize, however i think it should also work for opening the Steam Overlay

No dialog appear when game is opened

When the game opens, you'll see a dialog asking you which mods you'd like to use. Select them and press OK. You might need to restart your game for some of them to work.

I followed all the instructions but there was no dialog when I opened the game.

Game crashes if DebugMod is enabled while in-game

Suggestion: ESP but 2D Boxes or more settings for esp

heyy, i ask for it, i love with esp in mission to play <3

Example ESP:
Name (Smaller Font)
Health (Text / Bar)
Distance
Box Changer (2D, 3D)
Distance Render (100m - 800m)

BEST FOR (ONLY IF WORKS: GLOW)

Game will not start past the launcher if Wireless Controller is connected

Hi,

I am using an Xbox Elite Series 2 controller synced to a USB wireless adaptor plugged into my PC. If I try to launch the game while the controller is on, the debug cmd window gets as far as:

...
Successfully installed detour for D3D12 vtable hook address 0x7ffa1fb0a9a0.
Successfully installed detour for D3D12 vtable hook address 0x7ff9ed431fe0.
Resuming 43 suspended threads.
Installed D3D hooks.

Sometimes a bit further, and then closes. The game does not open after that and Steam does not behave like it is open (the green "play" button becomes clickable again once the cmd window closes).

If the controller is off, and then I turn it back on when I get to the game's main menu, it works perfectly.

Enabling or disabling Steam overlay has no effect.

Thanks very much

Game getting stuck at startup (unless you use noIntro mod)

4 out of 5 times the game gets stuck at startup

Suggestion: Option for NoPause to keep audio playing in background