#include <metaengine.h>

Inheritance diagram for MetaEngine:

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::OptionsContainerWidget *	buildEngineOptionsWidget (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::AchievementDescriptionList *	getAchievementDescriptionList () 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

enum MetaEngine::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

target Name 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

target Name 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, DarkseedMetaEngine, QDEngineMetaEngine, 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

syst	Pointer to the global OSystem object.
engine	Pointer to a pointer that the MetaEngine sets to the newly created Engine, or 0 in case of an error.
gameDescriptor	Detected game as returned by MetaEngineDetection::identifyGame
meDescriptor	Pointer 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

engine	Pointer to the Engine that MetaEngine created.
gameDescriptor	Detected game as returned by MetaEngineDetection::identifyGame
meDescriptor	Pointer 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

target Name 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

target	Name of a config manager target.
saveMode	If 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

target	Name of a config manager target.
slot	Slot 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

target	Name of a config manager target.
slot	Slot 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

saveGameIdx	Index of the save, or kSavegameFilePattern for returning a filename pattern.
target	Game 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

target Game 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, DarkseedMetaEngine, 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

target Name 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

boss	The widget or dialog that the returned widget is a child of.
name	The name that the returned widget must use.
target	Name 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

target Name 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

target Name 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, DarkseedMetaEngine, QDEngineMetaEngine, 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

target	Name of a config manager target.
slot	Slot 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:

engines/metaengine.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ MetaEngineFeature

Member Function Documentation

◆ getSavegameThumbnail()

◆ findEmptySaveSlot()

◆ getExtraGuiOptions()

◆ getName()

◆ createInstance()

◆ deleteInstance()

◆ listSaves() [1/2]

◆ listSaves() [2/2]

◆ getAutosaveSlot()

◆ getMaximumSaveSlot()

◆ removeSaveState()

◆ querySaveMetaInfos()

◆ getSavegameFile()

◆ getSavegameFilePattern()

◆ initKeymaps()

◆ registerDefaultSettings()

◆ buildEngineOptionsWidget()

◆ getAchievementsPlatform()

◆ getAchievementsInfo()

◆ getAchievementDescriptionList()

◆ hasFeature()

◆ appendExtendedSave()

◆ appendExtendedSaveToStream()

◆ copySaveFileToFreeSlot()

◆ parseSavegameHeader()

◆ fillDummyHeader()

◆ decodeSavegameDate()

◆ decodeSavegameTime()

◆ readSavegameHeader()