Kana's Body Framework (KBF) is a mod for Monster Hunter Wilds that lets you modify all the bones of important characters (Players, NPCs), and create, share, & organize presets for them.
I created this plugin to allow modification of a large number of bones per-frame with minimal CPU overhead (typically, 0.1 - 0.5ms), and thus impact on framerate.
This repo also serves as a very thorough native (C++) REFramework plugin reference, for which there is not much documentation within reframework itself, nor many open-source examples elsewhere.
Importantly, this mod also implements a hot-reloader for itself (native/main_hot_reload.cpp) which is absolutely necessary for making any native plugin of this complexity. Feel free to pillage this for your own plugins.
KBF Requires REFramework Nightly 01212 (or higher)
Extract the contents of the zip files KanasBodyFramework_vX.X.X and KanasBodyFramework_Fonts_vX.X.X into your game directory where MonsterHunterWilds.exe is located, or drop the zips into a mod manager of your choosing.
The recommended way to build KBF is with CMake & the MSVC compiler via Visual Studio.
This project uses Git submodules. First, clone the repository with submodules:
git clone --recurse-submodules https://github.com/kana-desu/KanasBodyFramework.gitIf you already cloned the repo without --recurse-submodules, you can initialize and update them with:
git submodule update --init --recursiveYou can build an use a debug build of REFramework to assist when debugging.
Run the following script with either RelWithDebInfo (Recommended, as below) or Debug.
cd external/reframework
git pull --recurse-submodules
git submodule update --init --recursive
mkdir build64_all
cd build64_all
cmake .. -G "Visual Studio 17 2022" -A x64 -DDEVELOPER_MODE=ON
cmake --build . --config RelWithDebInfo
cd ../../This will generate the files dinput8.dll and dinput8.pdb in external/reframework/build64_all/bin/MHWILDS.
Place them in your game directory to run REFramework as a debug build.
You can then attach to the process at run-time in Visual Studio via Debug > Attach To Process... / Debug > Reattach to Process... to catch any REFramework related errors.
Make sure to set the plugin and hot-reload directories for the plugin in the configurations in CMakeSettings.json:
PLUGIN_HOT_RELOAD_DIR = <Game Directory>/reframework/data/KBF/HotReload
PLUGIN_OUTPUT_DIR = <Game Directory>/reframework/pluginsThis allows the plugin to be built straight to the correct directory without you having to move files around.
This project includes two CMake targets: KanaBodyFramework.dll and KanaBodyFramework_logic.dll.
The former being the entry point to the plugin, and the latter being an (optional) hot-reloadable .dll holding the core part of the program.
-
To build a packaged distributable (mod .zip), build the target
KanaBodyFramework.dllwith the CMake Configurationx64-Dist. This will create a new .dll under./dist/KBF/reframework/pluginsand zip./dist/KBFto./dist/out -
To build a release build (no hot-reloading) to the game's plugin folder, build the target
KanaBodyFramework.dllwith the CMake Configurationx64-Release. -
To build a hot-reloadable debug build to the game's plugin folder, build both targets:
KanaBodyFramework.dll, thenKanaBodyFramework_logic.dll, with the CMake Configurationx64-Release-HotReload/x64-Debug-HotReload.
When building via 3., you can rebuild KanaBodyFramework_logic.dll while the game is running and it will be automatically hot-reloaded to avoid having to restart your game.
❓ How do I _____ ?
Please refer to the various tutorials in the plugins UI in-game, under About > Tutorials.
✨ I'd like to suggest a feature!
Please open an issue detailing your feature request, or leave a comment on the mod's NexusMods page.
🐛 I found a bug! How do I report it?
Please open an issue and include:
- A clear description of the bug
- Whether the bug causes a game crash or just incorrect behavior
- Steps to reproduce it
- Expected vs actual behavior
- A copy of REFramework's
re2_framework_log.txt - A copy of KBF's debug log (under
Debug > Log > Copy to Clipboard), if the game doesn't crash.
I have a limited amount of time to work on this mod and track down bugs, so without the above information I may not be able to address the issue!
🛠️ How can I contribute?
Contributions are very welcome given the scale of this plugin :)
You can:
- Fork the repo
- Add new features or fix bugs
- Submit a pull request
I don't have a strict code style guide, but please try to keep your code clean and well-documented.
I'll need to be able to clearly review the changes myself so please try to keep them concise, easily understandable, and make sure to test them in-game (please try to avoid hard crashes!).
Bugs / Known Issues
| Issue | Description | Severity | |
|---|---|---|---|
| ❌ | Missing Font Symbols | Some obscure font symbols are missing as they are not included is Noto CJK. | Med |
| ❌ | Bone Cache Overwrites | Some bone caches seem to write every load - like Cypurrpunk F-F | Med |
| ❌ | Fix certain cutscenes | In certain cutscenes, player and npc list appears to populate initially, then empty themselves as the cutscene begins | Low |
Potential Features
| Task | Description | Priority | |
|---|---|---|---|
| ❌ | Randomizer | Select multiple presets to randomize between | Low |
Technical Enhancements
| Task | Description | Priority | |
|---|---|---|---|
| ❌ | Simplify adding new NPC armours | Currently lots of code areas need to be changed. E.g. Name -> ID maps | High |
| ❌ | Remove unique_ptr arrays | Switch std unique_ptr containers to std optional / extra bool in struct for performance | Med |
| ❌ | Loading Screen Optimization | Optimize loading screen over fetching (especially for npcs) | Med |
| ❌ | Armour Fetch Optimization | Armour fetch can be quite slow: ~1-2ms . This may lead to frame drop spikes. | Med |
| ❌ | Test Quest End Cutscenes | These might break with TU3 | Low |