pyMHF 0.2.0

python Modding and Hooking Framework

pyMHF

pyMHF is a python Modding and Hooking Framework. It is designed to make it very easy to create libraries for any game or application which can then be used to make mods.

Features

pyMHF contains a number of important features to make creating a modding library as easy as possible:

Using pyMHF

pyMHF has a number of command line arguments to make running it easier. The main way to run pyMHF is by calling it like so:

python -m pymhf run <module>

Where <module> can either be the name of any library using pyMHF, the absolute or relative path to a folder which contains a pyproject.toml file (this method is often used for local development of libraries), or even the absolute or relative path to a single-file mod.

pyMHF also has a config mode which allows you to override the default values which are provided by the pymhf.toml file as part of a library.

This configuration is done by running

python -m pymhf config <module>

For all possible options, see pymhf --help.

Simple hooking

To create a hook, the following pieces of information are required:

• The relative offset of the function from the start of the binary or the byte signature [WIP] of the function.
• The function call signature. This is the return and argument types, specified as would be expected by using Pythons' ctypes library.
• A class definition which can be used to indicate the hierarchy of functions to allow for simpler calling of functions from the code.

Once this is provided, hooks can be defined as methods within a Mod class, allowing for complex behaviour to be implemented with little effort.

Ability to hook functions across multiple binaries

Whilst not fully feature complete yet, it will be possible to specify what loaded libraries or binaries the functions reside within, to allow for hook function in both the main executable as well as loaded ones.

Automatically generated GUI

A GUI (using DearPyGUI) is automatically generated for the program. All mods will appear automatically as separate tabs, and widgets can be added by way of function decorators within the mod to easily create simple interfaces.

"Compound hooks"

All hooks are defined as either being run before or after the original function. This allows pyMHF to construct what we call "compound hooks" which may consist of any number of detour methods across any number of mods. This means that two mods which affect the same function may coexist (generally) peacefully.

Note: The order of execution of detours is arbitrary, so one must not expect their detour to be run before or after any other detour of the same hook.

Custom callbacks

Modding libraries can define custom callbacks which can be used to allow methods to be called whenever they are triggered. Examples include every game tick or level change for example.

Keyboard callbacks

It is possible to declare methods to be run when a certain key is pressed or released.

Reloadability

One major annoyance when testing and debugging mods at this level is the requirement to often have to reload the game to reload any mods and hooks which have been created. pyMHF has the ability to reload mods (either via the GUI, or via the injected python REPL). This will re-read the python file and reload any hooks or keyboard callbacks which are defined in it.

Mod states

While reloading mods is great, sometimes objects are instantiated once when the game starts and that is it. To avoid losing these instances across reloads, there is the concept of a ModState object which will persist across reloads. These object are bound to the mod itself so it is generally recommended to use these to store any kind of state (and in fact, can be serialized and deserialized to json as a form of saving).