ScummVM API documentation
MetaEngine Class Referenceabstract

#include <metaengine.h>

Inheritance diagram for MetaEngine:
PluginObject AdvancedMetaEngineBase ScummMetaEngine AdvancedMetaEngine< Descriptor > AdvancedMetaEngine< ADGameDescription > AdvancedMetaEngine< AGS::AGSGameDescription > AdvancedMetaEngine< M4::M4GameDescription > AdvancedMetaEngine< Twp::TwpGameDescription > AdvancedMetaEngine< Ultima::UltimaGameDescription > BagelMetaEngine CrabMetaEngine DarkseedMetaEngine Hpl1MetaEngine ImmortalMetaEngine QDEngineMetaEngine TetraedgeMetaEngine AGSMetaEngine M4MetaEngine TwpMetaEngine UltimaMetaEngine

Public Types

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

Public Member Functions

virtual const char * getName () const override=0
 
virtual Common::Error createInstance (OSystem *syst, Engine **engine, const DetectedGame &gameDescriptor, const void *meDescriptor)=0
 
virtual void deleteInstance (Engine *engine, const DetectedGame &gameDescriptor, const void *meDescriptor)
 
virtual SaveStateList listSaves (const char *target) const
 
SaveStateList listSaves (const char *target, bool saveMode) const
 
virtual int getAutosaveSlot () const
 
virtual int getMaximumSaveSlot () const
 
virtual bool removeSaveState (const char *target, int slot) const
 
virtual SaveStateDescriptor querySaveMetaInfos (const char *target, int slot) const
 
virtual Common::String getSavegameFile (int saveGameIdx, const char *target=nullptr) const
 
Common::String getSavegameFilePattern (const char *target=nullptr) const
 
virtual Common::Array< Common::Keymap * > initKeymaps (const char *target) const
 
virtual void registerDefaultSettings (const Common::String &target) const
 
virtual GUI::OptionsContainerWidgetbuildEngineOptionsWidget (GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const
 
virtual Common::AchievementsPlatform getAchievementsPlatform (const Common::String &target) const
 
virtual const Common::AchievementsInfo getAchievementsInfo (const Common::String &target) const
 
virtual const Common::AchievementDescriptionListgetAchievementDescriptionList () const
 
virtual bool hasFeature (MetaEngineFeature f) const
 
void appendExtendedSave (Common::OutSaveFile *saveFile, uint32 playtime, Common::String desc, bool isAutosave)
 
void appendExtendedSaveToStream (Common::WriteStream *saveFile, uint32 playtime, Common::String desc, bool isAutosave, uint32 offset=0)
 
bool copySaveFileToFreeSlot (const char *target, int slot)
 

Static Public Member Functions

static void parseSavegameHeader (ExtendedSavegameHeader *header, SaveStateDescriptor *desc)
 
static void fillDummyHeader (ExtendedSavegameHeader *header)
 
static void decodeSavegameDate (const ExtendedSavegameHeader *header, uint16 &outYear, uint8 &outMonth, uint8 &outDay)
 
static void decodeSavegameTime (const ExtendedSavegameHeader *header, uint8 &outHour, uint8 &outMinute)
 
static WARN_UNUSED_RESULT bool readSavegameHeader (Common::InSaveFile *in, ExtendedSavegameHeader *header, bool skipThumbnail=true)
 

Protected Member Functions

virtual void getSavegameThumbnail (Graphics::Surface &thumb)
 
int findEmptySaveSlot (const char *target)
 
virtual const ExtraGuiOptions getExtraGuiOptions (const Common::String &target) const
 

Detailed Description

A MetaEngine is another factory for Engine instances, and is very similar to MetaEngineDetection.

This class, however, is made of of bridged functionalities that can be used to connect an actual Engine with a MetaEngine. Every engine "plugin" provides a hook to get an instance of the MetaEngine subclass for that "engine plugin.". For example, SCUMM provides a ScummMetaEngine. This is then in turn used for things like instantiating engine objects, listing savefiles, querying save metadata, etc.

Since engine plugins can use external runtime libraries, these can live and build inside the engine, while a MetaEngine will always build into the executable to be able to detect code.

Member Enumeration Documentation

◆ MetaEngineFeature

MetaEngine feature flags.

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

Enumerator
kSupportsListSaves 

List all save states for a given target that is supported.

For the target to be supported, the listSaves() and getMaximumSaveSlot methods must be implemented. Used for –list-saves support, as well as the GMM load dialog.

kSupportsLoadingDuringStartup 

Load from the launcher or command line (-x).

kSupportsDeleteSave 

Delete saves from the launcher.

This means that the engine implements the removeSaveState() method.

kSavesSupportMetaInfo 

Feature meta information for save states.

This means that the engine implements the querySaveMetaInfos method properly.

Engines implementing meta information always must provide the following entries in the save state descriptor queried by querySaveMetaInfos:

  • is_deletable - indicates whether a given save is safe for deletion
  • is_write_protected - indicates whether a given save can be overwritten by the user. You do not need to set this, default value is 'false'.
kSavesSupportThumbnail 

Feature a thumbnail in savegames.

This means that the engine includes a thumbnail in save states returned via querySaveMetaInfo. This flag can only be set when kSavesSupportMetaInfo is set.

kSavesSupportCreationDate 

Feature save_date and save_time entries in the save state returned by querySaveMetaInfo.

These values indicate the date and time when the savegame was created. This flag can only be set when kSavesSupportMetaInfo is set.

kSavesSupportPlayTime 

Feature play_time entry in the save state returned by querySaveMetaInfo.

This indicates how long the user played the game until the save. This flag can only be set when kSavesSupportMetaInfo is set.

kSimpleSavesNames 

This feature is available if the engine's saves can be detected with:

<target>.###

where ### corresponds to slot number.

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

NOTE: This flag is used by cloud code, but also in MetaEngine::getSavegameFile(), for common save names.

kSavesUseExtendedFormat 

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

This flag requires the following flags to be set:

  • kSavesSupportMetaInfo
  • kSavesSupportThumbnail
  • kSavesSupportCreationDate
  • kSavesSupportPlayTime

Member Function Documentation

◆ getSavegameThumbnail()

virtual void MetaEngine::getSavegameThumbnail ( Graphics::Surface thumb)
protectedvirtual

Convert the current screen contents to a thumbnail. Can be overriden by individual engine meta engines to provide their own thumb, such as hiding any on-screen save dialog so that it won't appear in the thumbnail.

Reimplemented in M4MetaEngine, TwpMetaEngine, CrabMetaEngine, QDEngineMetaEngine, Hpl1MetaEngine, and TetraedgeMetaEngine.

◆ findEmptySaveSlot()

int MetaEngine::findEmptySaveSlot ( const char *  target)
protected

Finds the first empty save slot that can be used for this target

Parameters
targetName of a config manager target.
Returns
The first empty save slot, or -1 if all are occupied.

◆ getExtraGuiOptions()

virtual const ExtraGuiOptions MetaEngine::getExtraGuiOptions ( const Common::String target) const
inlineprotectedvirtual

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
targetName of a config manager target.
Returns
A list of extra GUI options for an engine plugin and target.

Reimplemented in AdvancedMetaEngineBase.

◆ getName()

virtual const char* MetaEngine::getName ( ) const
overridepure virtual

Name of the engine plugin.

Classes inheriting a MetaEngine must provide an engineID here, which can then be used to match an Engine with MetaEngine.

For example, ScummMetaEngineDetection inherits MetaEngineDetection and provides a engineID of "scumm". ScummMetaEngine inherits MetaEngine and provides the name "Scumm". This way, an Engine can be easily matched with a MetaEngine.

Implements PluginObject.

Implemented in AdvancedMetaEngineBase, M4MetaEngine, UltimaMetaEngine, BagelMetaEngine, TetraedgeMetaEngine, AGSMetaEngine, ImmortalMetaEngine, CrabMetaEngine, QDEngineMetaEngine, DarkseedMetaEngine, Hpl1MetaEngine, and TwpMetaEngine.

◆ createInstance()

virtual Common::Error MetaEngine::createInstance ( OSystem syst,
Engine **  engine,
const DetectedGame gameDescriptor,
const void *  meDescriptor 
)
pure virtual

Instantiate an engine instance based on the settings of the currently active ConfMan target.

The MetaEngine queries the ConfMan singleton for data like the target, gameid, path etc.

Parameters
systPointer to the global OSystem object.
enginePointer to a pointer that the MetaEngine sets to the newly created Engine, or 0 in case of an error.
gameDescriptorDetected game as returned by MetaEngineDetection::identifyGame
meDescriptorPointer to a meta engine specific descriptor as returned by MetaEngineDetection::identifyGame
Returns
A Common::Error describing the error that occurred, or kNoError.

Implemented in AdvancedMetaEngineBase.

◆ deleteInstance()

virtual void MetaEngine::deleteInstance ( Engine engine,
const DetectedGame gameDescriptor,
const void *  meDescriptor 
)
virtual

Deinstantiate an engine instance. The default implementation merely deletes the engine.

The MetaEngine queries the ConfMan singleton for data like the target, gameid, path etc.

Parameters
enginePointer to the Engine that MetaEngine created.
gameDescriptorDetected game as returned by MetaEngineDetection::identifyGame
meDescriptorPointer to a meta engine specific descriptor as returned by MetaEngineDetection::identifyGame

Reimplemented in AdvancedMetaEngine< Descriptor >, AdvancedMetaEngine< ADGameDescription >, AdvancedMetaEngine< Twp::TwpGameDescription >, AdvancedMetaEngine< M4::M4GameDescription >, AdvancedMetaEngine< Ultima::UltimaGameDescription >, and AdvancedMetaEngine< AGS::AGSGameDescription >.

◆ listSaves() [1/2]

virtual 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 must ensure that this (Meta)Engine is responsible for the specified target. This is done 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
targetName of a config manager target.
Returns
A list of save state descriptors.

Reimplemented in UltimaMetaEngine, and AGSMetaEngine.

◆ listSaves() [2/2]

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 it has some extra logic for autosave handling.

Parameters
targetName of a config manager target.
saveModeIf true, get the list for a save dialog.
Returns
A list of save state descriptors.

◆ getAutosaveSlot()

virtual int MetaEngine::getAutosaveSlot ( ) const
inlinevirtual

Return the slot number that is used for autosaves, or -1 for engines that don't support autosave.

Note
This should match the engine getAutosaveSlot() method.

Reimplemented in AGSMetaEngine.

◆ getMaximumSaveSlot()

virtual int MetaEngine::getMaximumSaveSlot ( ) const
inlinevirtual

Return the maximum number of save slots 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 CrabMetaEngine, UltimaMetaEngine, AGSMetaEngine, and TwpMetaEngine.

◆ removeSaveState()

virtual bool MetaEngine::removeSaveState ( const char *  target,
int  slot 
) const
virtual

Remove the specified save state.

For most engines, this just means calling _saveFileMan->removeSaveFile(). Engines that 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
targetName of a config manager target.
slotSlot number of the save state to be removed.

Reimplemented in AGSMetaEngine.

◆ querySaveMetaInfos()

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

Return meta information from the specified save state.

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

Parameters
targetName of a config manager target.
slotSlot number of the save state.

Reimplemented in AGSMetaEngine, M4MetaEngine, UltimaMetaEngine, and TwpMetaEngine.

◆ getSavegameFile()

virtual Common::String MetaEngine::getSavegameFile ( int  saveGameIdx,
const char *  target = nullptr 
) const
virtual

Return the name of the save file for the given slot and optional target, or a pattern for matching filenames against.

Parameters
saveGameIdxIndex of the save, or kSavegameFilePattern for returning a filename pattern.
targetGame target. If omitted, then the engine ID is used.

Reimplemented in AGSMetaEngine.

◆ getSavegameFilePattern()

Common::String MetaEngine::getSavegameFilePattern ( const char *  target = nullptr) const
inline

Return the pattern for save files.

Parameters
targetGame target. If omitted, then the engine ID is used.

◆ initKeymaps()

virtual Common::Array<Common::Keymap *> MetaEngine::initKeymaps ( const char *  target) const
virtual

Return the keymap used by the target.

Reimplemented in UltimaMetaEngine, TwpMetaEngine, BagelMetaEngine, Hpl1MetaEngine, and CrabMetaEngine.

◆ registerDefaultSettings()

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

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

Parameters
targetName of a config manager target.

Reimplemented in TwpMetaEngine.

◆ buildEngineOptionsWidget()

virtual 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.

Engines can build custom option dialogs from here.

Engines that don't have an Engine tab in the Edit Game dialog, or that use ExtraGuiOptions in MetaEngineDetection can return nullptr.

Parameters
bossThe widget or dialog that the returned widget is a child of.
nameThe name that the returned widget must use.
targetName of a config manager target.

Reimplemented in AGSMetaEngine, and TwpMetaEngine.

◆ getAchievementsPlatform()

virtual Common::AchievementsPlatform MetaEngine::getAchievementsPlatform ( const Common::String target) const
virtual

Return the achievements platform to use for the specified target.

Parameters
targetName of a config manager target.
Returns
The achievements platform to use for an engine plugin and target.

Reimplemented in TwpMetaEngine.

◆ getAchievementsInfo()

virtual const Common::AchievementsInfo MetaEngine::getAchievementsInfo ( const Common::String target) const
virtual

Return a list of achievement descriptions for the specified target.

Parameters
targetName of a config manager target.
Returns
A list of achievement descriptions for an engine plugin and target.

◆ getAchievementDescriptionList()

virtual const Common::AchievementDescriptionList* MetaEngine::getAchievementDescriptionList ( ) const
inlinevirtual

Return the achievement descriptions.

Note
The default implementation returns nullptr
Returns
a list of achievement descriptions for an engine.

Reimplemented in AGSMetaEngine, and TwpMetaEngine.

◆ hasFeature()

virtual 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 AGSMetaEngine, M4MetaEngine, TetraedgeMetaEngine, BagelMetaEngine, ImmortalMetaEngine, CrabMetaEngine, QDEngineMetaEngine, DarkseedMetaEngine, Hpl1MetaEngine, and TwpMetaEngine.

◆ appendExtendedSave()

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

Write the extended savegame header to the given savegame file.

◆ appendExtendedSaveToStream()

void MetaEngine::appendExtendedSaveToStream ( Common::WriteStream saveFile,
uint32  playtime,
Common::String  desc,
bool  isAutosave,
uint32  offset = 0 
)

Write the extended savegame header to the given WriteStream.

◆ copySaveFileToFreeSlot()

bool MetaEngine::copySaveFileToFreeSlot ( const char *  target,
int  slot 
)

Copies an existing save file to the first empty slot which is not autosave

Parameters
targetName of a config manager target.
slotSlot number of the save state.
Returns
true if an empty slot was found and the save state was copied. false otherwise.

◆ parseSavegameHeader()

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

Parse the extended savegame header to retrieve the SaveStateDescriptor information.

◆ fillDummyHeader()

static void MetaEngine::fillDummyHeader ( ExtendedSavegameHeader header)
static

Populate the given extended savegame header with dummy values.

This is used when failing to read the header from a savegame file.

◆ decodeSavegameDate()

static void MetaEngine::decodeSavegameDate ( const ExtendedSavegameHeader header,
uint16 &  outYear,
uint8 &  outMonth,
uint8 &  outDay 
)
static

Decode the date from a savegame header into a calendar date. The month and day are both 1-based.

◆ decodeSavegameTime()

static void MetaEngine::decodeSavegameTime ( const ExtendedSavegameHeader header,
uint8 &  outHour,
uint8 &  outMinute 
)
static

Decode the time from a savegame header into a wall clock time.

◆ readSavegameHeader()

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

Read the extended savegame header from the given savegame file.


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