Start here
Base game, nothing done to it yet? This is the order to do things in.
7 steps
Start here
Base game, nothing done to it yet? This is the order to do things in.
Install Modkit
The one desktop app you'll use for the rest of this, and for managing mods afterward. Get it first — you'll come back to it in a couple of steps.
Modkit →Patch the game — Modkit can't do this part
Mercenaries 2 shipped with SecuROM, DRM modern Windows frequently refuses to run
at all. Run apply_crack against your own Mercenaries2.exe
— it produces Mercenaries2-cracked.exe, patched to load the
community loader in SecuROM's place. Back up your original exe, then replace it
with the cracked one.
Get the loader itself — pmc_bb.dll
This is what your patched exe now looks for. Modkit's Setup tab downloads it for
you — the easiest way — or grab it by hand from PMC Blackbox's
releases and drop it next to Mercenaries2.exe.
Launch once and check for a console window
A command window popping up alongside the game confirms the loader is running (it prints some diagnostic info too). No window means something's off with the patch or the DLL placement — worth sorting out before adding anything else.
Install lua-bridge through Modkit
In Modkit's Mod Market, add loganw234/Merc2-Mods-Exp as a Mod
Source, then browse to lua-bridge and deploy it — this also makes future
updates a click instead of a re-download. (Or by hand: drop
lua_bridge.asi and lua_bridge.ini into
<game>/scripts/ yourself.)
Launch again and check for the script folders
scripts/OnBoot/, scripts/OnLoad/ and
scripts/OnKey/ should now exist under your game folder, along with
an auto-generated lua_loader.ini (it'll already have a few sample
lines in it — that's normal, just add yours alongside). That confirms
lua-bridge is live.
You're ready for Ess
Ess is the Lua framework nearly everything else on this page assumes. Its own guide picks up exactly where this one ends.
Ess: Getting Started →Web apps
Open in a browser tab. No install, no build step.
Lua Web IDE
ide.mercs2.tools
Write Lua in the browser and run it inside your running game. Syntax
highlighting, autocomplete for both the Ess framework and the native
engine calls, a lint pass, an examples gallery and a built-in API reference —
with results and the live game log streaming straight back to the page.
Live Map
map.mercs2.toolsAn interactive map of the whole game world. Collectible and teleport layers ship built in, and you can drag in any JSON file of world-space points to get a new toggleable layer. Connect to a running game to watch your position live and teleport straight from the map.
GFXForge
gfx.mercs2.tools
A visual editor for custom in-game UI. Lay out panels, text, buttons and menus,
script them, preview the result in the browser, then export a .gfx
movie together with the Lua host script needed to drive it in game.
Skinner
skins.mercs2.tools
Recolour and reskin characters and vehicles in the browser. Pick a donor, edit its
texture sheets (with a guided hue tool), and export either a modkit mod, a
self-installing kit, or a drop-in vz-patch.wad — recolour in place
or add your skin as a brand-new outfit selectable by name.
WAD Simulator
wad.mercs2.tools
Pack your mods into the vz-patch.wad the game loads — add, merge and
delete assets, with no command line. Every block is labelled in plain language and
marked as replacing a base-game asset or adding a new one. Packs skinner exports and
GFXForge .gfx UI movies; the browser end of the whole toolchain.
Learn
Where to find out how any of this actually works.
Modding Wiki
wiki.mercs2.toolsThe reference: engine namespaces, deep dives on individual systems, and page-by-page documentation drawn from the game's own decompiled scripts. The best starting point if you're new to modding this game.
Community Research
GitHubA large collection of notes, scripts, reverse-engineering files, asset formats and file analyses gathered around the released game.
Build with Lua
The pieces the tools above are built on.
Ess — Essentials framework
GitHub
The Lua framework most of this ecosystem targets. One Ess global covering
spawning, missions and objectives, UI widgets, AI orders, markers, camera work and
cutscenes — layered so beginners get one-line helpers and advanced users still
reach the raw primitives. Drop one file in and start scripting.
lua-bridge
GitHubThe mod that opens a socket into the running game, serving both a raw TCP REPL and a WebSocket server locally. It's what lets the Web IDE and Live Map execute Lua and read live state from a browser with no relay in between.
Utilities
Smaller single-purpose tools, all client-side.
MissionForge
on this site
Web companion to the in-game contract authoring tool. Paste a
MISSIONFORGE_EXPORT dump, refine the objectives and mission details, then
copy out a ready contract definition.
Model Rig Browser
on this siteEvery bone and hardpoint across all 329 models in the game — characters, vehicles and weapons — searchable and viewable as a live 2D skeleton.
Collision Minter
on this site
Give it a target pandemic_hash_m2 hash and get back a short string that
hashes to it — not the real name, but a working stand-in for anything reachable
only by its hash, like an unnamed bone.
Game setup
Getting a moddable copy of the game running in the first place.
You need to own the game
Everything in this section assumes you already own a legitimate, purchased copy of Mercenaries 2: World in Flames. These tools exist so that a copy you own will run and stay moddable on modern hardware — a 2008 release with long-dead copy protection that current versions of Windows often refuse to launch at all.
They are not a way to obtain, unlock or play the game without buying it, and nothing here distributes game content. Please don't use them for anything else.
Modkit
GitHub
A desktop mod manager. Load mods, detect conflicts, resolve asset collisions and
package a validated vz-patch.wad without touching a command line.
PMC Blackbox
GitHubThe ASI loader and plugin framework the community builds custom scripts and structural engine mods on top of.
SecuROM Bypass
GitHubStrips the legacy SecuROM copy protection from the game executable and patches it to load the community mod loader. SecuROM is long-dead DRM that modern Windows frequently refuses to run at all — on a delisted 2008 title, this is often the only way to actually launch a copy you already own, and it's a prerequisite for everything else here.