pyMHF 0.1.7__tar.gz

pymhf-0.1.7/.github/workflows/pipeline.yml

@@ -0,0 +1,88 @@
+name: pyMHF
+
+on:
+  # Run on all branches except for the gh-pages branch
+  push:
+    paths-ignore:
+      - '*.md'
+    branches-ignore:
+      - 'gh-pages'
+    tags:
+      - '*'
+
+jobs:
+  build_test:
+    name: Build artefacts
+    runs-on: Windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        py_ver: [{version: '3.9'}] # , {version: '3.10'}, {version: '3.11'}]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python ${{ matrix.py_ver.version}}
+        uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.py_ver.version}}"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip uv
+          uv sync --frozen --dev
+      - name: Build Python ${{ matrix.py_ver.version}} wheel
+        run: uv build
+      - name: Lint and format code
+        run: |
+          uv run ruff check ./pymhf
+          uv run ruff format --check ./pymhf
+          uv run python -m twine check ./dist/*
+      - name: Upload Wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+  release:
+    name: Release pyMHF wheels and source build to PyPI
+    # Only run this job if the commit was tagged.
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - build_test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pyMHF
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - name: Download files for release
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+
+  test-release:
+    name: Release pyMHF wheels and source build to test-PyPI
+    needs:
+      - build_test
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pyMHF
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - name: Download files for release
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          attestations: true

pymhf-0.1.7/.gitignore

@@ -0,0 +1,10 @@
+build/*
+*.egg-info/
+**/__pycache__/**
+**/logs/**
+**/CRITICAL_ERROR.txt
+dist/*
+logs
+mods
+.venv/
+/run_*.py

pymhf-0.1.7/LICENCE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 monkeyman192
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymhf-0.1.7/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: pyMHF
+Version: 0.1.7
+Summary: python Modding and Hooking Framework
+Author: monkeyman192
+Maintainer: monkeyman192
+Project-URL: Homepage, https://github.com/monkeyman192/pyMHF
+Project-URL: Repository, https://github.com/monkeyman192/pyMHF.git
+Keywords: hooking,games,hacking,modding
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENCE.md
+Requires-Dist: cyminhook>=0.1.4
+Requires-Dist: psutil~=5.9.5
+Requires-Dist: pymem[speed]~=1.12.0
+Requires-Dist: keyboard
+Requires-Dist: pywin32
+Requires-Dist: dearpygui~=1.11.0
+Requires-Dist: questionary
+Requires-Dist: pywinctl
+Requires-Dist: packaging
+
+# 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 creatting a modding library as easy as possible:
+
+### 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](https://github.com/hoffstadt/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).

pymhf-0.1.7/README.md

@@ -0,0 +1,47 @@
+# 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 creatting a modding library as easy as possible:
+
+### 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](https://github.com/hoffstadt/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).

pymhf-0.1.7/docs/api/mod_loader.md

@@ -0,0 +1,12 @@
+# Mod Loader
+
+The `pymhf/core/mod_loader.py` file contains a number of functions and classes related to loading of mods.
+
+## Classes
+
+### `class ModState(ABC)`:
+    This class is the Base class which is used to indicate that the inheriting class is a "Mod State" (see docs...) # TODO: add link.
+
+### `class Mod(ABC)`:
+    The base class for any mod.
+    No methods are currently defined on this class, however, if your mod class has its own `__init__` method, then you MUST call `super().__init__()` in it otherwise the mod will not be properly initialised and an error will be raised to indicate this.

pymhf-0.1.7/docs/change_log.md

@@ -0,0 +1,45 @@
+# Change Log
+
+## Current
+
+### 0.1.6 (08/09/2024)
+
+- Add ability for GUI widgets to reload when their associated mod gets reloaded ([gh-4](https://github.com/monkeyman192/pyMHF/issues/4))
+- Add `extra_args` option to GUI field type decorators (eg, `FLOAT`) which are passed through to DearPyGui ([gh-8](https://github.com/monkeyman192/pyMHF/issues/8))
+- Fix issues with hooking multiple functions which are overloads of the same base function.
+- Add the ability for patterns to be hooked up using the `FUNC_PATTERNS` data in implementing libraries ([gh-14](https://github.com/monkeyman192/pyMHF/issues/14))
+
+### 0.1.5 (26/08/2024)
+
+- Allow overriding of function return values.
+- Fixed issue with `after` manual hooks with a `_result_` argument.
+- Implement pattern scanning functionality ([gh-1](https://github.com/monkeyman192/pyMHF/issues/1))
+
+### 0.1.4 (14/08/2024)
+
+- Overhauled config system to provide a more user-friendly experience.
+- Fixed a critical bug in hooking which meant that no result was returned.
+- Fixed an issue injecting variables into pymhf.
+
+### 0.1.3 (31/07/2024)
+
+- Implemented manual hooks. These are a decorator which have the can take an offset, name, and function definition, and allow for hooking a function without having to rely on the underlying library which utilises pymhf.
+- Made changes so that libraries can be installed as plugins to pymhf so that they can be run like `pymhf <libname>`
+
+### 0.1.2 (15/07/2024)
+
+- Made improvements to config reading
+
+### 0.1.1 (05/07/2024)
+
+- Fixed issues loading applications which aren't loaded with steam.
+- Fixed logging number of mods loaded.
+- Implemented custom triggers. They can be implemented by libraries which use this framework to enable custom triggers which are specific to the game/application.
+- Fixed some issues with reloading of mods when there are multiple mods all contributing to compound hooks, including hooks with completely disabled detours.
+- Added `@no_gui` decorator which can be applied to a `Mod` class to indicate that it doesn't need to be shown in the GUI.
+
+## Previous
+
+### 0.1.0 (30/06/2024)
+
+- Initial release. Much of the functionality has been copied over from NMS.py which was how this project started.

pymhf-0.1.7/docs/settings.md

@@ -0,0 +1,32 @@
+# pyMHF settings file
+
+*pyMHF* contains a file called `pymhf.cfg` which (currently) must be situated within the root directory of the modding library (cf. [here](../writing_libraries.md))
+This file has a number of properties in different sections. Some are required and others are not:
+
+## `binary` section:
+
+This section handles properties which relate to the game or program that the library will be for.
+
+- **path**: The full path of the binary to be run.
+
+- **mod_dir**: The full path to the directory containing the mods to be run.
+
+- **hash**: The `SHA1` hash of the exe. This is used to ensure that the binary matches what is expected by the library exactly.
+
+- **steam_guid** [optional]: If the game is run through steam, this should set to the Steam App ID. This can be found by right clicking on the game in your library and selecting "Properties...". The value can be found under the "Updates" option on the left.
+
+- **required_assemblies**: [optional]: A list of assemblies that are required to be loaded by the binary at `path` for the game to be considered "loaded". For now, if this is provided, it will also be the binary within which offsets are found relative to, however this will be relaxed in the future as better functionality regarding this is developed.
+
+## `pymhf` section:
+
+- **log_level**: Whether to log at the standard level (`INFO`), or more in-depth (`DEBUG`).
+
+## `gui` section:
+
+This section related to properties specifically for the GUI which is auto-generated.
+
+- **shown**: Whether or not to show the GUI (`True` or `False`).
+
+- **scale**: The scale of the GUI. For some high-resolution monitors the GUI may end up scaled down when running from within a process, so sometimes this may need to be set to 1.5 for the GUI to look correct.
+
+- **log_window_name_override** The text to display at the top of the log window.

pymhf-0.1.7/docs/setup.md

@@ -0,0 +1,16 @@
+# Setup
+
+1. Ensure that python 3.9+ is installed
+1. Install the required dependencies. Run the following in the current directory: `python -m pip install .`
+1. Modify `pymhf.cfg` to have the correct binary path. Note that currently the only supported binary is the one which has the hash listed in the file. You can check the hash of your NMS binary by running `certutil -hashfile "NMS.exe" SHA1` in the directory with the NMS.exe binary.
+1. in a terminal run `python main.py`
+
+You should have another popup appear with the pyMHF logo at the top, and then a series of log messages.
+If this doesn't occur then your firewall may be blocking the port 6770, so make sure that a TCP connection is allowed on this port on your local network (ie. 127.0.0.0, or possibly 0.0.0.)
+
+If all goes well you should see `"Serving on executor ('127.0.0.1', 6770)"`
+Once you see this message you are fine to press anything in the other window where you entered `python main.py`.
+
+Any exceptions will be logged to a file named `CRITICAL_ERROR.txt`, and logs will be placed in a `logs` directory.
+
+- If you want to stop the application, you can press `ctrl + C` in the window you started the process in to kill it.

pymhf-0.1.7/docs/writing_libraries.md

@@ -0,0 +1,21 @@
+# Writing Libraries
+
+The primary usage of *pyMHF* is to facilitate writing python libraries which can then be used to write mods.
+*pyMHF* provides all the tools required to make setting up a library easy, so that one only has to provide the definitions and all the hooking and mod complexity will be handled automatically.
+
+Follow the next steps to get your library project set up.
+
+## Creating the folder structure
+
+```
+LibraryName
+├── functions
+│   ├── __init__.py
+│   ├── call_sigs.py
+│   ├── hooks.py
+│   ├── offsets.py
+├── types
+│   ├── structs.py
+├── __init__.py
+└── pymhf.cfg
+```

pymhf-0.1.7/pyMHF.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: pyMHF
+Version: 0.1.7
+Summary: python Modding and Hooking Framework
+Author: monkeyman192
+Maintainer: monkeyman192
+Project-URL: Homepage, https://github.com/monkeyman192/pyMHF
+Project-URL: Repository, https://github.com/monkeyman192/pyMHF.git
+Keywords: hooking,games,hacking,modding
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENCE.md
+Requires-Dist: cyminhook>=0.1.4
+Requires-Dist: psutil~=5.9.5
+Requires-Dist: pymem[speed]~=1.12.0
+Requires-Dist: keyboard
+Requires-Dist: pywin32
+Requires-Dist: dearpygui~=1.11.0
+Requires-Dist: questionary
+Requires-Dist: pywinctl
+Requires-Dist: packaging
+
+# 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 creatting a modding library as easy as possible:
+
+### 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](https://github.com/hoffstadt/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).

pymhf-0.1.7/pyMHF.egg-info/SOURCES.txt

@@ -0,0 +1,45 @@
+.gitignore
+LICENCE.md
+README.md
+pyproject.toml
+uv.lock
+.github/workflows/pipeline.yml
+docs/change_log.md
+docs/settings.md
+docs/setup.md
+docs/writing_libraries.md
+docs/api/mod_loader.md
+pyMHF.egg-info/PKG-INFO
+pyMHF.egg-info/SOURCES.txt
+pyMHF.egg-info/dependency_links.txt
+pyMHF.egg-info/entry_points.txt
+pyMHF.egg-info/requires.txt
+pyMHF.egg-info/top_level.txt
+pymhf/__init__.py
+pymhf/_preinject.py
+pymhf/injected.py
+pymhf/log_terminal.py
+pymhf/main.py
+pymhf/core/__init__.py
+pymhf/core/_internal.py
+pymhf/core/_types.py
+pymhf/core/caching.py
+pymhf/core/calling.py
+pymhf/core/common.py
+pymhf/core/errors.py
+pymhf/core/hashing.py
+pymhf/core/hooking.py
+pymhf/core/importing.py
+pymhf/core/logging.py
+pymhf/core/math.py
+pymhf/core/memutils.py
+pymhf/core/mod_loader.py
+pymhf/core/module_data.py
+pymhf/core/process.py
+pymhf/core/protocols.py
+pymhf/core/utils.py
+pymhf/extensions/cpptypes.py
+pymhf/gui/__init__.py
+pymhf/gui/decorators.py
+pymhf/gui/gui.py
+pymhf/gui/protocols.py

pymhf-0.1.7/pyMHF.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pymhf-0.1.7/pyMHF.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pymhf = pymhf:run

pymhf-0.1.7/pyMHF.egg-info/requires.txt

@@ -0,0 +1,9 @@
+cyminhook>=0.1.4
+psutil~=5.9.5
+pymem[speed]~=1.12.0
+keyboard
+pywin32
+dearpygui~=1.11.0
+questionary
+pywinctl
+packaging

pymhf-0.1.7/pyMHF.egg-info/top_level.txt

@@ -0,0 +1 @@
+pymhf