End of GSoC

Hey everyone, GSoC has come to an end and I would just like to say that it's been a great experience for me. I've learned a whole lot. I'd like to say thank you to Max for having been such a great mentor for me, always there when I needed help, and giving good advice. And thanks to everyone else who has helped me along the way as well.

I've provided a project summary which summarizes most everything that I've done this summer, as well as a list of things that could be done to further build upon this project. I think I will probably stick around for a while and work on some of these things in my spare time as well.

Global Main Menu/ Return To Launcher

Implementing the Return to Launcher (RTL) feature first consisted of identifying and resolving any memory leaks within the engines. Then, reworking and unifying the way that the engines quit.

The first thing I did was to go through each of the engines and fix the memory leaks. I was able to successfully get rid of almost all of the engine related memory leaks, the Agos engine still has one small (20 byte) leak, but it is still able to support RTL. Peres was a great help to me working on some leaks in the Parallaction engine, as well as LordHoto with the Kyra engine.

To properly RTL, it was also necessary to create a unified way for engines to quit. Many engines were using _system->quit() to exit, which was bad. The first steps to solving this problem involved creating a 'quit' flag in order to signal to the engine when to shutdown. I had to find the correct places within the engines to both set and check this 'quit' flag. Since _system->quit() instantly terminates the program, some work was needed to convert the engines which used it to use the quit flag instead.

Once that was done, the engines were tidily returning to the launcher in a similar fashion. Time to implement the Global Main Menu (GMM). The Global Main Menu is based on the Scumm engine's F5 menu. It is pretty much the same thing, except no Save and Load dialogs, and adds on the 'Return to Launcher' button.

At first the RTL functionality from the GMM was accomplished using 'quit' and 'rtl' engine flags. The implementation was then greatly improved, by making use of artificial events which get added to the event manager's event queue. I added a pushEvent() method to the event manager which allows you to create “fake” events and insert them into the event queue. Neat! Stephen Kennedy also made use of this feature for his GSoC project. Next, I added a 'main menu' event as well as a 'rtl' event. The use of 'quit' and 'rtl' flags in the engine was then dropped for the event manager's shouldQuit() and shouldRTL() methods. At this point I went through all of the engines once again and converted them.

Now all of the engines quit and RTL in a uniform manner, and the event manager now keeps track of whether to quit ScummVM or RTL, so the engines need not worry about it.

If an engine needs to quit, it should call its quitGame() method, which sends a 'quit' event to the event manager.

If an engine needs to check whether or not it should shutdown or break out of its game loop, it should call its bool quit() method to check.

No more _system->quit()!

The next objective was to get the sound settings in the 'Options' dialog to function correctly. This involved creating a syncSoundSettings() method for the engines. Some of the engines used the default implementation, however some engines required their own specific implementation. I spent quite a bit (a little too much) time trying to get the settings to work right in all of the engines. These settings are now functional for all of the engines, however there are some improvements that can still be made which involve creating flags to identify if certain sound features (such as speech) are supported by the current game, and use them to show only the relevant controls in the Options dialog.

Savestate Management

The first thing I set out to do regarding save state management improvements was to implement support for –list-saves and –save-slot (-x). Some engines already supported these features, and I added support to many engines which did not have them yet. To accomplish this, I needed to become familiar with the saving/loading system for each engine I provided support for. I also managed to add auto-save support for AGI in the process.

Next I added a 'Load' button to the launcher, which brings up a dialog which lists the save states for the selected game and allows the user to directly load them from the launcher. I then added a 'Delete' button which allows the user to also delete their save games from the launcher. Some engines keep an index file to keep track of their save games, for these engines more work needs to be done before they can support deleting save games.

Since some engines do not support deleting save games, and a couple of engines (Agos and Gob) don't support -x or –list-saves, it's not very nice to make the user figure out which engines support these features. So, I created some meta engine feature flags which can be used to identify which features an engine supports. I use these to give a message to the user if an engine does not support loading from the Launcher, to enable/disable the 'Delete' button in the Launcher, as well as to enable/disable the RTL button in the GMM. The meta engine feature flags may come in handy for other purposes in the future as well.

TODO List

Global Main Menu/Return to Launcher

- Double Quit Confirm Dialogs -

When confirm exit is enabled in ScummVM, the ScummVM quit confirm dialog shows up in addition to the quit confirm dialogs for those games which have their own. For example, when you select 'Quit' from Beneath a Steel Sky's in-game menu, it asks you if you really want to quit. Then, after answering, ScummVM gives you another dialog asking you if you really want to quit. So, ScummVM should not show the quit confirm dialog if the in-game dialog has already been displayed.

This affects any game which has it's own menu system from where you can quit, or has a native quit confirm dialog. So this means most games.

- Options Dialog -

Implement engine flags to define which features in the Options dialog are supported by the current running game. Use these flags to hide/show the appropriate sliders and buttons in the Options Dialog

- Improve the look of the GMM -

This could include displaying the engine name and the ScummVM logo somewhere on the GMM.

- Config Dialog code -

Resolve the FIXME in engines/dialogs.cpp which pertains to having to use the empty string as the domain name.

Save State Management

- Add Save and Load Dialogs to the GMM -

Allow the user to Save and Load games from the GMM.

- Add Save State Meta-info to Save State Descriptor -

Define a standard for specifying save state meta-info (such as thumbnails, save date, play time, etc.) to the save state descriptor. Thumbnails should be treated differently than the other meta- info, since we do not want to load a large amount of thumbnails into memory each time we call MetaEngine::listSaves(). Thumbnails should perhaps be handled by implementing a new method, which returns a sort of extended SaveStateDescriptor, with more data than what listSaves() would return.

- Enhance the 'Load' Dialog in the Launcher to

Show Save State Thumbnails and Meta-info Data -

Use the previously mentioned extended SaveStateDescriptor to show save state thumbnails and other meta-info in the 'Load' dialog in the Launcher.

- Deleting Save Games -

Currently only engines which do not keep an index file for their save games support deleting save games from the Launcher. Add support for deleting save games for engines which do keep index files. This will include implementing a MetaEngine::removeSaveState() method for each of these engines.

Engines which use index files for their save games are:

CINE , SKY , SWORD1

I'm not sure if the following engines use an index file or not:

CRUISE, DRASCULA, IGOR, M4, MADE

- --list-saves Support -

If possible add –list-saves support to those engines which do not support it.

Engines which do not support –list-saves are:

CRUISE, DRASCULA, GOB, IGOR, M4, MADE , TINSEL

- --save-slot/-x Support -

If possible add –save-slot/-x support to those engines which do not support it.

Engines which to not support –save-slot/-x are:

AGOS, CRUISE, DRASCULA, GOB, IGOR, M4, MADE , TINSEL

NOTE: It is highly unlikely that AGOS and GOB will support –save-slot/-x, since the load/save system is script based.

Thanks for reading!

Nearing the end

Since last post I have added RTL support for Tinsel. I'm currently working on getting meta-info for savestates such as thumbnails, save date, etc. to display in the launcher's 'Load' dialog. I'm also working on adding support for deleting savestates from the launcher. Those two things I would really like to get done.

I would also like to implement the idea that Sev had, which was to add some engine flags for determining which engines support loading from the launcher. That way users would not be confused when there's a load button, but some of the games won't load without any explanation. These could possibly be used for RTL as well, so that engines which have a problem won't give the user the option to RTL from the GMM.

I've looked into the crash that would happen in Kyra after RTL. There are some static structures that are causing the problem. I was able to get around it, but the code wasn't pretty, and since I have many other priorities to attend to, I'll have to leave it up to those people working on Kyra to find a more elegant solution for now. But at least I found the source of the problem.

As for the RTL crash related to Cine, I quickly looked at it, but was unable to pinpoint a specific cause. Hopefully the engine maintainers will look into this.

Here are the goals I have set for the next week and a half:

Savestate meta-info in the launcher
Deleting savestates in the launcher
Engine flags (for being able to load from launcher and RTL)
GMM Menubar with info (Scumm version, Engine name, possibly ScummVM logo)
Saving/Loading from the GMM (maybe)
Recheck memory leaks
Documentation

Progress with Savestate Mgmt

Hey everyone. As I mentioned, the past week I've been working on implementing some savestate management features, namely loading games directly from savestates '-x', and listing savestates '--list-saves'. Some engines already supported these features, and I have added support for some of the engines that didn't. I've added '-x' support for LURE and PARALLACTION, and I'm still working on AGOS and GOB. I've added '--list-saves' support for quite a few engines as well.

Engines currently supporting -x:

AGI, CINE, KYRA, LURE, PARA, QUEEN, SAGA, SCUMM, SKY, SWORD1, SWORD2, TOUCHE

Engines currently supporting --list-saves:

AGI, AGOS, KYRA, LURE, PARA, QUEEN, SAGA, SCUMM, SKY, SWORD1, SWORD2, TOUCHE

I also managed to work in a 'Load' button into the launcher, which opens a savestate chooser. So now all of the engines supporting both -x and --list-saves can load savestates directly from the launcher, which is pretty cool I think.

So now I'm going to try and finish working with AGOS, GOB, and I'll also try to incorporate the newly added TINSEL engine. Also, I'm going to see about adding support for Autosaving in the engines where I can. Oh yeah, I might also add support for deleting savesates from the launcher.

The past week, after gaining much understanding of how sound is implemented in the engines, I have made some progress getting the settings in the Options dialog to function correctly as well as implemented properly for most engines. Learning how the sound should be implemented and finding the common ground between all of the engines was a challenging part of the Global Main Menu portion of my task.

In the following engines, modifying the sound settings through the GMM works very well, meaning that the volume for music, sfx, and speech can all be adjusted separately:

AGOS, GOB, LURE, QUEEN, SAGA, SKY, SCUMM, SWORD1, SWORD2, TOUCHE


Engines for which sound settings are modifiable, but not are not yet 100%:

KYRA - Volume is adjustable, however the music and sfx can not be separately adjusted. (At least in LoK, which is the only game I have to test with)

PARALLACTION - Sound effects are adjustable, however I have not yet been able to test music because music has not ever played for me in the game I have which uses this engine (Nippon Safes, full and demo versions).


Engines which I have not been able to properly implement the configuration of the sound settings through the GMM, due to time constraints and/or issues specific to how sound is currently handled in the engine:

AGI, CINE

It took some time to understand how the sound was being implemented in all of the engines, and sometimes I think I may have spent a little too much time on the details of certain engines trying to get the sound settings to work right. I'm certain that with a little attention from the engine maintainers, all of the engines will work seamlessly with the settings in the Options dialog.

Testing the sound settings for all of these engines was also a challenge. Due to many different variables which depend on the user such as the operating system, sound card/MIDI device being used, and game versions (demo, cd version, floppy version), it is hard for me to test that these sound settings are working correctly in *all* situations.

I did want to look into getting the engines to be able to let the GMM know what sound settings are supported by the game being played (such as speech, subtitle speed, etc.) so that only the relevant controls are displayed in the Options dialog. Hopefully I will have some time to come back and address this.

This week I begin my work on the Savestate Management portion of my project. So I am looking forward to becoming familiar with yet another aspect of ScummVM!

Well, it looks like I ended up doing the opposite of what I had planned.

Most of my progress has actually been made in improving the implementation of the Global Main Menu. I have gotten rid of the Quit and RTL flags that were being used by the engines. This is better because previously the Quit flag had to be made public, and the GMM code needed to access these flags, which was not good.

Now the DefaultEventManager keeps track of whether to Quit or RTL, and the GMM can simply send QUIT and RTL events to the Event Manager. This elminates the need for engines to track EVENT_QUIT in most cases, and now we can use the Quit flag for ScummVM without the need for an engine to be running.

I have implemented an artificialEventQueue and a pushEvent() method which allows you to push "fake" events into the event queue. I am using it to create QUIT, RTL, and MAINMENU events. The artificialEventQueue can be useful for other tasks as well, Stephen Kennedy is using this feature for his Virtual Keyboard.

I did make some progress with configuring the sound settings from the Options dialog. It is now possible to adjust the volume for all of the engines through the Global Main Menu. However the implementation needs some improvement. In particular, I need to look into how the kPlainSoundType is being used by the engines.

The Mid-Term evaluation period is over now, and I feel like I have made some good progress so far. I also think that now is a good time for me to look at my project schedule and re-evaluate how to spend my time.

I would at least like to get configuring the sound settings through the GMM properly implemented for all of the engines. Hopefully that will all be done this week. Then I will move on to the savestate management features.

It's been about a week and a half since my last post, I had meant to make an update sooner (sorry, time has just been flying by). I have implemented the Global Main Menu, and it is coming up in all of the engines. We are able to 'Quit' and 'Return to Launcher' from the GMM, and there are 'About' and 'Options' dialogs as well. Also, the sound settings for most engines are configurable through the GMM's Options dialog. I am still working on getting the sound settings to work for the following engines: AGI, LURE, QUEEN, and SCUMM.

So beware, I may be in need of your assistance if you have any knowledge regarding sound implementation for these engines!

For now I am going to focus on getting the Options dialog settings and overall functionality of the GMM working for all of the engines. After this I plan on making some improvements to the implementation of the GMM, as suggested by Fingolfin.

Ok, I made a little bit more progress with the return to launcher feature. SAGA, SWORD1, and SWORD2 can now be added to the list of working engines.

As for PARALLACTION, with some significant effort we have learned the cause of the aforementioned memory leaks, however I will be coming back to that problem as well as the KYRA engine later, probably in a couple of weeks.

This week I have turned my focus to the Global Main Menu dialog. So far I've been studying the main menu dialog code in the SCUMM engine, as well as the code in gui/dialog.cpp, newgui.cpp, etc. to get a feel for how the dialog should be implemented.

I will also be merging what I have worked on so far with the Return to Launcher feature to the trunk, so I'm excited about that!