-
-
Notifications
You must be signed in to change notification settings - Fork 998
/
metaengine.h
626 lines (556 loc) · 20.5 KB
/
metaengine.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
/* ScummVM - Graphic Adventure Engine
*
* ScummVM is the legal property of its developers, whose names
* are too numerous to list here. Please refer to the COPYRIGHT
* file distributed with this source distribution.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*
*/
#ifndef ENGINES_METAENGINE_H
#define ENGINES_METAENGINE_H
#include "common/achievements.h"
#include "common/scummsys.h"
#include "common/error.h"
#include "common/array.h"
#include "engines/game.h"
#include "engines/savestate.h"
#include "base/plugins.h"
class Engine;
class OSystem;
namespace Common {
class Keymap;
class FSList;
class OutSaveFile;
class String;
typedef SeekableReadStream InSaveFile;
}
namespace Graphics {
struct Surface;
}
namespace GUI {
class GuiObject;
class OptionsContainerWidget;
}
/**
* @defgroup engines_metaengine Meta engine
* @ingroup engines
*
* @brief API for managing various functions of the meta engine.
*
* @{
*/
/**
* Per-game extra GUI options structure.
* Currently, this can only be used for options with checkboxes.
*/
struct ExtraGuiOption {
const char *label; /*!< Option label, e.g. "Fullscreen mode". */
const char *tooltip; /*!< Option tooltip shown when the mouse cursor hovers over it. */
const char *configOption; /*!< confMan key, e.g. "fullscreen". */
bool defaultState; /*!< Default state of the checkbox (checked or not). */
};
/**
* debug channels structure
*/
struct DebugChannelDef {
uint32 channel; /*!< enum value, channel id, e.g. kDebugGlobalDetection */
const char *name; /*!< name of debug channel, e.g. "detection" */
const char *description; /*!< description of debug channel, e.g. "track scripts" */
};
/**
* delimiter of the array of DebugChannelDef
*/
#define DEBUG_CHANNEL_END {0, NULL, NULL}
/**
* Array of ExtraGuiOption structures.
*/
typedef Common::Array<ExtraGuiOption> ExtraGuiOptions;
/**
* @todo Doc required
*/
enum { kSavegameFilePattern = -99 };
#define EXTENDED_SAVE_VERSION 4
/**
* Structure describing a savegame file.
*/
struct ExtendedSavegameHeader {
char id[6]; /*!< ID of the savegame file. */
uint8 version; /*!< Version of the savegame header. */
Common::String saveName; /*!< Name of the savegame. */
Common::String description; /*!< Description of the savegame, as entered by the user. */
uint32 date; /*!< Date of the savegame. */
uint16 time; /*!< Time of the savegame. */
uint32 playtime; /*!< Total play time until this savegame. */
Graphics::Surface *thumbnail; /*!< Screen content shown as a thumbnail for this savegame. */
bool isAutosave; /*!< Whether this savegame is an autosave. */
ExtendedSavegameHeader() {
memset(id, 0, 6);
version = 0;
date = 0;
time = 0;
playtime = 0;
thumbnail = nullptr;
isAutosave = false;
}
};
/**
* A meta engine 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 MetaEngineDetection
* subclass for that "engine plugin". For example, SCUMM provides ScummMetaEngineDetection.
* This is then in turn used by the frontend code to detect games, and other useful functionality.
*
* To instantiate actual Engine objects, see the class @ref MetaEngine.
*/
class MetaEngineDetection : public PluginObject {
public:
virtual ~MetaEngineDetection() {}
/** Get the engine ID. */
virtual const char *getEngineId() const = 0;
/** Return some copyright information about the original engine. */
virtual const char *getOriginalCopyright() const = 0;
/** Return a list of games supported by this engine. */
virtual PlainGameList getSupportedGames() const = 0;
/** Query the engine for a PlainGameDescriptor for the specified gameid, if any. */
virtual PlainGameDescriptor findGame(const char *gameId) const = 0;
/**
* Run the engine's game detector on the given list of files, and return a
* (possibly empty) list of games supported by the engine that were
* found among the given files.
*/
virtual DetectedGames detectGames(const Common::FSList &fslist) const = 0;
/**
* 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.
*
* @param target Name of a config manager target.
*
* @return A list of extra GUI options for an engine plugin and target.
*/
virtual const ExtraGuiOptions getExtraGuiOptions(const Common::String &target) const {
return ExtraGuiOptions();
}
/**
* Return a list of engine specified debug channels
*
* If engine has no specified debug channels or not supported yet, then it will return NULL
*
* @return A list of engine specified debug channels
*/
virtual const DebugChannelDef *getDebugChannels() const {
return NULL;
}
/**
* Register the default values for the settings that the engine uses into the
* configuration manager.
*
* @param target Name of a config manager target.
*/
void registerDefaultSettings(const Common::String &target) const;
/**
* 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 option dialogs, but by default a simple widget
* allowing to configure the extra GUI options is used.
*
* Engines that are not supposed to have an Engine tab in the Edit Game dialog
* can return nullptr.
*
* @param boss The widget or dialog that the returned widget is a child of.
* @param name The name that the returned widget must use.
* @param target Name of a config manager target.
*/
GUI::OptionsContainerWidget *buildEngineOptionsWidgetStatic(GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const;
};
/**
* 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.
*/
class MetaEngine : public PluginObject {
protected:
/**
* 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.
*/
virtual void getSavegameThumbnail(Graphics::Surface &thumb);
/**
* Finds the first empty save slot that can be used for this target
* @param target Name of a config manager target.
*
* @return The first empty save slot, or -1 if all are occupied.
*/
int findEmptySaveSlot(const char *target);
public:
virtual ~MetaEngine() {}
/**
* 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.
*/
virtual const char *getName() const = 0;
/**
* 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.
*
* @param syst Pointer to the global OSystem object.
* @param engine Pointer to a pointer that the MetaEngine sets to
* the newly created Engine, or 0 in case of an error.
*
* @return A Common::Error describing the error that occurred, or kNoError.
*/
virtual Common::Error createInstance(OSystem *syst, Engine **engine) const = 0;
/**
* 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.
*
* @param target Name of a config manager target.
*
* @return A list of save state descriptors.
*/
virtual SaveStateList listSaves(const char *target) 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.
*
* @param target Name of a config manager target.
* @param saveMode If true, get the list for a save dialog.
* @return A list of save state descriptors.
*/
SaveStateList listSaves(const char *target, bool saveMode) const;
/**
* 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.
*/
virtual int getAutosaveSlot() const {
return 0;
}
/**
* 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).
*
* @return Maximum save slot number supported.
*/
virtual int getMaximumSaveSlot() const {
// For games using the new save format, assume 99 slots by default
return hasFeature(kSavesUseExtendedFormat) ? 99 : 0;
}
/**
* 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.
*
* @param target Name of a config manager target.
* @param slot Slot number of the save state to be removed.
*/
virtual void removeSaveState(const char *target, int slot) const;
/**
* Return meta information from the specified save state.
*
* Depending on the MetaEngineFeatures set, this can include
* thumbnails, save date and time, play time.
*
* @param target Name of a config manager target.
* @param slot Slot number of the save state.
*/
virtual SaveStateDescriptor querySaveMetaInfos(const char *target, int slot) const;
/**
* Return the name of the save file for the given slot and optional target,
* or a pattern for matching filenames against.
*
* @param saveGameIdx Index of the save, or kSavegameFilePattern
* for returning a filename pattern.
* @param target Game target. If omitted, then the engine ID is used.
*/
virtual Common::String getSavegameFile(int saveGameIdx, const char *target = nullptr) const;
/**
* Return the pattern for save files.
*
* @param target Game target. If omitted, then the engine ID is used.
*/
Common::String getSavegameFilePattern(const char *target = nullptr) const {
return getSavegameFile(kSavegameFilePattern, target);
}
/**
* Return the keymap used by the target.
*/
virtual Common::Array<Common::Keymap *> initKeymaps(const char *target) const;
/**
* Register the default values for the settings that the engine uses into the
* configuration manager.
*
* @param target Name of a config manager target.
*/
virtual void registerDefaultSettings(const Common::String &target) const {}
/**
* 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.
*
* @param boss The widget or dialog that the returned widget is a child of.
* @param name The name that the returned widget must use.
* @param target Name of a config manager target.
*/
virtual GUI::OptionsContainerWidget *buildEngineOptionsWidgetDynamic(GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const {
return nullptr;
}
/**
* MetaEngine feature flags.
*
* A feature in this context means an ability of the engine that can be
* either available or not.
*/
enum MetaEngineFeature {
/**
* 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.
*/
kSupportsListSaves,
/**
* Load from the launcher or command line (-x).
*/
kSupportsLoadingDuringStartup,
/**
* Delete saves from the launcher.
*
* This means that the engine implements the removeSaveState() method.
*/
kSupportsDeleteSave,
/**
* 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'.
*/
kSavesSupportMetaInfo,
/**
* 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.
*/
kSavesSupportThumbnail,
/**
* Feature @c save_date and @c 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.
*/
kSavesSupportCreationDate,
/**
* Feature @c 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.
*/
kSavesSupportPlayTime,
/**
* This feature is available if the engine's saves can be detected
* with:
* @code
* <target>.###
* @endcode
* 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.
*/
kSimpleSavesNames,
/**
* 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
*/
kSavesUseExtendedFormat
};
/**
* Return a list of achievement descriptions for the specified target.
*
* @param target Name of a config manager target.
*
* @return A list of achievement descriptions for an engine plugin and target.
*/
virtual const Common::AchievementsInfo getAchievementsInfo(const Common::String &target) const;
/**
* Return the achievement descriptions.
*
* @note The default implementation returns @c nullptr
*
* @return a list of achievement descriptions for an engine.
*/
virtual const Common::AchievementDescriptionList* getAchievementDescriptionList() const {
return nullptr;
}
/**
* Determine whether the engine supports the specified MetaEngine feature.
*
* Used by e.g. the launcher to determine whether to enable the Load button.
*/
virtual bool hasFeature(MetaEngineFeature f) const;
/**
* Write the extended savegame header to the given savegame file.
*/
void appendExtendedSave(Common::OutSaveFile *saveFile, uint32 playtime, Common::String desc, bool isAutosave);
/**
* Write the extended savegame header to the given WriteStream.
*/
void appendExtendedSaveToStream(Common::WriteStream *saveFile, uint32 playtime, Common::String desc, bool isAutosave, uint32 offset = 0);
/**
* Copies an existing save file to the first empty slot which is not autosave
* @param target Name of a config manager target.
* @param slot Slot number of the save state.
*
* @return true if an empty slot was found and the save state was copied. false otherwise.
*/
bool copySaveFileToFreeSlot(const char *target, int slot);
/**
* Parse the extended savegame header to retrieve the SaveStateDescriptor information.
*/
static void parseSavegameHeader(ExtendedSavegameHeader *header, SaveStateDescriptor *desc);
/**
* Populate the given extended savegame header with dummy values.
*
* This is used when failing to read the header from a savegame file.
*/
static void fillDummyHeader(ExtendedSavegameHeader *header);
/**
* Read the extended savegame header from the given savegame file.
*/
static WARN_UNUSED_RESULT bool readSavegameHeader(Common::InSaveFile *in, ExtendedSavegameHeader *header, bool skipThumbnail = true);
};
/**
* Singleton class that manages all engine plugins.
*/
class EngineManager : public Common::Singleton<EngineManager> {
public:
/**
* Given a list of FSNodes in a given directory, detect a set of games contained within.
*
* Returns an empty list if none are found.
*/
DetectionResults detectGames(const Common::FSList &fslist) const;
/** Find a plugin by its engine ID. */
const Plugin *findPlugin(const Common::String &engineId) const;
/**
* Get the list of all plugins for the type specified.
*
* By default, it will get METAENGINES, for now.
* If usage of actual engines never occurs, the default arguments can be skipped,
* and always have it return PLUGIN_TYPE_ENGINE_DETECTION.
*/
const PluginList &getPlugins(const PluginType fetchPluginType = PLUGIN_TYPE_ENGINE_DETECTION) const;
/** Find a target. */
QualifiedGameDescriptor findTarget(const Common::String &target, const Plugin **plugin = NULL) const;
/**
* List games matching the specified criteria.
*
* If the engine ID is not specified, this scans all the plugins,
* loading them from the disk if necessary. This is a slow operation on
* some platforms and should not be used for the happy path.
*/
QualifiedGameList findGamesMatching(const Common::String &engineId, const Common::String &gameId) const;
/**
* Create a target from the supplied game descriptor.
*
* @return The created target name.
*/
Common::String createTargetForGame(const DetectedGame &game);
/** Upgrade a target to the current configuration format. */
void upgradeTargetIfNecessary(const Common::String &target) const;
private:
/** Find a game across all loaded plugins. */
QualifiedGameList findGameInLoadedPlugins(const Common::String &gameId) const;
/** Use heuristics to complete a target lacking an engine ID. */
void upgradeTargetForEngineId(const Common::String &target) const;
};
/** Convenience shortcut for accessing the engine manager. */
#define EngineMan EngineManager::instance()
/** @} */
#endif