HsMod: a BepInEx plugin that patches the Hearthstone client at load time

A BepInEx and Harmony plugin for a Unity game

HsMod is a Hearthstone modification based on BepInEx, written in C# and built against the .NET 8 SDK, with BepInEx 5.x as its loader and Harmony as the patching library. The repository topics are bepinex, harmony, hearthstone, mod and unity, which is the whole stack in five words.

The technique is the standard one for this kind of tool. BepInEx is injected into the game through the Doorstop loader, the plugin DLL is placed in the plugins directory, and Harmony patches the game's own methods at runtime. Nothing is repackaged and no separate executable is shipped, which is why the install is a handful of file copies rather than a download of a modded client.

The scale of the feature set is unusual for a single plugin. The README documents features across Battlegrounds, the general interface, automation and idle behaviour, emotes and opponents, skins and cosmetics, and a final group it labels simulation and developer. The settings are reached from an in-game Mod Settings button in the game menu, with categories, search and key-binding capture, and a web page fallback is available when the in-game panel will not open.

The project states that the plugin does not collect any information about you, that it follows AGPL-3.0, and that it is used for learning and research only. The source is in the HsMod/ directory of a Visual Studio solution, HsMod.sln, so a reader can see what the plugin does rather than trust a claim about it.

Installing means overriding the loader's search path

The quick start for Windows is five steps, and step four is the one people miss.

You download HsMod.dll from Releases or build it yourself, extract BepInEx x64 into the Hearthstone folder, and copy the DLLs from the plugin's HsMod/UnstrippedCorlib directory into the Hearthstone side of the BepInEx tree:

Hearthstone\BepInEx\unstripped_corlib\

Those unstripped corlib files are the reference assemblies for the game's own framework libraries, which the client ships stripped of the metadata a runtime needs. Then the loader configuration is edited so that the plugin resolves against them:

dll_search_path_override = BepInEx\unstripped_corlib

Finally the plugin itself goes into the plugins folder and the game is launched:

HsMod.dll
Hearthstone\BepInEx\plugins

The settings are opened in-game with Esc followed by Mod Settings, and the wiki holds the full instructions for the other platforms, which the badge lists as Windows, macOS and Linux.

The dependency on the shipped corlib DLLs is the part to think about. Those files are tied to a particular client build, so when Blizzard ships an update the unstripped assemblies have to be refreshed to match. That is a maintenance cycle rather than a one-off install, and it is the strongest practical argument for reading the wiki's installation page before you start.

The project publishes no GitHub releases in the repository listing, so the download the README refers to has to come from wherever the maintainer hosts it, and the alternative is to build the DLL from the solution yourself.

The feature list is long enough to read as a design document

The features section is the substantive part of the README, and it divides into groups that reveal what the author considered worth fixing.

In Battlegrounds, the plugin shows each opponent's MMR under their name in the leaderboard overlay, loaded in the background at match start, and logs session statistics per ranked game, placing, MMR change and hero, to a CSV that is then charted by today, seven days, month or all time and by solo or duos. There are rebindable shop hotkeys for refresh, freeze, tavern upgrade, hero power and the teammate board in duos, active only during the shopping phase, and a fast battle mode that skips part of the animation.

The interface group is where most of the value sits for an ordinary player. Gear speed can be set up to 8 times and configured to 32 times, the window focus requirement and the resizing restrictions can be removed, pop-up prompts such as the cannot match message can be blocked, the real number of cards in favourites is displayed, and the DbId of a selected card is shown on right click. The new markers on cards can be removed with one click, a duel can be abandoned at 0-0, and the game can be muted with a shortcut.

The automation group is the one that needs a considered opinion from the reader. It logs in with VerifyWebCredentials, which the README says also supports command-line startup with no Battle.net needed, disables dropouts for long idle periods, auto-collects rewards from Arena, Duels and Mercenaries, opens five packs at a time, optionally auto-disenchants fully refundable cards, auto-reports opponents, and can block error reporting so no error messages are sent to Blizzard. Auto-rotate decks and auto-watching both sides when spectating a friend are also there.

That is a wide surface, and the settings menu with search and key-binding capture is what makes it manageable.

The developer and simulation group is a debugging console

The last feature group in the README is the one that reveals how the author works on the plugin.

It grants access to Hearthstone Developer Mode, simulates positioning for Hearthside parties, simulates an unplug or a disconnect, and simulates opening packs with random or fixed results and a custom type, quantity, rarity and quality. Device simulation collects pack card backs for iOS, Android and other devices, which may take a matchmaking game. Adventures can be bought with gold, with Naxxramas, Blackrock Mountain and League of Explorers named, and Karazjan can be force-opened, with the README noting that the prologue cannot be played and a level cannot be skipped until it is cleared.

Two of these features are effectively a local service. The information display, called Showinfo, requires the plugin and runs with default HTTP on port 58744, showing mercenary progress, pack-opening history and more. A webshell is available at the path /shell, but it must be enabled in the settings first, and the README warns that the Chinese display may be garbled there.

That webshell deserves a second look before you enable it. A path that grants command execution, sitting behind a local HTTP server on a fixed port, is the kind of thing that should be enabled only while you are debugging and disabled afterwards. The README does not describe any authentication for it, and the honest reading is that the setting is safe only on a machine where you trust every local process.

Skins are the other developer-facing area. Matchmaking and tavern hero skins, finisher effects, panels, the lucky coin and card backs can be modified, with a HsSkins.cfg file or the in-game settings, and the README says to press F4 to save while updating in a match and then simulate a disconnect, which tells you exactly how the workflow is meant to be used.

The China anti-cheat warning is the risk to weigh

The README opens with a warning that deserves to be read before anything else in this article.

It says that the Hearthstone client in mainland China starts the anti-cheat SDK by default, and that the plugin will try to block the related anti-cheat functions, but that it cannot guarantee the safety of your account.

That is an unusually direct statement, and it changes the character of the project. Blocking anti-cheat functions is not a feature in the same sense as the MMR overlay or the gear speed, it is a workaround for a client that ships with a protection mechanism, and the maintainer is explicit that the account risk remains. Any decision to install this on such a client has to be made with that sentence in mind, and no configuration in the settings menu changes it.

The same caution applies more broadly, in a quieter way. A plugin that patches a live game client can break with any update, and a plugin that ships automation of logins, reward collection and opponent reporting is doing things the game's own rules were written to discourage. The README's framing, learning and research only, is the author's position, and the AGPL-3.0 licence and the visible source are what let you check the claims rather than take them on trust.

The privacy claim is narrow and checkable. The plugin does not collect any information about you, and everything it does is local: the settings live in configuration, the statistics go to a CSV, the Showinfo server runs on the local machine. There is no telemetry in the description, and the source is in the repository, so that claim can be verified rather than believed.

Chinese first, English second, and a wiki that carries the detail

The project states that it is based on the Simplified Chinese documentation, that the English version may contain translation errors, and that the plugin is not yet fully translated. The mechanism for adding a language is straightforward: edit the JSON files in the HsMod/Languages directory and recompile.

That is a sensible design for a project that started in one language, and it also tells you what to expect from the English README. A feature list translated from another language will not always carry the nuance of the original, and the README says so itself. The authoritative documentation is the wiki, which covers installation, every setting, hotkeys and troubleshooting in detail, with the installation page holding the other platforms and the full steps.

The repository itself is small in shape: HsMod.sln, the HsMod/ directory with the plugin source, ReadMe.md, LICENSE.txt and the .github/ directory. The default branch is bepinex5, which matches the BepInEx 5.x loader the plugin targets, so a branch switch is how you would move to a different loader generation if the project ever adds one. The last push was on 2026-10-03, and the repository has no GitHub releases, so versions live in the loader's release assets and in the build you produce from the solution.

Editorial conclusion

Adopt HsMod if you want the specific conveniences it implements, such as a searchable in-game settings menu, Battlegrounds MMR display, gear speed control and local information server, and you are willing to keep a modified client and to rebuild when the game updates. Do not adopt it if you play in the mainland China client, because the README warns that the anti-cheat SDK is started by default there and that blocking it cannot guarantee the safety of your account. Before you install, read the account warning, check that the shipped HsMod/UnstrippedCorlib DLLs match your client build, and decide whether the HsMod.dll in Hearthstone\BepInEx\plugins and the dll_search_path_override in doorstop_config.ini are changes you want on your machine at all.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Pik-4/HsMod on GitHub
4. Project website
5. README