v0.1.0

H7ModEngine v0.1.0

The first release of H7ModEngine, a Lua 5.4 modding engine for Might & Magic Heroes VII.

Mods are plain Lua files. They can read and change any game object, call any UnrealScript function, and hook game functions to watch, change or block what they do. You turn mods on and off, and change their settings, from a new Mods entry in the main menu.

The engine doesn't change any game files or code on disk. It finds what it needs in memory when the game starts.

Installation

1. Download dinput8.dll below.
2. Put it in <Game>\Binaries\Win64\ (the folder that contains MMH7Game-Win64-Shipping.exe).
3. Start the game through Ubisoft Connect as usual.

That's all. On the first start the engine creates <Game>\H7ModEngine\ with its settings file, the Mods menu and a mods\ folder. The main menu now has a Mods entry, and the log is in <Game>\H7ModEngine\logs\engine.log.

Example mods (optional): download H7ModEngine-examples.zip and unzip it into the game folder (the folder that contains Binaries). The examples are off by default. Turn them on in the Mods menu.

Uninstall: delete <Game>\Binaries\Win64\dinput8.dll. Also delete <Game>\H7ModEngine\ if you don't want to keep your mods and their saved data.

Requirements

• Might & Magic Heroes VII v2.2.1, 64-bit, Windows (the Ubisoft Connect version). Other versions may not work.
• Single player. Multiplayer is untested and will probably desync when a mod changes gameplay.

What's included

For players

• Mods menu in the main menu, built on the game's own map selection screen. It lists every installed mod with its version, category, author and description.
• Enable or disable mods live. Changes apply right away and are saved in H7ModEngine.ini.
• Mod settings in the menu (sliders, check boxes, option arrows and number boxes) for every mod that has settings.
• Mod errors never crash the game. They are logged with a stack trace.

For modders

• Full access to game objects: read and write properties in place (including structs and arrays), call UnrealScript functions with normal Lua arguments, and look up every class, enum and function by name.
• Hooks on any UnrealScript function, including script-to-script calls: run code before or after a function, read and change its arguments, block it, or replace its return value.
• Create engine objects from Lua (h7.new_object, h7.clone).
• Events and timers: every frame, map changes, mods loaded or toggled; timers on game time.
• Mod structure: a mod.lua manifest (name, version, author, description, category, load_after, enabled, settings), load order, separate globals for each mod, and saved data that persists between sessions.
• Hot reload: save main.lua while the game runs and the mod reloads within about a second.
• Development tools: an exec folder that runs Lua in the running game, a detailed log, and an index of every engine object written at startup (DumpSDK in H7ModEngine.ini).

A minimal mod:

-- <Game>\H7ModEngine\mods\DailyGold\main.lua: the human player gets 500 gold every new day
h7.hook_post("MMH7Game.H7Calendar.NextDay", function(calendar)
    local controller = h7.first("H7AdventureController")
    local player = controller and controller:GetLocalPlayer(true)
    if not player then return end
    player:GetResourceSet():ModifyCurrency(500, true)
end)

Example mods (H7ModEngine-examples.zip)

Mod	What it does	Settings
HelloWorld	Logs a greeting, counts launches and session time	none
DailyGold	The human player gets bonus gold every new day	Gold per day
CombatXP	Heroes earn more experience from combat	XP multiplier
DamageScale	Scales all combat damage	Damage multiplier, log hits
HeroMovement	Heroes get more movement points per day	Movement multiplier, whose heroes

Documentation

• Modding guide and full API reference: https://whaileee.github.io/H7ModEngine/
• API.md is also in the examples zip.
• Building from source: see the README and docs/DEVELOPMENT.md in the repository.

Known limitations

• Works only with game version 2.2.1 (64-bit).
• Single player only; multiplayer isn't supported.
• This is an early release: the API may still change before 1.0.