37
edits
Difference between revisions of "Advanced Detector"
Jump to navigation
Jump to search
Added instructions for using the special prefixes in ADGameFileDescription. Added a comment to the ADGF_MACRESFORK game flag info, marking it as deprecated.
(Update id info) |
Fracturehill (talk | contribs) (Added instructions for using the special prefixes in ADGameFileDescription. Added a comment to the ADGF_MACRESFORK game flag info, marking it as deprecated.) |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 68: | Line 68: | ||
In the running mode Advanced Detector tries to match as much information stored in the config game entry as possible. The typical keys it matches against are '''gameid''', '''platform''' and '''language''', but it may also use '''extra''' when instructed to do so. | In the running mode Advanced Detector tries to match as much information stored in the config game entry as possible. The typical keys it matches against are '''gameid''', '''platform''' and '''language''', but it may also use '''extra''' when instructed to do so. | ||
In case there are no matches in the ''ADGameDescription'' list, there are two additional fallback detection modes. One is file-based detection, which matches just the file names, and second one is a hook which gets called and could contain code of any complexity. The most prominent example of advanced fallback detection is SCI engine. | In case there are no matches in the ''ADGameDescription'' list, there are two additional fallback detection modes. One is file-based detection, which matches just the file names, and second one is a hook which gets called and could contain code of any complexity. The most prominent example of advanced fallback detection is SCI engine. Note that by default the file-based fallback detection doesn't allow to add the games to ScummVM or start them, and is only used to report to the user that a possible unknown variant was found. This behaviour can be changed by reimplementing <syntaxhighlight lang="cpp" inline>bool canPlayUnknownVariants() const</syntaxhighlight > to return true in the derived class. | ||
=== Generated targets === | === Generated targets === | ||
| Line 170: | Line 170: | ||
'''fileSize''' -- file size in bytes. Optional too, set to -1 in order to match against any file size. | '''fileSize''' -- file size in bytes. Optional too, set to -1 in order to match against any file size. | ||
=== Special prefixes === | |||
The structure can be used to request some additional detection features by adding the following prefixes to the '''md5''' field: | |||
* <code>t:</code> The specified MD5 checksum is counted from the tail of the engine. Equivalent to the '''ADGF_TAILMD5''' ADGameFlag. | |||
* <code>r:</code> The provided file is in MacBinary format. The provided md5 sum is of the file's Resource fork. | |||
* <code>d:</code> The provided file is in MacBinary format. The provided md5 sum is of the file's Data fork. | |||
* <code>A:</code> The provided checksum is for a file embedded inside an archive. See details below. | |||
=== Scanning inside archives === | |||
In cases where a game was distributed in a compressed format and all its files have commonly-encountered names (e.g. "data1.cab"), we want to avoid adding the archive files to detection entries, since they can generate false positives when detecting, Thus, it becomes useful for the Advanced Detector to scan for files inside these archives. This is supported by doing the following: | |||
* Adding an <code>A:</code> prefix to the '''md5''' field. | |||
* Using the <code><archive type ID>:<archive name>:<file name></code> syntax in the '''fileName''' field. | |||
As an example, the following structure will match with an InstallShield cabinet named "data1.cab", which contains a file named "file.dat". Advanced Detector will extract that file, calculate its checksum, and compare it against the one provided in the '''md5''' field: | |||
{ "is:data1.cab:file.dat", 0, "A:0ea0755ce0254cbce1cd21841ab1b83a", 4480956 } | |||
This is currently only supported for InstallShield v3 cabinets (using the <code>is3:</code> prefix), and InstallShield v5-v13 cabinets (using the <code>is:</code> prefix). | |||
== Game Entry flags ADGameFlags == | == Game Entry flags ADGameFlags == | ||
| Line 175: | Line 193: | ||
Game flags are used to tell the engine which features this particular game has. There are both engine-specific and Advanced Detector-specific game flags. The latter, besides being more or less universal, also affects the detection behaviour. | Game flags are used to tell the engine which features this particular game has. There are both engine-specific and Advanced Detector-specific game flags. The latter, besides being more or less universal, also affects the detection behaviour. | ||
'''ADGF_ADDENGLISH''' -- Used for dual language games. In this case the user will be presented with a selection between localised and English | '''ADGF_ADDENGLISH''' -- Used for dual language games. In this case, the user will be presented with a selection between the localised and English versions of the game. Affects GUIOs. | ||
'''ADGF_AUTOGENTARGET''' -- Used for games without distinct gameid, usually fanmade. In this case, the '''extra''' field will contain the full game name, and it will be used for generating the target name instead of a generic engine-based one. See the WAGE engine for a good example. | |||
'''ADGF_CD''' -- Specifies a CD version. Generated target will get '-cd' suffix. | '''ADGF_CD''' -- Specifies a CD version. Generated target will get '-cd' suffix. | ||
| Line 183: | Line 203: | ||
'''ADGF_DROPLANGUAGE''' -- the generated target will not have a language specified. Used mainly for multilanguage games which have language selector internally. Thus the language will be selected within the game and the setting stored in the config file, but the game entry will stay intact. | '''ADGF_DROPLANGUAGE''' -- the generated target will not have a language specified. Used mainly for multilanguage games which have language selector internally. Thus the language will be selected within the game and the setting stored in the config file, but the game entry will stay intact. | ||
'''ADGF_MACRESFORK''' | '''ADGF_DROPPLATFORM''' -- the generated target will not have a platform specified. Use this when the game was released only for one platform, so suffixes like '-win' make no sense. | ||
'''ADGF_DVD''' -- Specifies a DVD version. Generated target will get '-dvd' suffix. | |||
'''ADGF_MACRESFORK''' -- The provided file's checksum is in MacBinary (or another format). Thus, only the Mac Res fork is extracted and the MD5 calculated. This flag is '''deprecated''', please use one of the special prefixes in the ADGameFileDescription structure. | |||
'''ADGF_NO_FLAGS''' -- No flags are set. | '''ADGF_NO_FLAGS''' -- No flags are set. | ||
| Line 189: | Line 213: | ||
'''ADGF_PIRATED''' -- Specifies a blacklisted game. The game will be detected but refuse to run. | '''ADGF_PIRATED''' -- Specifies a blacklisted game. The game will be detected but refuse to run. | ||
There are known hacked variants for some of the games exist in the wild. We used to ignore user reports on them, but with the number of engines growing, it became tough to remember that some particular game is really a hack. When it was widespread enough, we were getting recurrent reports that the game is not detected. To avoid this situation we now accept md5s of such games but mark them accordingly. | There are known hacked variants for some of the games that exist in the wild. We used to ignore user reports on them, but with the number of engines growing, it became tough to remember that some particular game is really a hack. When it was widespread enough, we were getting recurrent reports that the game is not detected. To avoid this situation, we now accept md5s of such games but mark them accordingly. | ||
'''ADGF_REMASTERED''' -- Specifies a remastered version. Generated target will get '-remastered' suffix. | |||
'''ADGF_TAILMD5''' -- The specified MD5 checksum is counted from the tail of the engine. Used in cases when the game data is concatenated at the end of the engine executable. Good example is the Director titles that contain the start movie in the main executable after the projector code that spans over hundreds of kilobytes. | |||
'''ADGF_TESTING''' -- Specifies a game which was announced for public testing. The user will get a relevant warning when launching the game. These are added once the public testing is announced and removed right before the release. | |||
'''ADGF_UNSTABLE''' -- Specifies a game which is not publicly supported and is in heavy development. The user will get a relevant warning when launching the game. This warning could be suppressed completely by setting '''enable_unsupported_game_warning=true''' in the global section of the scummvm config. | |||
''' | '''ADGF_UNSUPPORTED''' -- The game detection will not launch. Instead, a message from the '''extra''' field will be presented to the end-user. Used for knowingly broken versions or those that require additional code which is not yet implemented and we still want to document their presence. | ||
''' | '''ADGF_USEEXTRAASTITLE''' -- Instead of '''description''' specified in ''PlainGameDescriptor'' table, '''extra''' field will be used as game description. A good example is AGI fan games where the game title is known, but it is not feasible to add it to the ''PlainGameDescriptor'' table, or minor composer engine demos with games combined for the same reason. | ||
''' | '''ADGF_WARNING''' -- Specifies a game that produces a specified warning on launch. The warning is provided (usually in a translatable form) in the ''extra'' field. The game will proceed to be launched, in contrast to the ''ADGF_UNSUPPORTED'' flag. | ||
== Advanced Detector flags ADFlags == | == Advanced Detector flags ADFlags == | ||