SoC Ideas Savegame

Reorganizing the savegame format

Wesnoth basically supports two types of scenarios: Single player campaign (one campaign consists of several scenarios) and multiplayer (one isolated scenario). The savegame information for both share a lot of stuff, but there are also differences, information which is unique to each of them.

Lately, there is another development showing up, which wasn't really considered in the beginning of wesnoth: Multiplayer campaigns. Those kind of work at the moment, but they are a little uncomfortable, because the savegame format does not support them good enough.

Your task will be to develop a uniform savegame format, that allows to store all information needed for any kind of scenario and to write the code supporting this format.

General description

The idea behind this project is that there won't be any significant differences (at least regarding the savegame format) between single player and multiplayer anymore. Rather, multiplayer is seen as an enhancement to single player with the main difference being that multiple player information will have to be stored.

From the coding side of perspective, you might think that you will be able to reuse lots of existing code. In a way this will be true, but there are also some specialties about it:

• At the moment, the code for processing savegames is spread along several files and it is full of workarounds to serve the three main 'consumers': Single player scenarios, multiplayer scenarios and replays. In other words: It is a mess, one of the worst you will be able to find within the wesnoth codebase. Every new coder has to struggle just to find the functionality he is looking for and senior developers desperately try to avoid any changes to it.
• Although you will be able to reuse some of the code, you also will have to think of a new design, that combines the current still separated approaches to the different types of scenarios. It might turn out, that starting your code from scratch is a better idea than rewriting the existing stuff.
• Basically, the challenge of this project won't be writing the code in the first place, but rather figuring out what is the best way to rework it: How do i minimize impact? How can i design the code so that it is easy to understand and maintainable? What information is needed upfront to achieve that?. These are the important questions that you will tackle in close teamwork with your mentor.
• The intent of this project is to adapt the content of savegames, not the format that content is stored in. WML has been proven to be an efficient format and we don't want to change it.

Required knowledge and talent

• A minimal knowledge of C++ is required, a good knowledge of C++ is desired : The main challenge will be to become familiar with the common style of wesnoth coding, since we widely use some advanced C++ features like STL and rely on a couple of libraries. However, the savegame processing code is relatively straightforward and not as complex as many other areas.
• Design capabilities: Because your code will have to integrate into the current wesnoth architecture, you can't just grab the keyboard and start hacking (well, you shouldn't do that anyway but that's another topic for another day ;-). So a very important part of this project will be to provide a good design and put some thought into that. It is also essential, that this won't happen solely inside your head but that you also provide some visible results (see the list of milestones and deliverables below). Static (or maybe even dynamic) UML models would be really cool, but they are not required. Any other technique, be it a diagram or simple text will do as well, as long as it contains the needed information. Depending on your experience and skills, your mentor will closely interact with you throughout this work and give you the support you need.
• Good social interaction with the multiplayer community : As mentioned before, multiplayer campaigns are one of the triggers for this task. There are some multiplayer campaigns and part of your work will be to get in contact with the maintainers and get an understanding of the current problems in order to decide how to support needed features with savegame information.

Milestones and deliverables

Some of the milestones will become obvious after the design phase is finished, but here are some ideas of what needs to be done:

• Being familiar with the code : To get a better understanding, you will have to examine the currently available code, find all the places that deal with savegame information and roughly understand what their specific task is about. This should be documented. You will also have to learn the text representation of savegame information which is done by WML, a markup language that is widely used within wesnoth. Play a little with the different kind of scenarios and see what savegames get out of that and what the code is doing with them.
• Design : Evaluating the current problems with multiplayer campaigns will be needed for this phase. After you have done this, you will have to develop a new savegame format and a design for the code that is processing it. The delivery will be at least some kind of static model (preferably UML but other techniques will do as well) and a roadmap of steps to get from the current code to the new one.
• Implementing : It is hard to give detailed information about the content of this phase. But basically it will be implementing the roadmap steps one by one.

Proposal contents

Here are some questions and ideas to help you dive into the topic. They are meant to help you get a better idea of what this project is going to be about. They are also meant to show us, how much you made yourself familiar with wesnoth's code, as this is very important to us. We are mostly ambitious and passionate ourselves, and we seek for students that are alike. Other (wesnoth) projects provide the opportunity to present prototypes, which won't be working here. Therefore it is even more important, that you implement some patches to show us your coding skills.
However, there is some preparation you can do by now already. You should also add your thoughts about this to the proposal you are giving us. If you get accepted, this will serve as a starting point for further fleshing out things.

Don't hesitate to seek for help, if you have difficulties with some of the questions. I (YogiHH) will be on IRC most of the time in the evening (GMT+1) hours. You can also reach me by mail (joerg.hinrichs@alice-dsl.de) if that is not sufficient. Also keep in mind, that this is not a typical test with "right and wrong". It is clear that being new you won't be able to make the "perfect proposal" right out of the box. We are more interested in how you approach this task, how you communicate and if you can focus on the relevant stuff without losing yourself into details. So know what you are talking about, be innovative and take initiative.

The following two links are meant to give you further information for that:
savegame code - Contains the pieces of codes that deal with savegames and where to find them
WML - object mapping - A mapping table to show you which objects hold the information of the savegame WML content

1.

If you take a closer look at the code, you will find, that there are different architectures of design to implement persistence. One is a more layered approach, which separates the creation and population of objects from persistent information (a savegame file, represented by a config object) from the rest. Config_adapter.cpp is an example of that idea. The other passes the raw persistence information (=config object) to the object to be created and lets it do the work. An example for this is the game_state constructor that takes a config object as argument.

Which are the pro's and con's of those approaches with regard to encapsulation and maintenance? What would you choose for wesnoth's savegame processing?

2. If your task is to remove config_adapter.cpp, how would you do that? Where would you put the code instead? And what are your reasons for that?

3. The player_info struct and the team class share some information (for example units that belong to a certain side). Do you think it is a feasible idea to mold those two into one? And what are your reasons?

4. The same question is to be asked for the game_state class and the gamestatus class.

5. The second link above contains a mapping table, that matches savegame WML tags to C++ objects. Identify candidates for redundancies. Warning: Keep in mind, that WML is a mighty beast! Just one example: Through WML events, a map can change throughout a scenario. Therefore it makes a lot of sense to put that map into the [snapshot] and [replay_start] tags respectively, although at first glance it looks like we could put it into some central place. After you identified candidates for redundant information, you might want to talk to one of the WML experts to make sure those information is really redundant.

6. Based on the thoughts you layed out in 1-5, what would the new savegame structure you propose be like? A level of detail like it is outlined in the mapping table will suffice here. Please also make sure, that your proposal is consistent with the idea of multiplayer campaigns.

See also

Summer of Code Ideas - The root where all information regarding SoC is (or better should be) linked from.
savegame contents - Some ideas about the current and future content of savegames.
Savegame WML - Information about the format used for storing savegame information.