265
edits
Difference between revisions of "HOWTO-Engines"
Jump to navigation
Jump to search
m
Mention new optional engine skeleton style
(Removed references to quux and the quoted example. Automated way is to go) |
Dreammaster (talk | contribs) m (Mention new optional engine skeleton style) |
||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 22: | Line 22: | ||
=== Common Instructions === | === Common Instructions === | ||
There are two styles of engine skeletons supported. The first, if you just specify an engine name, creates a bare bones engine with a sample event loop. The second kind is selected if you also specify -events as an extra parameter after the engine name. In this case, it creates a more sophisticated engine skeleton that has a single centralized event loop, and dispatches events to views, which can be easily switched between. This has benefits of avoiding duplicating event loops in multiple different places, each handling event processing and quit checks. Each view simply has to implement a drawing method and override different event handler methods to handle whichever events it needs. | |||
In either case, once you've got the skeleton engine compiling, your next step should be to update the placeholder detection entry in detection_tables.h. The easiest way is to choose a file in your game's folder that you think is unique, and change the filename in the detection entry to it. If you then run ScummVM and try to add the game, it should prompt you that an unrecognised md5 for the game has been found, and give you the option to copy it to clipboard. You can do so, and then paste it to extract the md5 and filesize for the file, which can be used to update the detection entry. With this done you should be able to add your game, and run the skeleton engine. | |||
As a second optional step, by default everytime your game starts, you'll get an unsupported game warning dialog appear. If you want to suppress it, locate and open your scummvm.ini file, and find the section added for your game. Then add the following line to it: | As a second optional step, by default everytime your game starts, you'll get an unsupported game warning dialog appear. If you want to suppress it, locate and open your scummvm.ini file, and find the section added for your game. Then add the following line to it: | ||
| Line 33: | Line 34: | ||
=== File name conventions === | === File name conventions === | ||
Over the course of its existence, many people will have to deal with the source code of a given engine. Be it to fix bugs in it, modify it to still compile after changes made to the backend code, or to simply add new functionality. It is therefore expected to adhere to various conventions used throughout all engines. Besides source code conventions (see [[Code Formatting Conventions]]), this affects filenames. We suggest you use the following names for specific parts of your engine: | |||
{| border="1" cellpadding="2" width=100% | {| border="1" cellpadding="2" width=100% | ||
| Line 47: | Line 48: | ||
|saveload.cpp || Code related to savegames | |saveload.cpp || Code related to savegames | ||
|- | |- | ||
| | |console.cpp || (console) debugger | ||
|- | |- | ||
|gfx.cpp (alt: graphics.cpp) || Graphics code | |gfx.cpp (alt: graphics.cpp) || Graphics code | ||
| Line 127: | Line 128: | ||
=== True RGB color support === | === True RGB color support === | ||
If you need to support more than 256 colors in your game engine, please refer to [[API-Truecolor|the truecolor API reference page]] for specifications and initialization protocol. | If you need to support more than 256 colors in your game engine, please refer to [[API-Truecolor|the truecolor API reference page]] for specifications and initialization protocol. | ||
== Extended Saves == | |||
To easily support ScummVM-specific metadata in the saves, we implemented the ExtendedSaves interface. | |||
This basically makes your saves look like this: | |||
<DATA> Engine-specific save data | |||
<METAINFO> ScummVM metainfo, including play time, screenshot, save name etc | |||
<OFFSET> 4-bytes offset to the the ScummVM metainfo from the end of the save | |||
Thus, all generic methods like listSaves() are retrieving this information. | |||
In order to benefit from it, do the following: | |||
# In MetaEngine::hasFeature(), add kSavesUseExtendedFormat, kSimpleSaveNames, kSupportsListSaves, kSupportsDeleteSave, kSavesSupportMetaInfo, kSavesSupportThumbnail, kSavesSupportCreationDate, and kSavesSupportPlayTime. Also kSupportsLoadingDuringStartup if you intend to support loading savegames directly from the launcher. | |||
# Overload loadGameStream() and saveGameStream() where you parse/save only your engine-specific data | |||
# ... | |||
# PROFIT! | |||
== General Tips == | |||
* During the initial porting process, it might be preferable to link to C++ STL. In such cases, the `FORBIDDEN_SYMBOL_ALLOW_ALL` define can be used. However, you'll eventually need to get rid of this define. | |||