Difference between revisions of "MTropolis/Adding Games"

← Older edit

MTropolis/Adding Games (view source)

Revision as of 02:09, 23 September 2022

1,701 bytes added , 02:09, 23 September 2022

no edit summary

OneEightHundred

62

edits

@@ Line 1: / Line 1: @@
-This page describes guidelines for adding detection entries for mTropolis titles, and also describes file type behavior so that detection entries play nice with the mTropolis engine's boot code.
+This page describes the process for adding support for new mTropolis titles.
-Reading [[MTropolis/Common_Files_in_mTropolis_Software]] is recommended.
+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.
-Note that there appears to be a lot of quirky variation with extensions.  It appears that mFactory may have been somewhat hands-on with their users and provided custom or pre-release plug-ins, and sometimes there are variations between the Macintosh and Windows releases of the same game, so there is not a consistent pattern in which extensions have necessary data.
 ==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.
@@ Line 41: / Line 44: @@
 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 detection.
+If an extension is only used for code, then it should not be included in the boot table.
-==When to specify file type in the detection table?==
-If a file is one of the types specified above, but won't be detected as the correct type due to the extension or file type code mismatching, then you should specify the file type in the detection table.  '''This includes any data-fork-only detection for Macintosh versions''' because auto-detection for Macintosh versions requires that the files are in MacBinary format to extract the file type.
+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.
-If an extension doesn't have standard resources, its type should be MTFT_SPECIAL.
+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.
-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.
+==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.
-If a file does meet the auto-detection criteria, then you can leave its file type as 0 (MTFT_AUTO).
+===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.