MTropolis/Adding Games

This page describes the process for adding support for new mTropolis titles.

Reading MTropolis/Common_Files_in_mTropolis_Software is recommended. Unfortunately, while the file organization of mTropolis is fairly well-understood, there is significant variation in how those files are organized on CD-ROMs. Most mTropolis games are designed to have an installed part and an on-disc part instead of launching the game executable from the CD-ROM, and the installed part can have renamed extensions (such as replacing the last character with an underscore) or be inside of archives.

Additionally, it appears that mFactory may have been more hands-on with customers than, say, Director, and provided pre-release versions and plug-ins, so there are significant variations in plug-in usage.

To handle this, all mTropolis games added to detection must have a "boot ID" that points to a boot table entry that determines how to boot the game. There is not currently a "generic" boot process for unsupported games because every game identified so far has required custom handling. All boot handling is done in engines/mtropolis/boot.cpp.

Types of files

mTropolis games are loaded using a mTropolis Player executable combined with a "resource" folder containing plug-ins and the title data segments.

The player executable

There is one player executable, it should be included in detection as it contains cursor resources. The default names are "MTPLAY31.EXE" for Windows 3.1, "MTPLAY32.EXE" for Windows 95/NT, and "mTropolis Player" for Macintosh, but the game can rename the player executable to anything. Only add the highest supported architecture if there are multiple player executables.

The game data segments

A mTropolis project consists of a main segment and additional segments. Macintosh projects may not have a file extension, in which case the type is determined by the Macintosh file type code.

It is possible for a game to have multiple projects.

Main segment+Additional segment identification is as follows:

Macintosh type codes:

• mTropolis 1.x Macintosh project: MFmm+MFmx
• mTropolis 2.x Macintosh project: MFmm+MFxm
• mTropolis 2.x cross-platform project: MFmx+MFxx

Windows extensions:

• mTropolis 1.x Windows project: .MPL+.MPX
• mTropolis 2.x Windows project: .MFW+.MXW
• mTropolis 2.x cross-platform project: .MFX+.MXX

The main segment is detected as MTFT_MAIN and additional segments as MTFT_ADDITIONAL.

Extensions

Extensions have a 3-character extension where the last 2 characters correspond to the architecture: "31" for Windows 3.1, "95" for Windows 95/NT, "PP" for PowerPC Macintosh, and "68" for 68k Macintosh. The first character of the extension varies and is inconsistent, it appears to be for convenience only and not something that affects how the file is loaded. First characters are typically "X" or "E" for code extensions, "C" for cursor packs, and "R" for resources.

Extensions are automatically detected as the MTFT_EXTENSION type.

Extensions included in the detection tables with the MTFT_EXTENSION type are expected to have standard resources, which currently means cursors. You can check if a Macintosh-version extension has cursors using ResEdit on a Mac, or if a Windows-version extension has it by using a tool such as Resource Hacker. If an extension is detected as MTFT_EXTENSION but does not have standard resources, the boot code will raise a warning.

Which files to include?

Always include the player executable, any data segments, and any extensions with standard resources.

If an extension does not have standard resources, but has some other use, then you should include the extension, but you should set the file type to MTFT_SPECIAL.

If an extension is only used for code, then it should not be included in the boot table.

If a file is required for some reason other than mentioned above (including things like installer archives), then you should specify its type as MTFT_SPECIAL.

Data handlers

Data handlers can be used to unpack files and add plug-ins required to start the game. The most important things are the overrides for "unpackAdditionalFiles" and "addPlugIns"

To unpack files from an installer, you should unpack the files and add FileIdentifications, which can contain MacResManagers and/or SeekableReadStreams for the file contents.

You can also add persistent resources to the persistent resources list, which are arbitrary things that persist until the game is completely unloaded. If, for example, the SeekableReadStream for a file requires that an installer archive object stays alive, you can use a persistent resource wrapper to keep it alive.

Adding a boot table entry

The boot table is MTropolis::Boot::games in boot.cpp. Table entries consist of 5 fields:

The boot ID

The boot ID is a unique identifier that corresponds to an entry in MTropolisGameBootID in detection.h. There should only be one boot table entry per boot ID. All detected games must specify a boot ID, but if multiple games have identical boot handling, they can share a boot ID.

The file manifest

This points to a list of ManifestFiles naming each file to load. The list should end with {nullptr,MTFT_AUTO}

The directories list

This points to a list of subdirectories to search for files in. It should end with nullptr.

The subtitles definition

This points to a subtitle definition. Subtitles are not a standard mTropolis feature, so there will only be subtitles if someone adds them. If there is no subtitles definition, this should be nullptr.

The data handler factory

If the game has special data handling or plug-ins, then this should be filled in with the "create" method of a specialization of GameDataHandlerFactory that creates a data handler for the game.