Difference between revisions of "Advanced Detector"

Jump to navigation Jump to search

Advanced Detector (view source)

Revision as of 10:57, 1 August 2022

1,676 bytes added ,  10:57, 1 August 2022
m
→‎Game Entry flags ADGameFlags: grammar
(language changes)
(8 intermediate revisions by 3 users not shown)
Line 18: Line 18:
The code for this can be found in <tt>engines/advancedDetector.*</tt>
The code for this can be found in <tt>engines/advancedDetector.*</tt>


To use this, you will have to follow the instructions [[HOWTO-Engines#Subclassing_MetaEngine|here]], but you will subclass AdvancedMetaEngine instead within your engine's detection.h and detection.cpp.
To use this, you will have to follow the instructions [[HOWTO-Engines#Subclassing_AdvancedMetaEngine|here]] within your engine's detection.h and detection.cpp.


All you will have to provide is a standard data table of ADGameDescription entries describing each game variant, which is usually placed in a separate detection_tables.h header, which is included in detection.cpp for use there.
All you will have to provide is a standard data table of ADGameDescription entries describing each game variant, which is usually placed in a separate detection_tables.h header, which is included in detection.cpp for use there.


This structure plus other parameters are passed to the AdvancedMetaEngine constructor, which can also contain overrides of the default parameters for detection e.g. _md5Bytes is the number of bytes used for the MD5 hash for each file, etc.
This structure plus other parameters are passed to the AdvancedMetaEngineDetection constructor, which can also contain overrides of the default parameters for detection e.g. _md5Bytes is the number of bytes used for the MD5 hash for each file, etc.


It is suggested you consult the code and header comments in <tt>engines/advancedDetector.*</tt> and look at the examples provided by current engines for a more complete example.
It is suggested you consult the code and header comments in <tt>engines/advancedDetector.*</tt> and look at the examples provided by current engines for a more complete example.
Line 29: Line 29:


When you look into your .scummvmrc or scummvm.ini (depending on the platform), you will find that generally it has following structure
When you look into your .scummvmrc or scummvm.ini (depending on the platform), you will find that generally it has following structure
<syntax type="INI">
<syntaxhighlight lang="INI">
[scummvm]
[scummvm]
globalkey1=foo
globalkey1=foo
Line 38: Line 38:
description=Monkey Island 2: LeChuck's Revenge (DOS/English)
description=Monkey Island 2: LeChuck's Revenge (DOS/English)
path=/Users/sev/games/scumm/monkey2
path=/Users/sev/games/scumm/monkey2
engindid=scumm
gameid=monkey2
gameid=monkey2
language=en
language=en
platform=pc
platform=pc
</syntax>
</syntaxhighlight>


What you see here is several sections designated by identifiers in square brackets and set of key/value pairs belonging to each such section.
What you see here is several sections designated by identifiers in square brackets and set of key/value pairs belonging to each such section.
Line 49: Line 50:
Name of each game is what we are calling '''target'''. Target, which is in the sample above specified as ''monkey2-vga'' is user-editable identifier unique to the specific user, and could be used for launching the game from command line.
Name of each game is what we are calling '''target'''. Target, which is in the sample above specified as ''monkey2-vga'' is user-editable identifier unique to the specific user, and could be used for launching the game from command line.


Then each entry has '''description''' which is also user-editable, '''path''' to the game, and '''gameid'''. '''gameid''' is a service name which identifies the game within whole ScummVM. There should be no clashes, and each engine knows which gameids it does support. First engine which finds a match for a given gameid will be used to run the game. This is why it is important to keep this ID unique, since there is no guarantee in sequence of engines which ScummVM probes when launching a game.
Then each entry has '''description''' which is also user-editable, '''path''' to the game, '''engineid''' and '''gameid'''. '''engineid''' is a service name which identifies the engine within whole ScummVM. There should be no clashes, and each engine knows which gameids it does support, so '''gameid''' is only unique to each engine.


Keys '''platform''' and '''language''' are used for narrowing down the possible game candidate but are fully optional.
Keys '''platform''' and '''language''' are used for narrowing down the possible game candidate but are fully optional.
Line 67: 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 73: Line 74:
Targets generated by Advanced Detector have the following structure:
Targets generated by Advanced Detector have the following structure:


<code>
   GAMEID-DEMO-CD-PLATFORM-LANG
   GAMEID-DEMO-CD-PLATFORM-LANG
</code>


The target generation is affected by AD flags. The flags which have influence are: ADGF_CD, ADGF_DEMO, ADGF_DROPLANGUAGE.  
The target generation is affected by AD flags. The flags which have influence are: ADGF_CD, ADGF_DEMO, ADGF_DROPLANGUAGE.


== PlainGameDescriptor table ==
== PlainGameDescriptor table ==


<syntax type="C++">
<syntaxhighlight lang="cpp">
struct PlainGameDescriptor {
struct PlainGameDescriptor {
const char *gameid;
const char *gameid;
const char *description;
const char *description;
};
};
</syntax>
</syntaxhighlight>


This table contains all gameids which are known by the engine. Also each gameid contains a full human-readable description, which is used to provide the '''description''' field in the ScummVM configuration file.
This table contains all gameids which are known by the engine. Also each gameid contains a full human-readable description, which is used to provide the '''description''' field in the ScummVM configuration file.
Line 94: Line 93:
Typical PlainGameDescriptor table:
Typical PlainGameDescriptor table:


<syntax type="C++">
<syntaxhighlight lang="cpp">
static const PlainGameDescriptor cineGames[] = {
static const PlainGameDescriptor cineGames[] = {
{"cine", "Cinematique evo.1 engine game"},
{"cine", "Cinematique evo.1 engine game"},
Line 101: Line 100:
{0, 0}
{0, 0}
};
};
</syntax>
</syntaxhighlight>


Please note that it is NULL-terminated, and also contains the generic gameid ''cine'' which is used by fallback detection.
Please note that it is NULL-terminated, and also contains the generic gameid ''cine'' which is used by fallback detection.
Line 109: Line 108:
ADGameDescription table has the following structure:
ADGameDescription table has the following structure:


<syntax type="C++">
<syntaxhighlight lang="cpp">
struct ADGameDescription {
struct ADGameDescription {
const char *gameid;
const char *gameid;
Line 119: Line 118:
const char *guioptions;
const char *guioptions;
};
};
</syntax>
</syntaxhighlight>


'''gameid''' -- This is the gameid. Mainly it is used for taking the game description from the ''PlainGameDescriptor'' table.
'''gameid''' -- This is the gameid. Mainly it is used for taking the game description from the ''PlainGameDescriptor'' table.
Line 138: Line 137:
Typical ADGameDescription table will look as follows:
Typical ADGameDescription table will look as follows:


<syntax type="C++">
<syntaxhighlight lang="cpp">
static const ADGameDescription gameDescriptions[] = {
static const ADGameDescription gameDescriptions[] = {
{
{
Line 145: Line 144:
AD_ENTRY1("part01", "61d003202d301c29dd399acfb1354310"),
AD_ENTRY1("part01", "61d003202d301c29dd399acfb1354310"),
Common::EN_ANY,
Common::EN_ANY,
Common::kPlatformPC,
Common::kPlatformDOS,
ADGF_NO_FLAGS,
ADGF_NO_FLAGS,
GUIO0()
GUIO0()
Line 151: Line 150:
{ AD_TABLE_END_MARKER, 0, 0 }
{ AD_TABLE_END_MARKER, 0, 0 }
};
};
</syntax>
</syntaxhighlight>


== ADGameFileDescription structure ==
== ADGameFileDescription structure ==


<syntax type="C++">
<syntaxhighlight lang="cpp">
struct ADGameFileDescription {
struct ADGameFileDescription {
const char *fileName; ///< Name of described file.
const char *fileName; ///< Name of described file.
Line 162: Line 161:
int32 fileSize;  ///< Size of the described file. Set to -1 to ignore.
int32 fileSize;  ///< Size of the described file. Set to -1 to ignore.
};
};
</syntax>
</syntaxhighlight>


'''fileName''' -- name of the file. It is case insensitive, but historically we use lowercase names.
'''fileName''' -- name of the file. It is case insensitive, but historically we use lowercase names.
Line 168: Line 167:
'''fileType''' -- rarely used field where ''ADGameFileDescription'' structure is used by the engine. May specify music file, script file, etc.
'''fileType''' -- rarely used field where ''ADGameFileDescription'' structure is used by the engine. May specify music file, script file, etc.


'''md5''' -- MD5 of the file. Most often it is MD5 of the beginning of the file for performance reasons. See '''_md5Bytes''' setting of ''AdvancedMetaEngine''. If set to NULL, the md5 is not used in detection and the entry matches against any content.
'''md5''' -- MD5 of the file. Most often it is MD5 of the beginning of the file for performance reasons. See '''_md5Bytes''' setting of ''AdvancedMetaEngineDetection''. If set to NULL, the md5 is not used in detection and the entry matches against any content.


'''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.
Line 176: Line 175:
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 version of the game. Affects GUIOs.
'''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 184: Line 185:
'''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 files checksum is in MacBinary (or another format). Thus, only the Mac Res fork is extracted and the MD5 calculated. Use it for all Mac releases.


'''ADGF_NO_FLAGS''' -- No flags are set.
'''ADGF_NO_FLAGS''' -- No flags are set.
Line 190: Line 195:
'''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_TESTING''' -- Specifies game which was announced for public testing. The user will get a relevant warning when launching the game.
'''ADGF_REMASTERED''' -- Specifies a remastered version. Generated target will get '-remastered' suffix.


'''ADGF_UNSTABLE''' -- Specifies game which is not publicly supported and is in a heavy development. The user will get a relevant warning when launching the game.
'''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_USEEXTRAASTITLE''' -- Instead of '''description''' specified in ''PlainGameDescriptor'' table, '''extra''' field will be used as game description. Good example is AGI fan games where the game title is known but it is not feasible to add it to ''PlainGameDescriptor'' table, or minor composer engine demos with games combined for the same reason.
'''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 ==
Line 204: Line 217:
== Upgrading obsolete gameids ==
== Upgrading obsolete gameids ==


<syntax type="C++">
<syntaxhighlight lang="cpp">
static const Engines::ObsoleteGameID obsoleteGameIDsTable[] = {
static const Engines::ObsoleteGameID obsoleteGameIDsTable[] = {
         {"simon1acorn", "simon1", Common::kPlatformAcorn},
         {"simon1acorn", "simon1", Common::kPlatformAcorn},
         {"simon1amiga", "simon1", Common::kPlatformAmiga},
         {"simon1amiga", "simon1", Common::kPlatformAmiga},
         {"simon2talkie", "simon2", Common::kPlatformPC},
         {"simon2talkie", "simon2", Common::kPlatformDOS},
         {"simon2mac", "simon2", Common::kPlatformMacintosh},
         {"simon2mac", "simon2", Common::kPlatformMacintosh},
         {"simon2win", "simon2", Common::kPlatformWindows},
         {"simon2win", "simon2", Common::kPlatformWindows},
         {0, 0, Common::kPlatformUnknown}
         {0, 0, Common::kPlatformUnknown}
};
};
</syntax>
</syntaxhighlight>


= AdvancedMetaEngine =
= AdvancedMetaEngineDetection =


Is a generic MetaEngine wrapper which is aware of the Advanced Detector. It should be used whenever AD is used.
Is a generic MetaEngine wrapper which is aware of the Advanced Detector. It should be used whenever AD is used.
Line 221: Line 234:
== Engine constructor ==
== Engine constructor ==


<syntax type="C++">
<syntaxhighlight lang="cpp">
AdvancedMetaEngine(const void *descs, uint descItemSize, const PlainGameDescriptor *gameids);
AdvancedMetaEngineDetection(const void *descs, uint descItemSize, const PlainGameDescriptor *gameIds);
</syntax>
</syntaxhighlight>


'''descs''' must point to a list of ''ADGameDescription'' structures, or their supersets.
'''descs''' must point to a list of ''ADGameDescription'' structures, or their supersets.
Line 229: Line 242:
'''descItemSize''' is sizeof of the '''descs''' element used for iterating over it.
'''descItemSize''' is sizeof of the '''descs''' element used for iterating over it.


'''gameids''' must point to a list of ''PlainGameDescriptor'' structures defining supported gameids.
'''gameIds''' must point to a list of ''PlainGameDescriptor'' structures defining supported gameids.


== Additional Advanced MetaEngine parameters ==
== Additional Advanced MetaEngine parameters ==


'''_md5bytes''' -- number of bytes used to compute md5. If set to 0 then whole file will be used. Beware of doing this if your detection might encounter large files, since that can dramatically slow down the detection. Typically a sane value is 5000 bytes (the default), but often experimentation is required for many game variants with subtle differences.
'''_md5Bytes''' -- number of bytes used to compute md5. If set to 0 then whole file will be used. Beware of doing this if your detection might encounter large files, since that can dramatically slow down the detection. Typically a sane value is 5000 bytes (the default), but often experimentation is required for many game variants with subtle differences.
 
'''_singleid''' -- Used to override gameid. A recommended setting to prevent global gameid pollution. With this option set, the gameid effectively turns into engineid.
 
In the past we started to have clashes in game names, thus the option was introduced. Also it was mentioned that in the ideal world it should be enough to point just the game directory and ScummVM correctly detects and runs the game. This is a step towards this direction, however there are several cases when it is not possible to identify the game to run, particularly in those cases when there are more than single game stored in a directory.


'''_flags''' -- same as individual game flags but user for engine-wide settings. For instance, we know for sure that all games in the engine are unstable, so instead of modifying every game entry, we specify it here.
'''_flags''' -- same as individual game flags but user for engine-wide settings. For instance, we know for sure that all games in the engine are unstable, so instead of modifying every game entry, we specify it here.


'''_guioptions''' -- same as individual GUI options, but applied engine-wide. For example, when none of the games have speech, we may specify it in this spot.
'''_guiOptions''' -- same as individual GUI options, but applied engine-wide. For example, when none of the games have speech, we may specify it in this spot.


'''_maxScanDepth''' -- Maximum traversal depth for directories. Default is 1, that is do not go inside of subdirectories for detection.
'''_maxScanDepth''' -- Maximum traversal depth for directories. Default is 1, that is do not go inside of subdirectories for detection.
Retrieved from "https://wiki.scummvm.org/index.php?title=Special:MobileDiff/17448...35398"

Navigation menu