736
edits
Difference between revisions of "Advanced Engine Features"
m
Fullpipe renamed to NGI.
m (Gob has a console now.) |
m (Fullpipe renamed to NGI.) |
||
| (82 intermediate revisions by 15 users not shown) | |||
| Line 1: | Line 1: | ||
In the following, some of the more advanced features a ScummVM Engine may implement are described. We describe what advantage each feature gives to the engine author respectively to engine users, and sketch how to implement support for it. Features are roughly grouped and sorted by mutual dependency. | In the following, some of the more advanced features a ScummVM Engine may implement are described. We describe what advantage each feature gives to the engine author respectively to engine users, and sketch how to implement support for it.<br>Features are roughly grouped and sorted by mutual dependency. | ||
==Enhanced user interaction== | ==Enhanced user interaction== | ||
| Line 18: | Line 18: | ||
'''Relevant Engine API''' | '''Relevant Engine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
virtual void pauseEngineIntern(bool pause); | virtual void pauseEngineIntern(bool pause); | ||
void pauseEngine(bool pause); | void pauseEngine(bool pause); | ||
bool isPaused() const; | bool isPaused() const; | ||
</ | </syntaxhighlight> | ||
''' | '''Implemented by:''' | ||
[[AGOS]], [[Gob]], [[Kyra]], [[Lure]], [[Parallaction]], [[SAGA]], [[SCUMM]], [[Sword2]] | [[AGOS]], [[Draci]], [[Gob]], [[Kyra]], [[Lure]], [[Mohawk]], [[Mortevielle]], [[Parallaction]], [[Pegasus]], [[SAGA]], [[SCI]], [[SCUMM]], [[Supernova]], [[Sword2]], [[Toon]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' | ||
[[AGI]], [[Cine]], [[CruisE]], [[Drascula]], [[Groovie]], [[ | [[AGI]], [[Avalanche]], [[CGE]], [[Cine]], [[Composer]], [[CruisE]], [[Drascula]], [[Dreamweb]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Lastexpress]], [[MADE]], [[Neverhood]], [[NGI]], [[Queen]], [[Sky]], [[Sword1]], [[Sword25]], [[Tinsel]], [[Toltecs]], [[Tony]], [[Touche]], [[TsAGE]], [[Tucker]], [[Wintermute]] | ||
'''Support not necessary:''' | |||
[[TeenAgent]] | |||
===RTL ("Return to Launcher") support=== | ===RTL ("Return to Launcher") support=== | ||
| Line 35: | Line 38: | ||
'''How to implement it'''<br> | '''How to implement it'''<br> | ||
You can implement this by checking for and honoring the | You can implement this by checking for and honoring the EVENT_RETURN_TO_LAUNCHER event. A much easier way, which also gives you some other advantages (e.g. this also covers EVENT_QUIT), is to regularly poll the return value of Engine::shouldQuit(). If it returns true, you should break out from your main game loop and your Engine::run() method should return to the caller. | ||
'''Relevant Engine API''' | '''Relevant Engine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
void quitGame(); | |||
bool shouldQuit() const; | bool shouldQuit() const; | ||
kSupportsReturnToLauncher feature flag | |||
</syntaxhighlight> | |||
''' | '''Implemented by:''' | ||
[[AGI]], [[AGOS]], [[Cine]], [[Gob]], [[Groovie]], [[Kyra]], [[Lure]], [[MADE]], [[Parallaction]], [[Queen]], [[SAGA]], [[SCUMM]], [[Sky]], [[Sword1]], [[Sword2]], [[Touche]], [[Tucker]] | [[AGI]], [[AGOS]], [[CGE]], [[Cine]], [[Composer]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Gob]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lastexpress]], [[Lure]], [[MADE]], [[Mohawk]], [[Mortevielle]], [[Neverhood]], [[NGI]], [[Parallaction]], [[Pegasus]], [[Queen]], [[SAGA]], [[SCI]], [[SCUMM]], [[Sky]], [[Supernova]], [[Sword1]], [[Sword2]], [[Sword25]], [[TeenAgent]], [[Tinsel]], [[Toltecs]], [[Tony]], [[Toon]], [[Touche]], [[TsAGE]], [[Tucker]], [[Wintermute]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' [[Avalanche]] | ||
===Global options dialog support=== | ===Global options dialog support=== | ||
| Line 57: | Line 61: | ||
'''Relevant Engine API''' | '''Relevant Engine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
virtual void syncSoundSettings(); | |||
</syntaxhighlight> | |||
''' | '''Implemented by:''' | ||
[[ | [[AGOS]], [[Cine]], [[CruisE]], [[Draci]], [[Gob]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lastexpress]], [[Lure]], [[MADE]], [[Queen]], [[SAGA]], [[SCI]], [[SCUMM]], [[Sky]], [[Sword1]], [[Sword2]], [[Toltecs]], [[Tony]], [[Touche]], [[TsAGE]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' | ||
[[ | [[Avalanche]], [[CGE]], [[Composer]], [[Drascula]], [[Dreamweb]], [[Mohawk]], [[Neverhood]], [[NGI]], [[Parallaction]], [[Pegasus]], [[Sword25]], [[Tucker]], [[Wintermute]] | ||
'''Support not necessary:''' [[AGI]], [[Mortevielle]], [[TeenAgent]], [[Tinsel]], [[Toon]] | |||
===GMM ("Global Main Menu") support=== | ===GMM ("Global Main Menu") support=== | ||
| Line 78: | Line 86: | ||
None. | None. | ||
''' | '''Implemented by:''' | ||
''not applicable'' | ''not applicable'' | ||
| Line 87: | Line 95: | ||
In this section, we present various MetaEngine and Engine APIs which greatly experience | In this section, we present various MetaEngine and Engine APIs which greatly experience | ||
the user experience with regards to savestates. | the user experience with regards to savestates. These days, the bulk of logic for listing, loading, saving, or deleting savegames is provided by the Engine class. As engine writers you only need to override loadGameStream & saveGameStream to read and write data from savefiles. | ||
| Line 93: | Line 101: | ||
'''What is this about?'''<br> | '''What is this about?'''<br> | ||
With this feature, it is possible to build a list of available save slots for a given game target. This can be used by the user to list all saveslots from the command line, as the following example illustrates: | With this feature, it is possible to build a list of available save slots for a given game target. This can be used by the user to list all saveslots from the command line, as the following example illustrates: | ||
< | <syntaxhighlight lang="bash"> | ||
$ ./scummvm --list-saves --game=monkey2 | |||
Saves for target 'monkey2': | Saves for target 'monkey2': | ||
Slot Description | Slot Description | ||
| Line 100: | Line 109: | ||
1 Start | 1 Start | ||
2 Quicksave 2 | 2 Quicksave 2 | ||
$</ | $ | ||
</syntaxhighlight> | |||
Furthermore, this is used by the load/save dialogs in the Launcher and the GMM to build the list of savestates they show visually to the user. | Furthermore, this is used by the load/save dialogs in the Launcher and the GMM to build the list of savestates they show visually to the user. | ||
'''How to implement it'''<br> | '''How to implement it'''<br> | ||
You | You probably don't. Newly created engines, which use loadGameStream & saveGameStream, automatically use the extended savegame format. With this, the Engine class already provides a default implementation of listSaves for you. However, if for some reason you want to override it, such as if you're providing your own custom savegame implementation from scratch, the method is passed a parameter indicating the target for which the list of savestates is requested. From this, you can (using the config manager) determine the path to the game data, if necessary, or just directly compute all available savestates. Details necessarily depend on your Engine, but looking at existing implementations should give you a fairly good idea how to tackle this. | ||
Another requirement is MetaEngine::getMaximumSaveSlot, which returns the maximum save slot number supported by your engine. This is for example used by the GUI to show up empty slots correctly. | Another requirement is MetaEngine::getMaximumSaveSlot, which returns the maximum save slot number supported by your engine. This is for example used by the GUI to show up empty slots correctly. | ||
| Line 113: | Line 123: | ||
'''Relevant MetaEngine API''' | '''Relevant MetaEngine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
virtual SaveStateList listSaves(const char *target) const; | |||
virtual int getMaximumSaveSlot() const; | virtual int getMaximumSaveSlot() const; | ||
kSupportsListSaves feature flag</ | kSupportsListSaves feature flag | ||
</syntaxhighlight> | |||
''' | '''Implemented by:''' | ||
[[AGI]], [[AGOS]], [[Cine]], [[Groovie]], [[Kyra]], [[Lure]], [[Parallaction]], [[Queen]], [[SAGA]], [[SCUMM]], [[Sky]], [[Sword1]], [[Sword2]], [[Tinsel]], [[Touche]], [[Tucker]] | [[AGI]], [[AGOS]], [[Avalanche]], [[CGE]], [[Cine]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lure]], [[Mohawk]], [[Mortevielle]], [[Neverhood]], [[Parallaction]], [[Pegasus]], [[Queen]], [[SAGA]], [[SCI]], [[SCUMM]], [[Sky]], [[Supernova]], [[Sword1]], [[Sword2]], [[Sword25]], [[Tinsel]], [[Toltecs]], [[Tony]], [[Toon]], [[Touche]], [[Tucker]], [[Wintermute]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' | ||
[[ | [[Composer]], [[Gob]], [[Lastexpress]], [[MADE]], [[NGI]], [[TeenAgent]], [[TsAGE]] | ||
===Loading savestates via command line or Launcher=== | ===Loading savestates via command line or Launcher=== | ||
| Line 132: | Line 144: | ||
'''Relevant MetaEngine API''' | '''Relevant MetaEngine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
save_slot ConfigMan setting | |||
kSupportsLoadingDuringStartup feature flag</ | kSupportsLoadingDuringStartup feature flag | ||
</syntaxhighlight> | |||
''' | '''Implemented by:''' | ||
[[AGI]], [[Cine]], [[Groovie]], [[Kyra]], [[Lure]], [[ | [[AGI]], [[Avalanche]], [[Cine]], [[CGE]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lure]], [[Mohawk]], [[Mortevielle]], [[Neverhood]], [[Pegasus]], [[Queen]], [[SAGA]], [[SCI]], [[SCUMM]], [[Sky]], [[Supernova]], [[Sword1]], [[Sword2]], [[TeenAgent]], [[Tinsel]], [[Toltecs]], [[Tony]], [[Toon]], [[Touche]], [[TsAGE]], [[Tucker]], [[Wintermute]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' | ||
[[AGOS]], [[ | [[AGOS]], [[Composer]], [[Gob]], [[Lastexpress]], [[MADE]], [[NGI]], [[Parallaction]], [[Sword25]] | ||
===Deleting savestates via the Launcher and GMM=== | ===Deleting savestates via the Launcher and GMM=== | ||
| Line 153: | Line 167: | ||
'''Relevant MetaEngine API''' | '''Relevant MetaEngine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
void removeSaveState(const char *target, int slot) const; | |||
kSupportsDeleteSave feature flag</ | kSupportsDeleteSave feature flag | ||
</syntaxhighlight> | |||
''' | '''Implemented by:''' | ||
[[AGI]], [[Cine]], [[Groovie]], [[Kyra]], [[Lure]], [[Parallaction]], [[Queen]], [[SAGA]], [[SCUMM]], [[Sky]], [[Sword2]], [[Tinsel]], [[Touche]], [[Tucker]] | [[AGI]], [[Avalanche]], [[Cine]], [[CGE]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lure]], [[Mohawk]], [[Neverhood]], [[Parallaction]], [[Pegasus]], [[Queen]], [[SAGA]], [[SCI]], [[SCUMM]], [[Sky]], [[Supernova]], [[Sword1]], [[Sword2]], [[TeenAgent]], [[Tinsel]], [[Toltecs]], [[Tony]], [[Toon]], [[Touche]], [[TsAGE]], [[Tucker]], [[Wintermute]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' | ||
[[AGOS]], [[ | [[AGOS]], [[Composer]], [[Gob]], [[Lastexpress]], [[MADE]], [[Mortevielle]], [[NGI]], [[Sword25]] | ||
===Savestate metadata support=== | ===Savestate metadata support=== | ||
| Line 173: | Line 189: | ||
'''Relevant MetaEngine API''' | '''Relevant MetaEngine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
virtual SaveStateDescriptor querySaveMetaInfos(const char *target, int slot) const; | |||
kSavesSupportMetaInfo feature flag | kSavesSupportMetaInfo feature flag | ||
kSavesSupportThumbnail feature flag | kSavesSupportThumbnail feature flag | ||
kSavesSupportCreationDate feature flag | kSavesSupportCreationDate feature flag | ||
kSavesSupportPlayTime feature flag</ | kSavesSupportPlayTime feature flag | ||
</syntaxhighlight> | |||
''' | '''Implemented by:''' | ||
[[AGI]], [[Kyra]], [[SAGA]], [[SCUMM]] | [[AGI]], [[Avalanche]], [[CGE]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Mortevielle]], [[Neverhood]], [[SAGA]], [[SCI]], [[SCUMM]], [[Supernova]], [[Sword1]], [[TeenAgent]], [[Toltecs]], [[Tony]], [[Toon]], [[TsAGE]], [[Tucker]], [[Wintermute]], [[ZVision]] | ||
'''Not implemented by:''' | '''Not implemented by:''' | ||
[[AGOS]], [[Cine]], [[ | [[AGOS]], [[Cine]], [[Composer]], [[Gob]], [[Lastexpress]], [[Lure]], [[Mohawk]], [[MADE]], [[NGI]], [[Parallaction]], [[Pegasus]], [[Queen]], [[Sky]], [[Sword2]], [[Sword25]], [[Touche]], [[Tinsel]] | ||
===Loading/Saving during run time=== | ===Loading/Saving during run time=== | ||
| Line 193: | Line 211: | ||
'''How to implement it'''<br> | '''How to implement it'''<br> | ||
Unlike | Unlike the other features presented above, this is an ability of your Engine subclass, not of MetaEngine. First thing, you have to advertise the abilities of your engines with the appropriate engine feature flags. You can implement only loading, or only saving, or both. | ||
Next, for each of the two, you have to implement two Engine methods (so up to four). We focus on adding loading support here: For that, first implement Engine::canLoadGameStateCurrently(). This method should only return true if loading a savestate is possible right now. If this is always possible, just always return true. But if loading is not possible at some points, say while a cutscene is playing, make it return false at these times. | Next, for each of the two, you have to implement two Engine methods (so up to four). We focus on adding loading support here: For that, first implement Engine::canLoadGameStateCurrently(). This method should only return true if loading a savestate is possible right now. If this is always possible, just always return true. But if loading is not possible at some points, say while a cutscene is playing, make it return false at these times. | ||
Next, the Engine:: | Next, the Engine::loadGameStream() is used to load save file data. Previously, this was loadGameState, but engines using it had to manually open the save files, so it's now deprecated. The GMM will invoke this method with a valid stream from an opened save file, allowing the engine to read from it. If there is an immediate error, you can indicate so with its return value (for details, refer to the doxygen comments), in which case the GMM will show an appropriate error dialog. In | ||
'''Relevant Engine API''' | '''Relevant Engine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
virtual Common::Error Engine::loadGameStream(Common::SeekableReadStream *stream); | |||
virtual bool canLoadGameStateCurrently(); | virtual bool canLoadGameStateCurrently(); | ||
kSupportsLoadingDuringRuntime feature flag | kSupportsLoadingDuringRuntime feature flag | ||
</syntaxhighlight> | |||
Saving games is similar. Engines can override saveGameStream (rather than the now deprecated saveGameState). In this case, it gets passed in a write stream to a save file opened for saving. Additionally, it also gets passed a flag for whether an autosave is being created vs a save done by the user. Some engines may want to show a message or other indication in the UI after a save is done, but which shouldn't be done for regular autosaves. | |||
<syntaxhighlight lang="cpp"> | |||
virtual Common::Error Engine::saveGameStream(Common::WriteStream *stream, bool isAutosave); | |||
virtual bool canSaveGameStateCurrently(); | |||
kSupportsSavingDuringRuntime feature flag | |||
</syntaxhighlight> | |||
==Misc== | ==Misc== | ||
| Line 225: | Line 245: | ||
'''Relevant Engine API''' | '''Relevant Engine API''' | ||
< | <syntaxhighlight lang="cpp"> | ||
virtual void errorString(const char *buf_input, char *buf_output, int buf_output_size); | |||
</syntaxhighlight> | |||
''' | :'''Implemented by:''' [[SCUMM]] | ||
'''Not implemented by:''' | :'''Not implemented by:''' [[AGI]], [[AGOS]], [[Avalanche]], [[Cine]], [[CGE]], [[Composer]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Gob]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lastexpress]], [[Lure]], [[MADE]], [[Mohawk]], [[Mortevielle]], [[Neverhood]], [[NGI]], [[Parallaction]], [[Pegasus]], [[Queen]], [[SAGA]], [[SCI]], [[Sky]], [[Sword1]], [[Sword2]], [[Sword25]], [[TeenAgent]], [[Tinsel]], [[Toltecs]], [[Tony]], [[Toon]], [[Touche]], [[TsAGE]], [[Tucker]], [[Wintermute]], [[ZVision]] | ||
<syntaxhighlight lang="cpp"> | |||
virtual GUI::Debugger *getDebugger(); | |||
</syntaxhighlight> | |||
:'''Implemented by:''' [[AGI]], [[AGOS]], [[Avalanche]], [[Cine]], [[CGE]], [[Composer]], [[CruisE]], [[Draci]], [[Drascula]], [[Dreamweb]], [[Gob]], [[Groovie]], [[Hopkins]], [[Hugo]], [[Kyra]], [[Lastexpress]], [[Lure]], [[MADE]], [[Mohawk]], [[Mortevielle]], [[Neverhood]], [[NGI]], [[Parallaction]], [[Pegasus]], [[Queen]], [[SAGA]], [[SCI]], [[SCUMM]], [[Sky]], [[Sword1]], [[Sword2]], [[Sword25]], [[TeenAgent]], [[Tinsel]], [[Toltecs]], [[Toon]], [[Tony]], [[Touche]], [[TsAGE]], [[Tucker]], [[Wintermute]], [[ZVision]] | |||
:'''Not implemented by:''' | |||