ResidualVM logo ResidualVM website - Forums - Contact us BuildBot - Doxygen - Wiki curved edge

A meta engine is essentially a factory for Engine instances with the added ability of listing and detecting supported games. More...

#include <metaengine.h>

Inheritance diagram for MetaEngine:
Collaboration diagram for MetaEngine:

List of all members.

Public Member Functions

virtual ~MetaEngine ()
virtual const char * getEngineId () const =0
 Get the engine ID.
virtual const char * getOriginalCopyright () const =0
 Returns some copyright information about the original engine.
virtual PlainGameList getSupportedGames () const =0
 Returns a list of games supported by this engine.
virtual PlainGameDescriptor findGame (const char *gameId) const =0
 Query the engine for a PlainGameDescriptor for the specified gameid, if any.
virtual DetectedGames detectGames (const Common::FSList &fslist) const =0
 Runs the engine's game detector on the given list of files, and returns a (possibly empty) list of games supported by the engine which it was able to detect amongst the given files.
virtual Common::Error createInstance (OSystem *syst, Engine **engine) const =0
 Tries to instantiate an engine instance based on the settings of the currently active ConfMan target.
virtual SaveStateList listSaves (const char *target) const
 Return a list of all save states associated with the given target.
SaveStateList listSaves (const char *target, bool saveMode) const
 Return a list of all save states associated with the given target.
virtual int getAutosaveSlot () const
 Returns the slot number being used for autosaves.
virtual const ExtraGuiOptions getExtraGuiOptions (const Common::String &target) const
 Return a list of extra GUI options for the specified target.
virtual void registerDefaultSettings (const Common::String &target) const
 Register the default values for the settings the engine uses into the configuration manager.
virtual
GUI::OptionsContainerWidget
buildEngineOptionsWidget (GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const
 Return a GUI widget container for configuring the specified target options.
virtual const
Common::AchievementsInfo 
getAchievementsInfo (const Common::String &target) const
 Return a list of achievement descriptions for the specified target.
virtual int getMaximumSaveSlot () const
 Return the maximum save slot that the engine supports.
virtual void removeSaveState (const char *target, int slot) const
 Remove the specified save state.
virtual SaveStateDescriptor querySaveMetaInfos (const char *target, int slot) const
 Returns meta infos from the specified save state.
virtual const char * getSavegameFile (int saveGameIdx, const char *target=nullptr) const
 Returns name of the save file for given slot and optional target.
virtual const char * getSavegamePattern (const char *target=nullptr) const
 Returns pattern for save files.
virtual Common::Array
< Common::Keymap * > 
initKeymaps (const char *target) const
 Return the keymap used by the target.

Static Private Member Functions

static void saveScreenThumbnail (Common::OutSaveFile *saveFile)
 Converts the current screen contents to a thumbnail, and saves it.

MetaEngineFeature flags



enum  MetaEngineFeature {
  kSupportsListSaves, kSupportsLoadingDuringStartup, kSupportsDeleteSave, kSavesSupportMetaInfo,
  kSavesSupportThumbnail, kSavesSupportCreationDate, kSavesSupportPlayTime, kSimpleSavesNames,
  kSavesUseExtendedFormat
}
 

A feature in this context means an ability of the engine which can be either available or not.

More...
virtual bool hasFeature (MetaEngineFeature f) const
 Determine whether the engine supports the specified MetaEngine feature.
static void appendExtendedSave (Common::OutSaveFile *saveFile, uint32 playtime, Common::String desc, bool isAutosave)
static void parseSavegameHeader (ExtendedSavegameHeader *header, SaveStateDescriptor *desc)
static void fillDummyHeader (ExtendedSavegameHeader *header)
static WARN_UNUSED_RESULT bool readSavegameHeader (Common::InSaveFile *in, ExtendedSavegameHeader *header, bool skipThumbnail=true)

Detailed Description

A meta engine is essentially a factory for Engine instances with the added ability of listing and detecting supported games.

Every engine "plugin" provides a hook to get an instance of a MetaEngine subclass for that "engine plugin". E.g. SCUMM povides ScummMetaEngine. This is then in turn used by the frontend code to detect games, and instantiate actual Engine objects.

Definition at line 102 of file metaengine.h.


Member Enumeration Documentation

A feature in this context means an ability of the engine which can be either available or not.

Enumerator:
kSupportsListSaves 

Listing all Save States for a given target is supported, i.e., the listSaves() and getMaximumSaveSlot methods are implemented.

Used for --list-saves support, as well as the GMM load dialog.

kSupportsLoadingDuringStartup 

Loading from the Launcher / command line (-x).

kSupportsDeleteSave 

Deleting Saves from the Launcher (i.e.

implements the removeSaveState() method)

kSavesSupportMetaInfo 

Features meta infos for savestates (i.e.

implements the querySaveMetaInfos method properly).

Engines implementing meta infos always have to provide the following entries in the save state descriptor queried by querySaveMetaInfos:

  • 'is_deletable', which indicates if a given save is safe for deletion
  • 'is_write_protected', which indicates if a given save can be overwritten by the user. (note: of course you do not have to set this, since it defaults to 'false')
kSavesSupportThumbnail 

Features a thumbnail in savegames (i.e.

includes a thumbnail in savestates returned via querySaveMetaInfo). This flag may only be set when 'kSavesSupportMetaInfo' is set.

kSavesSupportCreationDate 

Features 'save_date' and 'save_time' entries in the savestate returned by querySaveMetaInfo.

Those values indicate the date/time the savegame was created. This flag may only be set when 'kSavesSupportMetaInfo' is set.

kSavesSupportPlayTime 

Features 'play_time' entry in the savestate returned by querySaveMetaInfo.

It indicates how long the user played the game till the save. This flag may only be set when 'kSavesSupportMetaInfo' is set.

kSimpleSavesNames 

Feature is available if engine's saves could be detected with "<target>.###" pattern and "###" corresponds to slot number.

If that's not true or engine is using some unusual way of detecting saves and slot numbers, this should be unavailable. In that case Save/Load dialog for engine's games is locked during cloud saves sync.

kSavesUseExtendedFormat 

Uses default implementation of save header and thumbnail appended to the save.

This flag requires the following flags to be set: kSavesSupportMetaInfo, kSavesSupportThumbnail, kSavesSupportCreationDate, kSavesSupportPlayTime

Definition at line 302 of file metaengine.h.


Constructor & Destructor Documentation

virtual MetaEngine::~MetaEngine (  )  [inline, virtual]

Definition at line 109 of file metaengine.h.


Member Function Documentation

void MetaEngine::appendExtendedSave ( Common::OutSaveFile saveFile,
uint32  playtime,
Common::String  desc,
bool  isAutosave 
) [static]

Definition at line 147 of file metaengine.cpp.

GUI::OptionsContainerWidget * MetaEngine::buildEngineOptionsWidget ( GUI::GuiObject boss,
const Common::String name,
const Common::String target 
) const [virtual]

Return a GUI widget container for configuring the specified target options.

The returned widget is shown in the Engine tab in the edit game dialog. Engines can build custom options dialogs, but by default a simple widget allowing to configure the extra GUI options is used.

Engines that don't want to have an Engine tab in the edit game dialog can return nullptr.

Parameters:
boss the widget / dialog the returned widget is a child of
name the name the returned widget must use
target name of a config manager target

Definition at line 352 of file metaengine.cpp.

virtual Common::Error MetaEngine::createInstance ( OSystem syst,
Engine **  engine 
) const [pure virtual]

Tries to instantiate an engine instance based on the settings of the currently active ConfMan target.

That is, the MetaEngine should query the ConfMan singleton for the target, gameid, path etc. data.

Parameters:
syst Pointer to the global OSystem object
engine Pointer to a pointer which the MetaEngine sets to the newly create Engine, or 0 in case of an error
Returns:
a Common::Error describing the error which occurred, or kNoError

Implemented in AdvancedMetaEngine, and Grim::GrimMetaEngine.

virtual DetectedGames MetaEngine::detectGames ( const Common::FSList fslist  )  const [pure virtual]

Runs the engine's game detector on the given list of files, and returns a (possibly empty) list of games supported by the engine which it was able to detect amongst the given files.

Implemented in AdvancedMetaEngine.

void MetaEngine::fillDummyHeader ( ExtendedSavegameHeader header  )  [static]

Definition at line 202 of file metaengine.cpp.

virtual PlainGameDescriptor MetaEngine::findGame ( const char *  gameId  )  const [pure virtual]

Query the engine for a PlainGameDescriptor for the specified gameid, if any.

Implemented in AdvancedMetaEngine, and Grim::GrimMetaEngine.

virtual const Common::AchievementsInfo MetaEngine::getAchievementsInfo ( const Common::String target  )  const [inline, virtual]

Return a list of achievement descriptions for the specified target.

The default implementation returns an empty list.

Parameters:
target name of a config manager target
Returns:
a list of achievement descriptions for an engine plugin and target

Reimplemented in Wintermute::WintermuteMetaEngine.

Definition at line 232 of file metaengine.h.

virtual int MetaEngine::getAutosaveSlot (  )  const [inline, virtual]

Returns the slot number being used for autosaves.

Note:
This should match the engine getAutosaveSlot() method

Definition at line 178 of file metaengine.h.

virtual const char* MetaEngine::getEngineId (  )  const [pure virtual]
virtual const ExtraGuiOptions MetaEngine::getExtraGuiOptions ( const Common::String target  )  const [inline, virtual]

Return a list of extra GUI options for the specified target.

If no target is specified, all of the available custom GUI options are Returned for the plugin (used to set default values).

Currently, this only supports options with checkboxes.

The default implementation returns an empty list.

Parameters:
target name of a config manager target
Returns:
a list of extra GUI options for an engine plugin and target

Reimplemented in AdvancedMetaEngine.

Definition at line 195 of file metaengine.h.

virtual int MetaEngine::getMaximumSaveSlot (  )  const [inline, virtual]

Return the maximum save slot that the engine supports.

Note:
MetaEngines must indicate that this function has been implemented via the kSupportsListSaves feature flag.

The default implementation limits the save slots to zero (0).

Returns:
maximum save slot number supported

Reimplemented in Myst3::Myst3MetaEngine, Stark::StarkMetaEngine, and Wintermute::WintermuteMetaEngine.

Definition at line 246 of file metaengine.h.

virtual const char* MetaEngine::getOriginalCopyright (  )  const [pure virtual]

Returns some copyright information about the original engine.

Implemented in Grim::GrimMetaEngine, Myst3::Myst3MetaEngine, Stark::StarkMetaEngine, and Wintermute::WintermuteMetaEngine.

const char * MetaEngine::getSavegameFile ( int  saveGameIdx,
const char *  target = nullptr 
) const [virtual]

Returns name of the save file for given slot and optional target.

Parameters:
saveGameIdx index of the save
target game target. If omitted, then the engine id is used

Definition at line 40 of file metaengine.cpp.

const char * MetaEngine::getSavegamePattern ( const char *  target = nullptr  )  const [virtual]

Returns pattern for save files.

Parameters:
target game target. If omitted, then the engine id is used

Definition at line 48 of file metaengine.cpp.

virtual PlainGameList MetaEngine::getSupportedGames (  )  const [pure virtual]

Returns a list of games supported by this engine.

Implemented in AdvancedMetaEngine.

bool MetaEngine::hasFeature ( MetaEngineFeature  f  )  const [virtual]

Determine whether the engine supports the specified MetaEngine feature.

Used by e.g. the launcher to determine whether to enable the "Load" button.

Reimplemented in Grim::GrimMetaEngine, Myst3::Myst3MetaEngine, Stark::StarkMetaEngine, and Wintermute::WintermuteMetaEngine.

Definition at line 135 of file metaengine.cpp.

Common::KeymapArray MetaEngine::initKeymaps ( const char *  target  )  const [virtual]

Return the keymap used by the target.

Reimplemented in Wintermute::WintermuteMetaEngine.

Definition at line 56 of file metaengine.cpp.

SaveStateList MetaEngine::listSaves ( const char *  target,
bool  saveMode 
) const

Return a list of all save states associated with the given target.

This is a wrapper around the basic listSaves virtual method, but which has some extra logic for autosave handling

Parameters:
target name of a config manager target
saveMode If true, getting the list for a save dialog
Returns:
a list of save state descriptors

Definition at line 312 of file metaengine.cpp.

SaveStateList MetaEngine::listSaves ( const char *  target  )  const [virtual]

Return a list of all save states associated with the given target.

The returned list is guaranteed to be sorted by slot numbers. That means smaller slot numbers are always stored before bigger slot numbers.

The caller has to ensure that this (Meta)Engine is responsible for the specified target (by using findGame on it respectively on the associated gameid from the relevant ConfMan entry, if present).

The default implementation returns an empty list.

Note:
MetaEngines must indicate that this function has been implemented via the kSupportsListSaves feature flag.
Parameters:
target name of a config manager target
Returns:
a list of save state descriptors

Reimplemented in Grim::GrimMetaEngine, Myst3::Myst3MetaEngine, Stark::StarkMetaEngine, and Wintermute::WintermuteMetaEngine.

Definition at line 271 of file metaengine.cpp.

void MetaEngine::parseSavegameHeader ( ExtendedSavegameHeader header,
SaveStateDescriptor desc 
) [static]

Definition at line 189 of file metaengine.cpp.

SaveStateDescriptor MetaEngine::querySaveMetaInfos ( const char *  target,
int  slot 
) const [virtual]

Returns meta infos from the specified save state.

Depending on the MetaEngineFeatures set this can include thumbnails, save date / time, play time.

Parameters:
target name of a config manager target
slot slot number of the save state

Reimplemented in Myst3::Myst3MetaEngine, Stark::StarkMetaEngine, and Wintermute::WintermuteMetaEngine.

Definition at line 368 of file metaengine.cpp.

WARN_UNUSED_RESULT bool MetaEngine::readSavegameHeader ( Common::InSaveFile in,
ExtendedSavegameHeader header,
bool  skipThumbnail = true 
) [static]

Definition at line 209 of file metaengine.cpp.

void MetaEngine::registerDefaultSettings ( const Common::String target  )  const [virtual]

Register the default values for the settings the engine uses into the configuration manager.

Parameters:
target name of a config manager target

Definition at line 341 of file metaengine.cpp.

void MetaEngine::removeSaveState ( const char *  target,
int  slot 
) const [virtual]

Remove the specified save state.

For most engines this just amounts to calling _saveFileMan->removeSaveFile(). Engines which keep an index file will also update it accordingly.

Note:
MetaEngines must indicate that this function has been implemented via the kSupportsDeleteSave feature flag.
Parameters:
target name of a config manager target
slot slot number of the save state to be removed

Reimplemented in Myst3::Myst3MetaEngine, Stark::StarkMetaEngine, and Wintermute::WintermuteMetaEngine.

Definition at line 361 of file metaengine.cpp.

void MetaEngine::saveScreenThumbnail ( Common::OutSaveFile saveFile  )  [static, private]

Converts the current screen contents to a thumbnail, and saves it.

Definition at line 179 of file metaengine.cpp.


The documentation for this class was generated from the following files:


Generated on Sat May 30 2020 05:02:24 for ResidualVM by doxygen 1.7.1
curved edge   curved edge