← MekEngine

Making MekEngine Mods

MekEngine mods replace the original game's data with files of your own. You don't need any tools or need to repack anything. A mod is a folder of loose files laid out like the game's data files, and MekEngine uses your file wherever the game would have used its own.

Mods work in every edition of MechWarrior 2 (DOS, Pentium, 3Dfx, Matrox, S3 Virge, ATI Rage, PowerVR, BattlePack…). You don't need to make a separate version for each one.

What can be modded today:

• Shell (menu) music: recordings replacing the MIDI songs (section 4).
• World, mech and building textures: images replacing the CEL textures (section 5).

Other kinds of data (sounds, menu pictures, …) will follow the same folder and naming rules as support is added.

Coming soon: models. Models can't be replaced yet, but you can already dump the originals to a standard 3D format and start working (section 6).

Demonstration mods

Two small mods to try, or to pull apart and see how a mod is made:

Each zip contains a Mods folder. Extract it into the folder that holds MekEngine, so the mod lands in Mods next to the MekEngine folder. Then turn it on from Mods on the Choose Edition screen.

1. Where mods go

Mods live in a folder named Mods that sits next to the folder MekEngine is in:

SomeFolder/
  MekEngine/          <- the game (MekEngine.exe)
  Mods/               <- mods go here
    MyFirstMod/
    AnotherMod/
    loadorder.txt     <- written by the game; you don't need to touch it

Each mod is one folder inside Mods. The folder's name is the mod's ID.

2. Turning mods on and off

On the Choose Edition screen (the first screen at launch), click Mods.

• Click a mod's box (or select it and press Space) to turn it on or off. A green X means it's on and a grey – means it's off.
• The number on the right (#1, #2…) is its place in the load order. Turning a mod on puts it at the end.
• Select a mod and use Move Up / Move Down to change its place.
• When two mods replace the same file, the one further down the list wins.
• The panel at the bottom shows the selected mod's description (see mod.txt below).

Your choices are saved in Mods/loadorder.txt.

3. Anatomy of a mod

MyFirstMod/
  mod.txt                     <- optional: title and description
  DATABASE.MW2/               <- replacements for things in DATABASE.MW2
    43.flac
    43.loop.txt
  MW2.PRJ/                    <- replacements for things in MW2.PRJ
    CEL/
      L1GOSTBR.png

mod.txt

This file is optional. The first line is the mod's title and everything after it is the description shown in the Mods screen. If there's no mod.txt, the folder name is used as the title.

GhostBear 2 MoonBunny
Replaces the Ghost Bear clan emblem with the MoonBunny emblem.

Mirroring the game's data files

The game keeps its data in a few big files. Inside your mod, each data file becomes a folder with the same name, and things inside it are laid out the way the data file organizes them:

Naming a replacement

Name a replacement after the original, then add your file's real extension. For example:

Items in DATABASE.MW2 have no names, so they're named by their item number in plain decimal (43, not 0x2B).

MekEngine checks that your file is a format it can use for that thing. A file in a format it can't use is skipped, and a warning is written to the log.

Don't put two replacements for the same thing in one mod (e.g. both 43.flac and 43.wav). If you do, MekEngine uses whichever file it finds first. The load order decides between different mods, not within one.

Pointer files (share one file, save space)

A file named exactly like the original, with no extra extension, is a pointer. It's a plain text file holding a relative path to the real file:

MW2.PRJ/CEL/L2GOSTBR          <- text file containing:  L1GOSTBR.png
MW2.PRJ/CEL/L1GOSTBR.png      <- the real image

• The path is relative to the pointer's own folder.
• It must stay inside your own mod. Pointers into other mods or outside Mods are refused.
• The file it points to must still be a format that's allowed for the thing being replaced.

For things with no name (database items), the pointer is the bare number: a text file called 43.

Companion files

Some replacements can have a small companion file named <original>.<something>.txt, such as 43.loop.txt. Companions are never mistaken for replacements. A companion is only read from the same mod that supplied the replacement it belongs to.

4. Shell music

The music in the menus (the "shell") is MIDI stored in DATABASE.MW2. You can replace each song with a recording.

Formats: FLAC, WAV, OGG, MP3. Any sample rate or bit depth works. FLAC is recommended because it's lossless and about half the size of WAV.

Songs:

MyMusicMod/
  DATABASE.MW2/
    43.flac
    43.loop.txt     <- optional

The song behaves like the original: it loops forever, follows the music volume setting, and pauses when you switch to another program.

Looping: <item>.loop.txt

If there's no loop file, the whole recording loops, with a short 50 ms crossfade from its end back into its start.

For a seamless loop, add a loop file next to the song:

start=11.975
end=117.108

• Times are in seconds, with a decimal point. Lines starting with # or ; are comments.
• start is where each repeat begins (default: the start of the file).
• end is where each pass ends and the next one begins (default: the end of the file).
• **Anything after end is the "tail".** When a pass reaches end, the next pass starts from start right on time, while the old pass keeps playing its tail (the reverb and decay of the last notes) underneath, fading out at the end of the file. This way the reverb carries over into the repeat instead of cutting off.

So the best recording is: the song from the very first note, played through past its loop point, with a few seconds of tail at the end. Then put the loop point in loop.txt.

Original loop points (in seconds from the first MIDI event):

These only apply if your recording follows the original MIDI timing exactly, starting the instant the first MIDI event plays. If you recorded a different arrangement, a different tempo or your own song, use your own times.

5. Textures

World, mech and building textures are CEL resources in MW2.PRJ. You can replace them with images.

Formats: PNG or TGA (raw or RLE; true-colour, greyscale or colour-mapped).

Where: MW2.PRJ/CEL/

Naming

Every edition names the same texture with a different extension:

You can name your replacement any of these ways. It's used in every edition whichever one you pick:

• A9BLAH01.png: by its stem. This is the usual choice.
• A9BLAH01.555.png or A9BLAH01.SGL.png: by a full name.
• A9BLAH01.XEL.png: a paletted texture (see below).

Any size, same shape on the model

A replacement is a drop-in: it always fills exactly the area the original covered on the model, whatever its size. A 1024×1024 image replacing a 64×32 texture is stretched to fill that 64×32 area, keeping its 2:1 shape on the model. It doesn't take a 64×32 corner out of your image.

So draw your image to the same aspect ratio as the original, at whatever resolution you like.

Replacements are drawn with smooth filtering (mipmaps, trilinear, anisotropic). The originals are drawn blocky.

Transparency

Your image's alpha channel is used as transparency. The engine dithers partial alpha, so soft edges come out as dithered coverage. Save as RGBA if you want any transparency. An image without alpha is fully opaque.

Paletted textures (.XEL.png)

If you name the file <name>.XEL.png (or .XEL.tga), the image is treated as paletted, the way the DOS editions' textures are:

• the red channel is the palette index (0–255);
• green and blue are ignored;
• alpha is still transparency.

MekEngine colours it with the same palette the original texture would get, including the darker palettes of night missions. A paletted replacement follows the mission's time of day; a full-colour one looks the same day and night.

Dumping the original textures

Start MekEngine with the -dumptextures switch to get every texture as a PNG:

bin\MekEngine.exe -dumptextures

(Or add -dumptextures to the target of a shortcut to MekEngine.exe.)

Pick an edition as usual. Before the intro plays, MekEngine writes all of that edition's textures to a TextureDump folder next to Mods. Then the game carries on normally. TextureDump is laid out exactly like a mod:

TextureDump/
  MW2.PRJ/
    CEL/
      L1GOSTBR.555.png
      L1GOSTBR.555.alpha.png
      ...

• 3Dfx, Matrox, S3, ATI, PowerVR: each texture comes out as MekEngine draws it. <name>.png is how opaque faces show it, and <name>.alpha.png is the version with alpha that transparent faces use. On PowerVR, small textures that sit in the corner of a bigger map are cut down to just the art.
• DOS, Pentium, BattlePack: each texture comes out as a greyscale index map, <name>.XEL.png: grey level = palette index, and index 255 is transparent. Its name already makes it a paletted replacement (see above), so you can edit it and drop it back in.

To use a dumped texture, copy it into your mod's MW2.PRJ/CEL/ folder and edit it. Paint at any resolution you like, as long as you keep the aspect ratio. Rename a .alpha.png file to drop the .alpha (for example L1GOSTBR.555.png, or just L1GOSTBR.png). Delete TextureDump when you're done; MekEngine doesn't read it.

Finding texture names

The easiest way is to dump the textures (above) and look through them. Otherwise:

Texture names are 8 characters, and many follow a pattern. For example, the clan emblems:

Not yet replaceable: menu pictures, the mouse cursor, fonts, cockpit HUD art and videos.

6. Models (coming soon)

Model replacement mods aren't supported yet. The -dumpmeshes switch is available now so that artists can get to work early, and help shape how model support is built. If you start on a model, come talk about what you need from the importer on the Discord.

Dumping the original models

Start MekEngine with the -dumpmeshes switch:

bin\MekEngine.exe -dumpmeshes

(Or add -dumpmeshes to the target of a shortcut to MekEngine.exe. It can be used together with -dumptextures.)

Pick an edition as usual. Before the intro plays, MekEngine writes all of that edition's models to a MeshDump folder next to Mods. Then the game carries on normally. Like TextureDump, it's laid out like a mod:

MeshDump/
  DUPLICATES.txt        <- pieces shared by more than one model
  MW2.PRJ/
    BWD/
      <name>.glb        <- mechs, vehicles, turrets, doors, ...
    POLY/
      <name>.glb        <- buildings, props and other single shapes
    CEL/
      <name>.png        <- the textures the models use
      <name>.alpha.png

The models are glTF 2.0 (.glb), which most 3D programs can open. In Blender, use File → Import → glTF 2.0. The textures are separate PNGs that the models find through the CEL folder next to theirs, so keep the folders together when you copy them.

What's in a dumped model

• BWD/ holds the game's objects: things built from several pieces that move against each other, such as mechs (legs, torso, arms…), vehicles and turrets. Each piece is its own node, named after its shape and placed at its joint under the piece it hangs from, so the hierarchy is the one the game animates. Empty attachment points come out as nodes named DUMMY_<number>.
• POLY/ holds every shape that isn't part of an object: buildings, props and so on, each as a single mesh.
• Only the highest detail level is dumped. That's the only one MekEngine draws.
• Textures and colours are the ones the edition's first mission uses, with the default faction colours. On DOS, Pentium and BattlePack the textures come out in full colour, not as the grey index maps -dumptextures writes.
• Faces that the game draws at full brightness use unlit materials. Faces with no texture get a plain colour material.
• Textures are set to blocky (nearest) filtering, the way the originals are drawn.
• Mods are left out: the dump is always the original game data.

Shared pieces: DUPLICATES.txt

Many models share pieces. For example, several mechs can use the same shape for a part. Each dumped .glb has its own copy, but in the original game it's one shape. DUPLICATES.txt lists each group of models and the pieces they all share.

Delete MeshDump when you're done; MekEngine doesn't read it.

7. Example: replacing a clan emblem

Mods/
  GhostBear2MoonBunny/
    mod.txt
    MW2.PRJ/
      CEL/
        L1GOSTBR.png      <- RGBA image, any size, square
        L2GOSTBR          <- pointer file containing: L1GOSTBR.png

mod.txt:

GhostBear 2 MoonBunny
Replaces the Ghost Bear clan emblem with the MoonBunny emblem.

Turn it on from Mods on the Choose Edition screen and start a Ghost Bear mission.

8. Example: a recorded soundtrack

Mods/
  MoonMusic/
    mod.txt
    DATABASE.MW2/
      43.flac   43.loop.txt
      44.flac   44.loop.txt
      ...
      46.flac   46.loop.txt     <- start=11.975 / end=117.108
      ...

9. Troubleshooting

• My mod doesn't show up. Check that it's a folder directly inside Mods, next to the MekEngine folder. If the Mods screen finds no mods at all, it shows the folder it looked in.
• It shows up but nothing changes. Is it turned on (green X)? Is a mod further down the list replacing the same thing? Check the file name: the name, then exactly one extension (43.flac, L1GOSTBR.png), or the original name and then your extension (L1GOSTBR.555.png).
• It still doesn't work. MekEngine writes a line to its log for each file it skips, such as a wrong format, a bad pointer or an unreadable file. Look for lines starting with Mods:, TextureMods: or ShellAudioSequence:.
• My texture has a black (or white) box around it. The image has no alpha channel. Re-save it as RGBA, with the background transparent.
• The music loop jumps. Check loop.txt: the times are in seconds from the very start of your file, and end must be after start.