What Is Crossmatching in BuildGDX and How Does It Affect Game Compatibility?

Crossmatching, in the context of BuildGDX and similar source ports, refers to matching the right game data files, addons, and configuration settings to the correct game module so the port can load and run them properly. It matters most when you are running multiple Build Engine titles through one port family, or when you install addons and maps that were built for a specific game. If the match is wrong, the game may crash, load the wrong resources, or fail to find levels and sounds. The M210 Projects site documents BuildGDX releases and fixes that directly affect how these matches are handled, including addon finding, savegame loading, and map info indexing.

How Crossmatching Works in BuildGDX

BuildGDX is a port family, not a single game engine. It includes separate modules such as BloodGDX, DukeGDX, TekwarGDX, WangGDX, and LSPGDX. Each module expects game data that belongs to its own title. Crossmatching is the process of making sure:

• The game data files you point the port to are the correct ones for that module.
• Addons and maps are associated with the game they were designed for.
• Configuration values such as useHighTiles, useModels, and map info indices line up with the loaded content.

The release notes show that this matching is not automatic in every case. For example, BuildGDX v1.18 includes a fix for DukeGDX "Improved con addon finding (when definevolumename is not defined, but definelevelname is)." That is a crossmatching fix: the port now finds addons even when one expected definition is missing but another is present.

Why Crossmatching Affects Compatibility

When crossmatching fails, the symptoms are usually one of these:

• The game starts but loads the wrong sky, tiles, or models.
• Addons do not appear in the menu or fail to launch.
• Savegames fail to load or crash.
• The port crashes when loading a map with broken sectors.
• Music or sound does not play because the wrong audio path is used.

The v1.18 changelog lists several fixes in this area:

• "BloodGDX: Fixed loading extra data in savegame files (after remove support of old dos saves)"
• "DK / RR setMapInfo index protect"
• "DK / RR genspriteremaps() corrupted lookup.dat doesn't close the port now"
• "DK / RR sndPlayMusic with oggmusic crash fix"

Each of these is a case where data from one source was being matched incorrectly against the game module's expectations.

Crossmatching Across Different Game Modules

The same port codebase handles different games, but the matching rules differ per module. The table below summarises what the release notes indicate for each.

This shows that crossmatching is not one single feature. It is a set of per-game data and resource matching behaviours.

Common Crossmatching Problems and How to Resolve Them

If you are running into what looks like a crossmatching issue, work through these steps.

1. Confirm you are using the correct module for the game

Blood data must go to BloodGDX, Duke3D data to DukeGDX, and so on. Do not point DukeGDX at Blood files or vice versa. The port may start but will fail to match resources.

2. Check your addon definitions

For DukeGDX, the v1.18 fix specifically addresses addons where definevolumename is not defined but definelevelname is. If an addon does not appear, verify that its definition file contains at least one of these. If you are on an older BuildGDX version, updating to v1.18 or later may resolve the issue without further changes.

3. Verify map info indices

The "DK / RR setMapInfo index protect" fix in v1.18 suggests that out-of-range or mismatched map info indices could previously cause problems. If you are loading custom maps and seeing incorrect behaviour, check that the map info entries in your configuration match the maps you have installed.

4. Watch for corrupted lookup data

The fix for "genspriteremaps() corrupted lookup.dat doesn't close the port now" means that a corrupted lookup.dat used to close the port. In v1.18 and later, the port handles this more gracefully. If you are on an older version and the port closes unexpectedly when loading certain content, this may be the cause.

5. Update to the latest BuildGDX

The v1.18 release (11 January 2025) contains the most recent crossmatching-related fixes. If you are on v1.17 (23 August 2024) or earlier, updating is the most direct way to get these fixes. Note that v1.17 increased the savegame version and changed the config file version, so savegames and configs from older BuildGDX versions may not be compatible.

What to Check Before Reporting a Crossmatching Bug

• Confirm the BuildGDX version you are running.
• Confirm which module (BloodGDX, DukeGDX, etc.) you are using.
• Confirm the game data version and the addon or map you are loading.
• Check whether the issue is listed as fixed in a later release than the one you have.

The M210 Projects site lists releases with dates and changelogs, so you can compare your version against the documented fixes. If the issue is already fixed in a newer release, updating is the first step. If it is not listed, the changelog entries give you the specific terms (such as definevolumename, lookup.dat, or setMapInfo) to use when describing the problem.