SoC2013 thunderstruck MP Campaign Support

From The Battle for Wesnoth Wiki
Revision as of 16:05, 10 May 2013 by Thunderstruck (talk | contribs) (Goals, engine and wml syntax changes)

This page is related to Summer of Code 2013
See the list of Summer of Code 2013 Ideas

This is a Summer of Code 2013 student page


Andrius Silinskas (thunderstruck) - Multiplayer campaign improvements

The current multiplayer campaign support from both UMC developers/maintainers and players perspective is far behind comparing to singleplayer support. I propose a project to improve overall quality of multiplayer games by enabling singleplayer campaigns to be used as multiplayer campaigns and fixing most of the well known issues. The old multiplayer campaigns and scenarios should remain supported.



The Project


The singleplayer campaign support surpasses multiplayer support because of the complexity involved in multiplayer codepath. As a result of this, not all important features are yet supported in multiplayer games and there are some bugs which greatly affect the quality of the game. To address these issues, multiplayer campaigns should make use of CampaignWML and ScenarioWML. This use of new syntax would allow to use singleplayer campaigns and scenarios as multiplayer ones and vice versa. It would also make a ground to implement features missing in multiplayer e.g. difficulties and extra defines.

Furthermore, the relevant GUI elements should be improved and/or new ones introduced to cope with the game engine changes and allow better multiplayer experience from the user's perspective. The save and restore issues should be fixed as well and be of high priority since it is a problem for most of the multiplayer community.

This approach would increase an overall quality of playing multiplayer games and developing or maintaining them. The LoW campaign would be ported to the new syntax during the project.

WML syntax changes

Multiplayer campaign file



# details omitted..


    # Indicates how campaign is allowed to play. Possible values: 'sp', 'mp', 'hybrid'. 
    # Optional. 'sp' will be used as a default value.
    # details omitted..

    # details omitted..

Scenario file


    # details omitted..


    # details omitted..
        # details omitted..
        # Specifies whether players should be allowed to choose factions.
        # Optional. 'yes' will be used as a default value. 
        # Specifies whether players should be allowed to modify an order of turns for the sides.
        # Optional. 'no' will be used as a default value.
        # These should be no longer necessary:
        # save_id=1
        # persistent=yes

Game Engine Improvements


TODO: clarify eras role in WML parsing

New syntax support
Currently, engine recognizes singleplayer games by [campaign] and [scenario] tags and multiplayer games by 'MULTIPLAYER' define and [multiplayer] tag respectively. It should be modified so that it would load multiplayer games with only [campaign] and [scenario] tags and recognize what type of game it is by 'campaign_type' attribute. The [multiplayer] tag would stop be to used. However 'MULTIPLAYER' define would still be used, but would play a less important role i.e. it would only be used to make adjustments between singleplayer and multiplayer in hybrid campaigns. Additionally, stand-alone multiplayer scenarios would remain the same, except that they would use [scenario] tag.
Old syntax support
After multiplayer game configs start to use CampaignWML and ScenarioWML, the old multiplayer games would stop to be supported. To cope with this issue and to not introduce a new codepath just to support the old configs, the utility responsible for upgrading old multiplayer games will have to be implemented. It should be called at the loading time of game configs and upgrade all configs identified as an old multiplayer WML. Additionally, the upgrader utility should also wrap eras around with unique defines to improve multiplayer loading time. The upgraded files should be stored in user's data directory and would be also cached for performance reasons.
Upgrader's functionality:
  • [multiplayer] -> [scenario]
  • #ifdef MULTIPLAYER .. #endif -> [campaign]..[/campaign] #ifdef CAMPAIGN_SYMBOL .. #endif (only in '_main.cfg')
    • campaign_type="mp"
    • fields such as 'id' and 'name' would be set up by path to campaign
    • all other non-mandatory fields would be left empty
  • [era]..[/era] -> #ifdef ERA_DEFINE [era]..[/era] #endif
Further new syntax support
To enable multiplayer games to use 'difficulties' and 'extra_defines' attributes from CampaignWML, some parts responsible for singleplayer and multiplayer game set up would have to be merged. Additionally, part of multiplayer set-up logic could be moved to game_controller class. This would allow re-parsing of game config file and also setting up binary paths when creating a multiplayer game.
Configs loading
The game configs for all multiplayer games are currently loaded when "Multiplayer" option is chosen from the main menu. The proposed solution would allow to avoid that, because multiplayer campaigns would have their own campaign define and would be loaded with appropriate difficulty only once game is created. The stand-alone multiplayer games would still be fully parsed with every other multiplayer, but that would not drastically affect loading times, since scenarios contain far less data than campaigns. However, since game loading speed is still an important aspect, some adjustments would might have to be made. When creating a game, instead of loading all WML again, we would have to load only a particular campaign we are interested. This would be done by keeping track of path to '_main.cfg' for every add-on and using that path to load everything under that directory. Additionally, if it would appear that big campaigns would cause time-outs while they are parsed, the thread responsible for answering ping requests from the server could be created in order to avoid that.
Saving and restoring
Wesnoth's multiplayer users experience several issues with save/restore games. Most of those issues are not immediately visible and causes small, but important and undesirable gameplay changes (e.g. wrong carry-over or xp calculations). To address those issues, multiplayer game saves storing needs to be carefully reviewed and improved. Furthermore, the stricter check for OOS could be made to make it easier to notice save/restore issues.
Players management
The game engine is currently able to provide only a basic players management and only during the connection phase of a multiplayer game. That means users don't have flexibility to change players between multiplayer campaign scenarios unless they reload the game. In order to improve the players management, the connection phase of the multiplayer game will have to be modified. It would have to lock some options to prevent changes if they haven't been allowed by campaign's developer (custom sides and turns). And most importantly, play campaign loop will have to be modified so that it is possible to go from the end of the scenario to the connect window. In addition, non-host players should also see similar connect window, instead of the current wait window, but only be able to modify their side settings. This would allow better user experience and would simplify the current multiplayer screens logic.
Multiplayer screens logic
before (taken from the multiplayer.cpp):
lobby <-> create <-> connect <-> (game)
lobby <------------> wait    <-> (game)


 lobby <-> create <-> connect_host   <-> (game)
 lobby <------------> connect_player <-> (game)


Additional players management
The game engine could be improved to automatically suggest appropriate sides for the players. It would benefit campaign players, because if the same side exists over multiple scenarios, the player who used to play for that side should be placed in relevant slot. However, players would still be able to swap sides. Furthermore, the host could be able to kick and invite players during the connection phase.
Default values for 'allow_player' attribute should be added to make SideWML less redundant. Already done.

GUI improvements


Create game window
The current window which lets user to create a new multiplayer game mix the all multiplayer campaigns and scenarios into one list. What is more, it won't display campaign's name in that list, but the first scenario of the campaign instead (or more scenarios in some cases). It could be fixed by displaying campaign as a single list item. For the cases when there are multiple starting points (scenarios with 'entry_points' has more than one attribute), all the scenarios should be displayed in the additional dialog if campaign is chose to be played. In addition, there should be two separate lists for campaigns and scenarios and the "Load game" option should be moved from the maps list and be represented as a button. Furthermore, additional option for difficulties should be added along other game options as a drop-down box.
Connect window
The current connect window would need to be modified so that it would be possible to disable/enable options for a non-host player. In this way, the window could be used not for only host player. After those modifications, wait window would no longer be necessary.


Connect window
Additionally, connect window could include buttons/drop-down boxes for the host to invite/kick players.

Additional Improvements

Some other things not mentioned in the project could also be implemented to improve multiplayer campaigns support. They are of lower priorities than tasks mentioned above and would be done at the very end if there is time left or possibly after GSoC.

And also there are some bugs who would be worth looking at.


May 3 - May 27 (pre-GSoC)
  • Work on things related to the project, but on those who could benefit users immediately even if the project is not going to be done at all.
  • Do a further research on project's implementation and make notes on that.
  • Exam period at the University.
  • Demo to play SP campaigns as MP with no extra WML tweaking (works only partially).
May 27 - June 17 (community bonding period)
  • Resolve any ambiguities and issues (if any) with the project's proposal.
  • Start coding.
June 17 - July 25
  • Game engine: new and old syntax support.
  • GUI: create game window.
July 25 - August 2 (midterm evaluation)
  • Extensive testing of implemented things.
  • Port LoW to the new syntax. This is going to happen gradually, along with game engine improvements, but it should be finally ported and polished at this time.
August 2 - August 15
  • Game engine: save/restore issues, players management.
  • GUI: connect window.
August 15 - September 16
  • Extensive testing of implemented things.
  • Code clean-up and polish.
  • Implementing 'not-so-important' tasks and/or tasks from Additional Improvements section.
September 16 - September 27 (final evaluation)
  • Fix any left blocking bugs.
  • Write documentation.
  • Update relevant wiki pages.


1 Refactor game controller


Refactor parts of game_controller.*pp to unify the set up of singleplayer and multiplayer games.
2 Refactor multiplayer


Refactor and move parts of multiplayer set-up logic in multiplayer.*pp to the game_controller.*pp.
3 Multiplayer WML 1


Enable singleplayer campaigns to be played in multiplayer.
4 Multiplayer WML 2


Remove [multiplayer] tag references in the code and adjust it to work with [scenario].
5 Loading game configs


Improve game configs loading time by introducing a loading mechanism which would only load configs under specific sub-directory (path to campaign's '_main.cfg').
6 Multiplayer WML upgrade 1


Implement a utility class to upgrade old multiplayer WML configs to the new syntax.
7 Multiplayer WML upgrade 2


Use upgrader class to upgrade all relevant configs at a loading time.
8 Multiplayer WML upgrade 3


Write a script which uses upgrader to permanently upgrade stuff in 'data/multiplayer/'.
9 Create window 1


Add a new list for games to play and move campaigns to it, leaving scenarios in the previous one.
10 GUI2 drop-down box


Implement a drop-down box for GUI2 in order to use it in create window.
11 Create window 2


Remove "Load game" option from the scenarios list and place it in the same window as a button. Add drop-down box or dialog for choosing difficulties. Connect GUI changes with relevant code.
- Milestone 1


Everything above to be done by July 10. n/a
12 Save and restore 1


Improve multiplayer save games storing in order to fix current issues.
13 Save and restore 2


Implement stricter checks for OOS and fix any new observed issues.
- Milestone 2


Everything above to be done by July 25. n/a
14 Multiplayer screens 1


Modify the multiplayer's screen logic to display multiplayer connect window between multiplayer scenarios. Tweak the connect window to correctly respond to the new changes.
15 Multiplayer screens 2


Enable engine to display multiplayer connect window instead of wait for non-host players.
16 Multiplayer screens 3


Tweak engine to disable/lock relevant connect window options for host and non-host players.
17 Multiplayer screens 4


Implement a simple "I'm ready" system for connect windows. It would decide when to enable/disable "I'm ready" buttons and when to start a scenario.
- Milestone 3


Everything above to be done by August 10. n/a

Future Aspects

Since a whole dedicated summer for multiplayer improvements sounds like a lot, it definitely won't fix all things need to be fixed and won't implement all desirable features. So I think it is worth to note some thoughts on the possible significant (more or less) changes of multiplayer in Wesnoth.

  • Allow 2 or more players to play the same side by splitting units among them. Suggested here.
  • Enable communal choices. Suggested in the same post as above.


1) Basics

1.1) Write a small introduction to yourself.
Hello, my name is Andrius Silinskas and I am an enthusiastic programmer. I would describe myself as a keen and curious person. I enjoy working in many areas of Computer Science but I have not yet found the one which interests me the most. My current goal is to find it and be great at it.

1.2) State your preferred email address.
silinskas.andrius [at] gmail [dot] com

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?
I like to solve problems. Summer of code seems a perfect opportunity for this, because then I would be able to dedicate my whole time for it and meanwhile I could also do something useful to others.

1.5) What are you studying, subject, level and school?
I have just finished my 2nd year at Heriot-Watt University in the United Kingdom. I am studying Computer Science there.

1.6) What country are you from, at what time are you most likely to be able to join IRC?
I am from Lithuania, but I live in the UK now. I lurk on IRC all day, so that would be 7 - 23 in UTC.

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.
I don't have any other commitments, but I plan to go for a week or two to Lithuania. However, I would still be able to dedicate the required amount of time while being there.

2) Experience

2.1) What programs/software have you worked on before?
Most of the programming I did was for university's assignments or my own small projects. Some of them:

  • Whilst learning Python I developed a countdown timer with numerous features using Gtk+.
  • For the Coursera's online course I wrote a lexer and parser for "COOL" programming language using Java.
  • As an exercise I developed an audio recording/playing application using a low level API in C++.
  • For the university's assignment I wrote a simple spell checker program with my own implemented Hash Table data structure in Java.

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)
I was developing software in a team for a few assignments at university. Although they didn't involve much work, I gained a good idea about developing a software in a team.

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?
No, it is my first time.

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.
No, I am not.

2.5) Gaming experience - Are you a gamer?
I consider myself a casual gamer.

2.5.1) What type of gamer are you?
Usually, when I play games I tend to explore as much as possible and find a most efficient way to complete a certain level, mission or some task of the game. I guess that means that I am an exploring type of gamer.

2.5.2) What type of games?
I mostly prefer games which are rather simple in their rules, but allow great possibilities and complexity later on. As for now, World of Goo and Wesnoth (at least in principle) are the games which are like that. I also really enjoy playing a bord game GO, because of the same thing.

2.5.3) What type of opponents do you prefer?
I prefer opponents whose behaviour is hard to predict, who sometimes do really good and who sometimes do mistakes. In other words, I like my opponents to be as similar to humans as possible.

2.5.4) Are you more interested in story or gameplay? As they are both vital to a good game, it is hard to tell which interests me more. But I would probably say story, because story alone is something (e.g. a book), while gameplay alone would get boring soon.

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer. We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively.
Yes, I have. I know the game for about 2 years, but I haven't played it regularly all the time. Although I had peaks where I played Wesnoth quite a lot. I would lean towards single player, because it has a better story and seems to be more finished.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our repository (during the evaluation period or earlier) please state so.
#3777 (not reviewed yet)
#3862 (closed by my request, but it still shows my involvement in Wesnoth)

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
My English grammar is still not perfect, but I don't have problems whatsoever while communicating in English.

3.2) What spoken languages are you fluent in?
English and Lithuanian.

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
I think I am. I have been playing MMO games in the past and I was successful at interacting with other players. I've also been a game master for a MMORPG where I had to interact with the players and they were not always nice.

3.4) Do you give constructive advice?
At least most of the time, yes. I always try to be positive when giving any sort of advice.

3.5) Do you receive advice well?
I think I do. I tend to carefully listen to advice I get.

3.6) Are you good at sorting useful criticisms from useless ones?
That is hard to tell, but I always give a thought about criticism I receive and I think I cope well with it.

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want
I would say I am quite autonomous but I don't mind discussing with others when it is needed either. I tend to try to do things on my own as much as possible and then discuss what is not clear to me.

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?
I've selected 'Game Engine: Improve Multiplayer Campaign Support' project.

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?
As I have already stated, I like solving problems. It seems that this project is rather an interesting problem due to lots of different aspects involved. And I would also like to make multiplayer better, since as I have already said that singleplayer surpasses multiplayer.

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".
See Timeline section.

4.5) Include as much technical detail about your implementation as you can
See The Project section.

4.6) What do you expect to gain from this project?
Apart from gaining more experience and improving my technical skills, I expect to get involved in Open Source community and have a great time.

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?
I probably risk to sound like a guy who is promising in order to be accepted, but I already feel like staying with Wesnoth from what I have already experienced.

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?
Git (used for all commits)
I am new to Git and still learning, but I know my way around pretty well.

C++ (language used for all the normal source code)
Since C++ is such a big language, I can't say that I already know it very well, but I feel confident using it for this project.

STL, Boost, Sdl (C++ libraries used by Wesnoth)
I have some experience with Boost and STL, but not Sdl.

Python (optional, mainly used for tools)
I haven't programmed with it recently, but I know it quite well.

build environments (eg cmake/scons)
I mostly use scons (for Wesnoth), but I have used cmake sometimes as well.

WML (the wesnoth specific scenario language)
I have learnt some of it while preparing my proposal, creating a few small scenarios for fun and while fixing some bugs. I think, I have a grasp of it.

Lua (used in combination with WML to create scenarios)
I know basics.

5.2) Which tools do you normally use for development? Why do you use them?
At the moment, I am in transition to move from GUI development tools to Vim + terminal combination. Although I am still not as efficient as I would want to be, it works pretty well for me. My computer runs Linux.

5.3) What programming languages are you fluent in?
Java - mostly used in university.
C/C++ and Python - learned on my own.
PHP, JavaScript, Pascal - I know the basics and a bit more.

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!
No problem at all.