H7ModEngine 0.2.1 (Multiplayer: opt-in desync reports)

H7ModEngine 0.2.1

Multiplayer: opt-in desync reports

OnlineLobby (0.3.0) has a new setting, Send desync reports (Mods menu → OnlineLobby). It is off by default.

When it's on and a multiplayer game goes out of sync, or a command reaches the other PC too late to be applied, your
game sends a short report to the community lobby. The report holds the last few hundred multiplayer events (commands,
turn counters, random rolls, heroes, armies and resources) and your game, engine and mod versions. The reports help
track down and fix the game's multiplayer desyncs, and they help most when every player in a game turns the setting on.

• No player or profile names, IP addresses or save games are sent.
• At most 3 reports per game, up to 96 KB each. The lobby keeps them for 30 days.
• With the setting off, online play works exactly as in 0.2.0.

For mod makers and testers

• MPSyncDebug (new; Developer category, off by default): writes a full multiplayer trace of each game to
  H7ModEngine\logs\mpsync-<host|client>-<time>.log. The trace covers every command and turn-counter step, synced random
  rolls, the game's own out-of-sync checks, commands that arrive too late, frame gaps (for example while a player
  alt-tabs) and state snapshots. Developer mods don't count as gameplay mods, so the lobby browser doesn't flag a host
  for running it.
• New shared library lib\mpsync.lua (the multiplayer tracer), installed by the DLL and used by both mods above.
• Repository tools: tools/mpsync_diff.py compares two players' traces and points at the first difference;
  tools/fetch_reports.py downloads desync reports from the lobby (admin only) and compares each game's pair.
• docs/DESYNC.md: how the game keeps players in sync, and why a host alt-tabbing can break it.

Installing / upgrading

Replace Binaries\Win64\dinput8.dll. On the next start it updates OnlineLobby and installs MPSyncDebug and
lib\mpsync.lua. All players in a game should use the same version: the online browser marks a host running a
different engine version as "Differs".

H7ModEngine 0.2.0 — Online multiplayer is back

Heroes VII's Online menu works again. Ubisoft's online services are shut down, so H7ModEngine now ships with
OnlineLobby, a bundled mod that hosts games over the game's own LAN code and lists them in a free community
lobby. Mods also get a networking API.

Install / update

1. Download dinput8.dll below.
2. Put it in <Game>\Binaries\Win64\. Replace the old one if you're updating.
3. Start the game. The engine unpacks its bundled mods (ModManager, DebugConsole, OnlineLobby) into
   <Game>\H7ModEngine\ and keeps your settings.

Every player in a game needs this version. 0.1.x can still browse and join, but can't host on the public lobby,
and shows 0.2.0 games as "Differs".

Online multiplayer

Hosting: Multiplayer → Online → Create, then set up the game as usual.

• Your PC is the server and other players connect straight to it. No game traffic goes through any server.
• The mod opens UDP and TCP port 27015 on your router through UPnP and lists the game in the online lobby.
• Before listing it, the lobby checks that your PC is reachable and really is the one hosting.
• If something would stop players from reaching you, you get a popup saying what to change: the router port, or
  Windows Firewall.
• Starting the game or leaving the lobby takes it off the list.

Joining: Multiplayer → Online → Join.

• The browser lists open games: Host | Map | Players | Version | Status, with the map picture and the game's
  settings (turns, skills).
• Status is "Compatible", or names what differs from your game: game version, engine version, edition
  (base or modded), community content in CookedPC (by pack and version), or gameplay mods.
• Joining a game that differs asks first and lists the differences. Mismatched content can make a game go out of
  sync, so join anyway at your own risk.
• Refresh reloads the list.

Safety:

• Verified hosts only: the lobby lists a game only after the host's PC answers a check proving it holds that
  game's secret. A listing can't point you at someone else's computer.
• No downloads: your game no longer downloads packages from a host.
• No redirects: if a host tries to send your game to a different address, you're disconnected instead (setting
  Block redirects).
• Limits: the lobby limits how many games and registrations come from one address, and abusive address
  ranges can be banned.

Settings (Mods → OnlineLobby):

• UPnP: open the ports on your router automatically.
• Show mismatched games: list games that differ from yours.
• Block redirects

The lobby address is in H7ModEngine.ini under [Online] LobbyUrl. You can run your own lobby: see
H7Lobby.

If players can't join your game

• Ports: forward UDP and TCP 27015 to your PC in your router if UPnP is off or unsupported. The popup
  names your PC's local address.
• Windows Firewall: allow Might & Magic Heroes VII (MMH7Game-Win64-Shipping.exe) for Private and Public
  networks in Windows Defender Firewall → Allow an app through firewall. Windows may ask once the first time
  you host.
• Shared internet address: some internet providers share one public address between customers, and then
  nobody can reach your PC from outside. Play over a virtual LAN (Tailscale, ZeroTier, Radmin VPN) and use the
  LAN menu instead.
• H7ModEngine\logs\engine.log says which port the game listens on and what the firewall allows.

For modders

New API (reference: API docs):

• h7.http.request / get / post / cancel: HTTPS requests on background threads; the callback runs on the game
  thread.
• h7.json.encode / decode / array / null
• h7.net.upnp_add / upnp_remove / local_ip: router port mapping and this PC's LAN address.
• h7.net.udp_ports / firewall_check: the game's open UDP ports and Windows Firewall's verdict.
• h7.net.set_lan_host: point a server-browser entry at any host, joinable through the game's own join.
• h7.net.responder_start / responder_stop: the online lobby's host check.
• h7.crypto.sha256 / hmac_sha256 / random_hex
• h7.game_content(fn): community content packs in CookedPC with version hashes.
• h7.version is "0.2.0".

Other changes

• The engine retries its startup calibration for up to a minute instead of disabling mods when the game loads
  slowly.
• If your router sends a garbled reply, UPnP retries once.

Known issues

• A full online match between two PCs has been played in one direction only. In the other direction, joining
  timed out on the host's side; this release adds the checks to diagnose it. Please report problems with both
  players' engine.log.
• Heroes VII's own multiplayer desync bugs are not fixed yet. docs/DESYNC.md describes the plan.
• Third-party firewalls and antivirus suites aren't checked; only Windows Defender Firewall is.

H7ModEngine is an unofficial fan project, not affiliated with or endorsed by Ubisoft.

🤖 Generated with Claude Code

v0.1.1

H7ModEngine v0.1.1

This release adds an in-game debug console for mod makers, a few new API functions, and puts the project under the Apache License 2.0.

Installation

Same as before: download dinput8.dll below and put it in <Game>\Binaries\Win64\ (replace the old one). The new DLL updates the Mods menu and installs the DebugConsole mod on the next start; your mods, settings and saved data stay as they are.

Example mods (optional): H7ModEngine-examples.zip, unzipped into the game folder (the folder that contains Binaries).

What's new

Debug console

A Lua console drawn over the game, for writing and testing mods without leaving it. It is a mod, DebugConsole, off by default: turn it on in the Mods menu (category Developer), then press ~ (the key left of 1). The key can be changed in H7ModEngine.ini:

[Console]
Key=Tilde

• Shows the engine log live; runs Lua (an expression prints its value) or game console commands (/Stat FPS).
• One-time scripts: type or paste (Ctrl+V) several lines. Enter on an unfinished block (for i = 1, 3 do) starts a new, indented line; the script runs once it is complete.
• Suggestions as you type, each with its kind, signature and declaring class: game commands (only the ones this build accepts), Lua globals, table fields, and the properties and methods of game objects, also after lookups such as h7.first("H7AdventureHero"):Get.
• Parameter hints while typing arguments, with the current argument underlined:
  find_all(class: string | Class, include_templates?: bool) -> Object[]
• History is saved between sessions; the game doesn't receive the keyboard while the console is open.

For modders

• h7.log_lines([after]): the recent log lines (for in-game viewers).
• h7.config(section, key [, default]): read values from H7ModEngine.ini.
• h7.clipboard([text]): read or set the clipboard text.
• h7.properties entries have a new type_name field with the UnrealScript type (Vector, array<H7Creature>).
• The API reference now shows typed signatures: https://whaileee.github.io/H7ModEngine/

License

H7ModEngine is now licensed under the Apache License 2.0 (see LICENSE). Lua is MIT-licensed. Might & Magic Heroes VII and its content belong to Ubisoft.

Requirements

• Might & Magic Heroes VII v2.2.1, 64-bit, Windows (the Ubisoft Connect version).
• Single player only; multiplayer isn't supported.

Full changelog: v0.1.0...v0.1.1

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.