Monday, August 6, 2012

Little summary

Now, after two months of work, it is time to show progress and describe the architecture of events recorder. This is a class diagramm, which can give some understanding of how does events recorder relates with other classes of scummvm.




Lets describe it particulary by means of subsistems, which it records. 
User Input: to record events from mouse and keyboard, eventRecorder implements DefaultEventMapper. During the initialisation, it registers itself as a mapper. So, every event occurring in system, is catched with EventRecorder's pollEvent function. This function checks state of the recorder and calls PlaybackFile's writeEvent() function to write this event in temporary memory buffer. If the buffer is full, playback file dumps it to file and takes screenshot, calculates checksumm and dumps it to the file too.
To playback events, recorder does everything in reverse order. It implements EventSource and reguster in EventDispatcher as the source of events. Every time when game engine calls pollEvent function, EventDispatcher calls pollEvent function of EventRecorder. This function checks if the EventRecorder in playback mode and calls getNextEvent function of PlaybackFile class. This function read event from events memory buffer, and if buffer is empty, it reads next events chunk from the file. Also it reads screenshot from the file and compare it with current screen image. If there are any differences, it shows warning message. 
System time:   To correct playback process we need to write and to play system time when a game engines queried for it. To do this, we inserted processMillis call to OSystem_SDL::getMillis function. This function in recording mode writes system time to the file and in playback mode reads time from the file and give it to  a game. The problem is that this meathod registers time queries not only from a game engine, but from GUI and TimerManager. It ruins playback, cause gui and timer manager not synchronised with engine logic. To solve this problem, two improvements to the code were made. The first one -  parameter which disallow to register this query was added to getMillis function. By default, this parameter sets to false. It sets to true in calls from GUI. The second one - call timers update routine from EventRecorder/ became possible.
Audio: As audio fragments are played in other thread and controlled only with SDL subsystem, there could be some problems with  audio flow synchronization and user events. For instance, in Kyrandia, when you click anywhere while somebody's talking, sound interrupts and mouse event doesn't pass to the game. In the same situation, durring playback, sound may be played a little bit faster. And mouse's event will be passed to the game and it's possible that the whole gameplay will chrash. To avoid this unpleasant situation, new class had been added: NullSdlMixerManager. It updates with EventsRecorder and "output" sound to nowhere. And we may always know that during playback sound ends the same time it ends during recording.
Random numbers: as an engine use pseudo random sequences, and we can prognose the whole sequence by initial value of random numbers generator, it's very easy to record and playback random events. It's necessary only to hold this initial value and restore it. Every time RandomSource is created, it calls getRandomSeed() function of EventRecorder. If the recorder not in recording or playback mode, this function works just as bypass.In playback mode it changes initial value to recorded one.

Friday, July 27, 2012

What has been done on this week

Hi. This week I've add new features to events recorder. Now it can replay game without display it on screen:  it initialize memory buffer instead of initializing of SDL context. Next feature: user can switch recording mode to normal game play. I. e.while user is recording his gameplay he may interrupt it and continue playig in normal mode. You may see on this diagram how it works:

Friday, July 20, 2012

Finished save files embedding

On this week I've finished savefiles embedding. Following the fuzzie's idea, I created class which inherits DefaultSaveFileManager and implements listFiles and openForLoading functions. During the recording or playback it calls functions of events recorder. This functions read hold or read save files from recording file.

Also, I've begin work on onsreen recording dialog. This dialog will show during the recording and playback and allow to control the recording process. You may see very first version of this dialog on following video:
http://www.youtube.com/watch?v=EylL9saw8lQ 

Friday, July 13, 2012

Refactoring week


So, I'm still working on integration of save files into recording file. On last week I did alot of things to this. After code studying, I saw that every engine supporting states loading, have some kind of fucntion which generates file name by slot's number. Some engines have this function as is a class static method, others like public method, few engines have this function inlined to code of saves-related functions. In other words, we have same behavior and different interface. So after discussion with mentor we decided to unificete interface of save files name generation and make all engines compatible with this interface. Then we produced some requirements to name generation function:

1) It should be accessible without class instancing. Because MetaEngine use it for removeSaveState and querySaveMetaInfo functions.
2) It should be accessible inside of class methods (obviously)
3) It should be accessible outside of class using the pointer of abstract class Engine. It to make possible to use it from eventRecorder
4) Logic of name generation should be in one place. Because it's possible to get error relate to duplicated code. For instance, in current version of queen engine, function QueenEngine::makeGameStateName uses constant string "queen" and function QueenMetaEngine::removeSaveState uses variable target for name generation. This may cause a problems.
5) Preferably to have a fucntion which check number of saving's slot is special (for ecample used for autosave or recording file) and generate name without depending to engine implementation

As most engines generate file name by formula fileName = preffix + "." + pattern, where preffix is a name of engine and pattern is function from slot number (for example "%03d"). Firstly I thought that it would be a nice idea to make a universal method in Engine class. Parameters of this function would be preffix (usualy target name) and pattern to generate extension of save file. This method could look like Engine::getSaveName(prefix, pattern, slot). But some engine need different algorithm of names generation and each time we call this method we should pass to many params to it, which is not very comfortable and can be cause of errors.

Then I decided that it should be good to make and AbstractNameGenerator class with abstract generateSaveName method, and inherited it for each engine. You can see it on diagram:

I would be consistent to all requirements, but create class without state which contains only one method is definitely overengineerng.
So, we decided to make static method and wrap it by virtual function in each engine. And in every virtual function call checking for special slot.

And then fuzzie suggested to  wrap the SaveFileManager's openForLoading function, for the event recorder. And this idea looks very attractive, cause at first, it can be realized without changing of existing codem and at second it corresponds to the logic of other eventrecorder's systems. So at the moment I'm working on implementation this idea

Friday, July 6, 2012

Savefiles embedding



It's needed to make a recording self-sufficient and independent from save files. At the moment, user should  make following sequence of actions to playback loaded game:
1) choose game
2) select playback record
3) press "Playback" button
4) in pop up dialog box select is it need to load from savegame.
5) if loading from savegame choosed, show load game dialog

After I implement this feature, 4th and 5th steps will be removed. Also, will be sufficient only recording file to playback the gameplay. Will not be necessary to share save file.

At first glance, it's easy to implement this feature: just current save file during the recording and give it to
engine during the playback. But it's not so easy to do, using the current engine API.

First of all, every function related to saving and loading works only with slot numbers and save files name generation is different for each engine, so our function can't get filename of current save. I've tried to solve this by adding the virtual funtion getSaveFileName to engine class. Anyway, this function is in every engine in different forms: somewhere it part of loading function, somewhere it's separate function, but it exists in any engine. So, i think it's a good idea to make an unificated interface for it.


Next issue is to load savefile from recording. As I said above,  we can load savefiles only by their slot number. There was to  ways to solve it: write procedure which loads game state from given stream or create some virtual slot used only for recordings. First way requires to large code rewriting, so we chosen second.
I've almost implemented it, and now I'm doing testing and fixing a bugs. Hope to show a demo soon.


Friday, June 29, 2012

Nothing special

This week I've just did little code refactoring and moved all playback file related issues to separate class. Also, following my mentor's advice, I implemented cache for recording dialog. Now It reads every file header before adds it to list, store file's header to array and every time when user update selected record, it doesn't need to reopen the file.
What I want to implement now it's to keep the game save in playback file, i.e. if we load file before recording, it shouldn't ask what record you want to load. It should load it automatically. I'm not sure is it possible, but it may be great feature.

Tuesday, June 26, 2012

GUI feautures of event recorder

Last week I've added opportunity to view playback file screenshots directly from GUI. How it works you may see on the following video:
http://www.youtube.com/watch?v=trqPXKsAaCs



Also I've added dialog window to edit info about author, visible name and description of playback file.
http://www.youtube.com/watch?v=trqPXKsAaCs

During the work by GUI we've desided to move all operation with file to separate class. It should provide high flexibility and make possible to simple access to playback file. So I've added class PlaybackFile which works with file and provide higher level of abstraction.

Saturday, June 16, 2012

Recorder GUI

It's time to make gameplay recording more user friendly, cause rewrite config time every time when we want to record or to playback isn't very fun. So we've begun work on GUI for recording and replay. First of all, I once again changed initialization routine of recorder, totally removed it from engines and call it at same time when the user choose game, so it became even better and transparent.
Then I've change naming of records. Now name for recordfile generates as <game>.rxx, where xx is number of recordfile. For instance: kyra1-cd.r11
Use cases for choosing records are very simmilar to loading from savefiles. So recorder dialog going to be very simmilar to load savefiles dialog:

At the moment, it have minimal functionality: it can record gameplay to new file, playback choosen record and delete existing records. Next week I want to add few more interesting features :)

Monday, June 11, 2012

Almost works


This week I made easy integration of recorder to engine. Now, engines inherited of AdvancedMetaEngine initialize registrator automaticaly. Few other, inherited from MetaEngine (SKY, SCUMM, SWORD1, SWORD2, QUEEN) can be initialized by adding only two strings: 

#include "common/eventrecorder.h" g_eventRec.init(gameName());


I've tried registrator on number of games and at first view it works well. So, seems like it almost works and will ready to testing soon.

Tuesday, June 5, 2012

Making things better

On this week, I fixed architecture mistakes in event registrator. When I've enabled registering of all time events (when somebody whant to know about system ticks) there strange mistakes occurred and it didn't work at all.  So, I've enabled registering time events only in some places of engine. But even in comments to my gsoc proposal, LordHoto noticed that need something to do with it, because when different parts of VM see different time, this will cause problems. In addition, direct replacement of g_system->getMillis() by the g_eventRec.getMillis() is bad, untransparent, unflexible, etc. At last, after one of commits, my mentor _sev proposed me to liquidate this dirty hack, by getting rid of all g_eventRec calls and doing registration of all g_system->getMillis() calls.
First problem we have found - events might be recorded before full initialization of registrator. It was fixed by simple  flag adding which shows that the registrator completely initialized.
After I solved this problem, I tried to find another bugs during at about two days. Something went wrong, but I couldn't find what exactly. _sev very helped me when suggested to use backtrace macros which will show who and when call getMillis fucntion. I've begun to write this data to log and analyze it. This helped me to find next two problems:
DefaultEventManager::pollEvent called more often durring the playback. And also it calls if user doing any action (moves mouse, presses keyboard keys). I solve this programm by adding a stop and start registrating feature  to registrator class. Now it just skips time messages from pollEvent function.
Last problem was hard to find, but very easy to solve. To describe a problem I should tell how we've developed wrapper for audio registering.
Original audio subsystem can be represented by this sequence diagramm:


I. e, SDL audio subsystem give mixer manager to know about it's readiness to play next chunk of sound and give buffer which must be filled by sound data. Manager give this event to platform-independent mixer which must to fill this buffer. Mixer check is there any free chanal and give this buffer to it. Chanal fill the buffer by sound data and ask the current time from system. System ask for time from events registrator.

This scheme worked perfectly, but had a little problem: it was very hard to synchronize sound with logic. Wasn't possible to determine how often will be calback called and what will be buffer size. _sev proposed to get rid of the dependence from  SDLInternals and replace SdlMixerManager to own wrapper. Obviously, there was needed to use some external events source which  will set how frequently mixer's callback will called. Also, this source must have possibility of sinchronization with registrator. We decided to use processMillis for this purposes.   Regarding to this idea, sequence acquired the following form:

Very easy to see that this sequence resulted in an infinite loop and stack overflow. We decied to make a bypass to disable events recording while mixer's callback executing 




Now, in case of necessary, registrator taken out from sequence and system time became the result of function. It saved from stack overflow and worked quite well. When I began to register all calls of getMillis, problem has arisen where I did not expect it. There is function Chanal::getElapsedTime, which returns the time elapsed from begining of sound playing. It getting first time period in Chanal::mix function (during it bypass works and time is real from system). Another time it gets from events recorder. So difference between them is undefined and different for each replay. After problem was found it was very easy to fix it and make result of getElapsedTime function positive and predictable.




Friday, May 25, 2012

What is the use of a book without pictures?

Since the last post I've worked on the screenshots feature. There was few requirements:
1) During the recording process screenshots should record into the same file as other evetns
2) It should be possible to setup period of screenshot recording
3) During the playback process screenshots should read from playback file and compare with current game screen. Best of all it would do using MD5 hash, so it must be recorded with image data.

Wednesday, May 16, 2012

New recording format

Last 2 weeks I've worked on developing of format for holding recorded gameplay data. Why this needed and how does it work you may read under the cut.

Tuesday, May 1, 2012

My first success

Hi. Last week was pretty fruitful. I got to work EventRecorder on KYRA engine. Let's describe it in more details.

Tuesday, April 24, 2012

It has begun



Hi to all. It's not my first record in this blog, but I had no chance to introduce myself in previous posts. In this post I'm going to fix this unfortunate mistake.

My name's Danil. I'm ukrainian student and am studying computer science in university.  You might have guessed on the basis of my project's choice, but just in case I will specify that I really love computer games.

Now about news. Of course, main news is MY GSOC PROPOSAL HAS BEEN ACCEPTED!!! What does it mean in practical plane? In practical plane it mean that during the next 4 month you'll read in this blog how I'm writing "Testing framework for ScummVM". I promise that will do my best to make this blog not very boring to read.

What can I say else? Fortunatelly, in this year Ukraine choosed for EURO2012 soccer champ. Our goverment pay a big attention to this event, therefore my university's exams begins and ends early, so I'm almost pass them and ready to work right now. 

Maybe it's all that I can say in introduction. So see you later in next post after I do some work and be able describe any interesting technical details



Thursday, April 19, 2012

Progress at 19'th of April


  I tried to make something workable in time, but it was much harder than expected. So I'll show what I had done for this moment. Sources you can see at this  LINK. There I'll tell how and what I did to realize this idea.

  I've read and criticism of my idea to link events with engine's loop. I've desided that it's realy hard in realization and impossible to make universal for all existing engines. Then I've desided to write every "external" event (with some exceptions), namely mouse's moves and clicks, keyboard's events, calling of delay and getmillis functions.  

  I've quite quickly writtem it, fortunately most of all this was already in existing code. Then I've tested it on SKY engine and everything worked perfect.

  I needed to consolidate success and I've tested gameplay recording on KYRA engine. And there began problems. Events have become different from record very fast and gameplay absolutely different with from recorded. I've begun to find out what's wrong. First of all, I've noticed, then getMillisec and delayMillisec functions called not only by engine. ScummVM (GUI system and something also) call them too. It's giving undefined behavior, cause we don't know what state have scummvm when we began record or replay. So, I've removed global hook of these functions and created method getMillis for EventRecorder class. Engine must call this method if want's to record time event. I've changed all callings of g_system->getMillis to g_eventRec.getMillis. It's become better.

  Then I've noticed dependence of gameplay from audio playback. Following the tested game logic, if user presses mouse button during the speach, speach finishes and mouse event doesn't passes to game. As sound is playing in separate thread - audio playback speed doesn't corresponds to gameplay speed. So I've thought how it's possible to record and playback of audio events and synchronize them with gameplay thread. During the code studying, I've noticed then substitution of arguments of mixCallback function in MixerImpl class affects to audio playback speed. I've inserted my hook code into this function. So audio event's syncronizing with EventRecorder's timer and occurs in same moments of time.

  Unfortunatelly, this didn't solve the problem of incorrect gameplay playback. So, for make debugging easier, I've visualised it. I've inserted debug output to log for every place where event occurs.  Now when I'm recording gameplay, I'm saving log file and comparing it with playback's log file using the diff utility. It allows to easyly detects places where playback events became different from recorded events.

  Using this method I've found that in sound_midi.cpp function g_eventRect.getMillis called by timer handler, which is absolutely independend from engine and is a part of scummvm. It called randomly and make errors during the playback. For this time I've made calling of system getMillis and discrepancy has gone.

  Then I've seen that played back gameplay is absolutely identically to the recorded before the sound begin plays. Since audio playback events begin to diverge. It happens becouse game logic and audio playback executing in different threads. It can be executed random number of gamecode while sound is playing. It makes undefined behavior. I've tryed to syncronize engine thread with audio thread. Now engine wait for finishing of audio playing and only then continues work.

  Now I have problem related to wrong returned time of samples was played by certain chanal. I tryed to solve it in current commit, but think I'll havn't time before choosing of participants. And I had to make this post to show current progress of work.

Tuesday, April 3, 2012

SKY refactoring


In my first post I've wrote about refactoring of SKY engine. Here I want to describe it in more details what did I mean.

Monday, March 26, 2012

Proof Of Concept


Here you can see my vision of EventRecorder I've implemented. I've summoned all my mad msPaint skills and hopeing that it looking as well clear as funny. Let me describe how it works:

recording:
EventsRecorder subscribed as observer to EventManager. Every income message it push into _eventsQueue. Every iteration of main loop(sync), engine calls EventsRecorder's sync method and all events from queue falling down into the file.

playback:
Every iteration of main loop (sync), EventsRecorder clear _eventsQueue and push events from file to events queue. Then push it back into EventManager.

Video of working demo: http://www.youtube.com/watch?v=6AcXYGLH4vE

I've forked scummvm on github and trying to understand how can i work with code (all this repositories, branches and collaborate work is very new for me).  Now there is only clone of scummvm in my repository, but anyway, here is link for it:
https://github.com/jakimushka/scummvm

Friday, March 23, 2012

At the beginning of a long journey


I want to take part in summvm development as a part of the Google Summer of Code Event. Here I’ll tell about work done, about my impressions from this project and about other things related to this.

 It was highly recommended to make bugfix or path of existing code for participation  in the project. But I have some problems with them. After trying about ten bugs from bugtracker, I can’t reproduce any of them. That’s why, I’m going to start working on the idea I want to implement during this project.

So, my aim is to write testing framework, which can record or reproduce user’s actions. There is already implemented module in the project, but it has some problems with synchronization with states of engine. After analyzing the existing sources, I’ve found that previous version of the recorder was based on the idea that input events are in the form of interrupts and they linked to the time. In fact, events are state of input controls during the current iteration of engine. So for the recorders correct work, it’s necessary to store/restore the state of input controls in each iteration.
It looks much easier than previous version cause there is no necessity to make any time calculations. But difficulty lay in the fact that calling of recorder must be implemented in every supported engine and different implementation of main loop in engines also can be a problem. So calls recorder’s interface must be as easy and compact as possible. Ideally, recorder must be encapsulated into Event Manger.

My first step is implementation of Event Recorder class and integration into one of the existing engines (I think it going to be Sky engine, cause it is very easy to find game for testing) and testing until it will work perfectly.
Then I’ll try to integrate it into another engine and analyze what difference it has and what should I change in engines to make integration easy. 

Next I’ll integrate it into all engines and will write guidelines for using it in new engines. 
The main loop of engine was easily found in go() method of SkyEngine class. This method implements all game logic and it calls delay() function which sync engine with FPS and also processes events. 

Actually, I do not really like main loop implementation, and if it would be permitted, I refactor it. 
Firstly, I think that methods 
delay() and doIntro  isn’t routines. They are states of engine! And engine is a classic state machine, which can be in following states: 
STATE_INTRO - playing of intro, which can be interrupted by escape key pressing and going into action state 
STATE_ACTION - working iteration of engine. Makes updates in logic graphicks, analyze input 
STATE_IDLE - state for syncing with FPS 
STATE_PAUSE - ingame pause
Now it works how statemachine but logic “smoothed“ with the code. Function delay() , following its name must pause application work. But it also makes an events processing (btw, events processing loop wants to be extracted from delay method). 

To test my idea, I’m adding public methods saveEngineInputState and restoreEngineInputState into EventRecorder class. They are only writing given state of keyboard and mouse to file depends from recorder state. (if recorder in writing state - restoreEngineInputState doesn’t work. if recorder in playback state, saveEngineInputState doesnt work) . I’m going to store input state after processMessages routine and push stored messages into EventManager before processMessages routine (faking real events). 

Pseudocode: 
g_eventRec.restoreEngineInputState(); 
processMessages(); 
g_eventRec.saveEngineInputState(_keyBoardState, mouseState, mouseClicked); 

After testing, I’ve noticed that this principle works really great in things related to synchronization. But it also has some problems, which must be solved:
only mouse and keyboard events are processing now. And only aim engine routine. For instance, EVENT_QUIT willn’t handle. Keys pressing will not handling properly too. (but that moment I thought it was due to weak engine architecture)
  • aren’t processing mouse movement events
  • there may be some problems with using it in different engines
  • aren’t processing random (easy to fix)
In general, I think, I get awesome progress for few hours of work. I’m looking forward for any suggestions and criticism comments.