View source for SummerOfCodeProposal Euschn

==GSoC 2009: Summary==
This is a short summary of my main achievements during my project "savegame reorganization" in GSoC09

===savegame redundancy elimination===

I have eliminated several redundancies in save files, the biggest being the [player] tag, which contained persistence (aka carryover) information of sides in campaigns. for example, carryover gold and recall lists are no longer stored twice, which decreases the savegame file size considerably.

===redesign of the savegame code===

in order to provide a better design for the savegame C++ code, the following changes were made:

* handling of game data: improved the interface between high-level C++ objects and savegame WML/config based data. high-level objects (team, unit,...) are used in the scope of play_controller (i.e., within a single scenario). WML/config objects are used for reading/writing savegames and between scenarios (persistence/carryover information).
* added interface-style class savegame_config: an interface for creating WML/config data out of high-level C++ objects
* added class savegame: an interface for reading and writing save files.

* removed the classes config_adapter and gamestatus.
* removed the struct player_info (which was largely redundant to class team)
* added the classes tod_manager (turn/time of day information) and game_classification (meta-information of a scenario)

===improved persistence of sides===

I have added an optional flag 'persistent' to SideWML. This allows for better control of which sides have their information stored for future
scenarios in a campaign: at the start of my project, all sides with human controllers were automatically set as persistent. Now, by using
the 'persistent' flag, ai sides can be made persistent aswell - and human sides can be set as non-persistent likewise. Additionally, 
persistent sides can now "pause" (i.e., not appear) an arbitrary number of scenarios before returning in a future scenario (without using
additional WML variables to manually store these sides).

===mulitplayer campaign improvements===

In combination with the previous point, I have made some changes to the persistence mechanism to improve the handling of multiple persistent
sides in mp campaigns. I have updated the corresponding wiki page accordingly. Creating and playing multiplayer campaigns should now be
less tedious.

===updated uml model===
http://stud3.tuwien.ac.at/~e0204097/wesnoth/post_gsoc.jpg

==Euschn's SoC Proposal: Savegame Reorganization==

==Milestones and Timeline==



=== Possible Milestones ===

1) the UML model of the new design

2) removal of WML redundancies in savegames (where possible)

3) implement the unified design (partitioned into a pre and post midterm milestone)

4) documentation of the implementation

===Savegame Reorganisation: game_state and play_controller tasks===

These are the first batch of coding tasks of savegame reorganisation. They reflect the changes to game_state and play_controller proposed in the uml design. (tasks have prerequisites where noted)

1) remove config_adapter. move its functionality to controller_base, play_controller and team_manager.

2) add the members gold_add, carryover_gold and available_units (recall list) from player_info to team_info.

3) move turn related functionality to play_controller.

4) create (interface style) class SavegameConfig.

5) create class tod_manager (time of day functionality). Move from gamestatus to play_controller. Needs 4).

6) create class game_classification and add it to game_state.

7) merge game_state and gamestatus. Needs 3),5).

8) remove map of players and teams vector from game_state. Change references from these objects to references to play_controller's teams vector. Needs 2)

9) update do_replay and do_replay_handle in class replay. needs 7).

10) Implement SavegameConfig for class team. Needs 2),4).

11) Implement SavegameConfig for classes game_events::event_handler, game_display, soundsources::manager and sound::music_track. Needs 2),4).

12) Implement SavegameConfig for play_controller. Needs 2),4),9),10).


===SavegameWML related tasks===

13) Add a carryover_gold key to SavegameWML (replay_start.side, snapshot.side). Needs 2).

14) Add the unique keys of the [player] tag to [side]. Needs 2).

15) Change the savegame code to read teams information from [side] only. Needs 2),14).

16) remove the [player] tag. Needs 2), 8), 14), 15).

17) remove the root/[snapshot] redundancies via the implementation of savegame_config for game_classification, game_state and play_controller. Needs 6), 12).

=== Timeline ===



april 20th - may 15th: "bonding peroid": 

 * get familiar with the code and WML
 * start the documentation of the current implementation of savegames
 * evaluate the problems with/needs for multiplayer campaigns
 

may 16th - may 31st: the actual start of work:

 * finish evaluation of problems
 * develop a new design of "unified" savegames
 * deliver UML model

june 1st - june 15th:

 * start of implementation:
 * determine set of features/milestones to be ready for mid-term
   examples: singleplayer functionality, replay functionality, multiplayer campaign features,...

june 16th - june 30th:

 * implementation of mid-term feature set
 * track progress, compare to timeline

july 1st - july 11th: 

 * finish implementation of the mid-term feature set
 * goal: have a (partially) functional implementation for mid-term

july 12th - july 19th:

 * vacation

july 20th - august 2nd:

 * implementation of missing features

august 3rd - august 17th:

 * testing, bug fixing
 * documentation of implementation (additions and changes to the UML model)

===Detailed per-week timeline===

Task duration estimations are based on:
 * my experience with submitting my first patch
 * my general feel for my skills/speed
 * http://www.overcomingbias.com/2007/09/planning-fallac.html 


{| border="1"
|+ '''week 1 (20.4.-26.4.), time budget: 3 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 0
| https://gna.org/bugs/?13268 : identify the source of the reproducable bug I discovered. (assumption: dismissals are not/wrongly stored in a replay under certain conditions)
| 1
| yes
|
|-
| 1
| https://gna.org/bugs/?13268 : Implement a fix for the reproducable bug and perform tests. goal: 2nd submitted patch to gain dev access
| 2
| yes
|
|}


{| border="1"
! id
! task
! duration (days)
! complete
! note
|+ '''week 2 (27.4.-3.5.), time budget: 2-3 days'''
|-
| 3
| document MP campaign savegame problems and differences to SP campaigns
| 1
| yes
| 
|-
| 4
| get up to date on recent savegame code changes (e.g., savegame class)
| 1
| yes
| 
|}


{| border="1"
|+ '''week 3 (3.5.-9.5.), time budget: 2-3 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 6
| investigate possible relation of gsoc mp protocol tasks to savegames. test reported problems (broadcast of [story] wml to clients in mp campagins)
| 1
| yes
| story broadcast works fine
|}


{| border="1"
|+ '''week 4 (10.5.-16.5.), time budget: 2-3 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 7
| further investigation of existing MP campaigns: Analyse scenario wml and savegames. What workarounds are used to solve MP campaign problems (e.g.: difficulty, gold/recalls,...). Candidates for testing: World Conquest, Unnatural Winter, Elf War (MP version)
| 1
| yes
| 
|-
| 8
| Investigate bugs reported in http://www.wesnoth.org/forum/viewtopic.php?f=15&t=25346 and (https://gna.org/bugs/?13016). Goal: reproduce any of these bugs with existing MP campaigns
| 1
| yes
| unable to reproduce host switching or side color bug in either Unnatural Winter or World Conquest
|}


{| border="1"
|+ '''week 5 (17.5.-23.5.), time budget: 4 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 2
| create a minimal multiplayer campaign to get to know the current hassles with MP campaigns and analyze their savegames in comparison to SP campaign savegames. campaign features: 2 players, 2 scenarios, <5 turns to complete each scenario.
| 1
| yes
| http://stud3.tuwien.ac.at/~e0204097/wesnoth/mpcs.zip
|-
| 9
| UML: Design a class diagram for gamestatus/gamestate incorporating the changes from the proposal.
| 1
| yes
| 
|-
| 10
| determine impact of class changes: which classes need to be adapted and how? (obvious candidates: play_controller, savegame)
| 1
| yes
| move from game_state/staus to play_controller: list of team objects, tod functionality; from config_adapter to play_controller: get_unique_saveid, get_theme (the latter to controller_base actually)
|-
| 11
| Investigate broken WC replay: http://www.wesnoth.org/replays/1.6/20090513/MP_campaign_-_World_Conquest_2_Turn_15_(6448).gz . Determine relevance/connection to savegame reorganisation (might have other causes)
| 1
| yes
| could not determine the specific source of the bug (misplaced units/non-existing locations for units?)
|}


{| border="1"
! id
! task
! duration (days)
! complete
! note
|+ '''week 6 (24.5.-30.5.), time budget: 5 days'''
|-
| 5
| refine the originally proposed savegame wml and C++ object mapping changes based on the results of MP campaign problem and game_state redesign investigations
| 1
| yes
| investigate connections between mp player name, wml leader name and (save_)id in mp games.
|-
| 12
| UML: design a class diagram of play_controller (and possibly subclasses/superclass) including the changes implied by game_state change
| 2
| yes
| 
|-
| 13
| UML: design a class diagram of savegame including the changes implied by game_state change
| 1
| yes
| 
|-
| 14
| UML: analyze the replay class with respect to game_state changes and design a class diagram if needed
| 1
| yes
| 
|}


{| border="1"
|+ '''week 7 (31.5.-6.6.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 15
| removal of config_adapter: move its functions to controller_base, play_controller and teams_manager
| 1-2
| yes
| 
|-
| 16
| create (interface style) class SavegameConfig and implement it for class team
| 1
| yes
| 
|-
| 17
| create classes tod_manager and game_classification, implement SavegameConfig.
| 1
| yes
| 
|-
| 18
| Implement SavegameConfig for sound related classes.
| 1
| partial
| holding back music_track until a solution for append key is found
|}


{| border="1"
|+ '''week 8 (7.6.-13.6.), time budget: 4-5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 19
| move turn and time of day functionality from gamestatus to play_controller.
| 2-3
| partial
| remaining: unit, terrain_filter, some ai related classes
|-
| 20
| start implementation of savegame_config for play_controller: build config of tod/turn information. goal: everything should be functional after tod/turn migration.
| 1
| yes
| implemented to_config(), but it is not yet used in game_savegame
|-
| 21
| set up more concrete tasks on savegameWML refactoring. (currently, they are implicitly contained in savegame_config implementation tasks)
| 1
| yes
| 
|}


{| border="1"
|+ '''week 9 (14.6.-20.6.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 22
| move the teams vector from gamestatus to play_controller
| 3
| no
| 
|-
| 23
| finish tod/turn migration from gamestatus to play_controller
| 1-2
| yes
| only remaining tod turn functions are in assertions and the no longer used function actions::timeofday_at
|}


{| border="1"
|+ '''week 10 (21.6.-27.6.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 24
| remove the gamestatus functionality from class savegame
| 2
| yes
| 
|-
| 25
| remove class gamestatus from the source code
| 2
| yes
| 
|-
| 26
| investigate handling of carryover gold: How is it generated and stored for the next scenario? (in preparation of player/team merge)
| 1
| yes
| 
|}


{| border="1"
|+ '''week 11 (28.6.-4.7.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 27
| Develop a solution to save carryover gold without using player_info. main problems: scope of teams, correct saving of "end of game" replay
| 1
| yes
| 
|-
| 28
| implement the solution to remove carryover gold functionality from player_info
| 2-3
| yes
| 
|-
| 29
| investigate handling of recall lists. set up tasks that are needed to migrate them from player_info to team.
| 1-2
| yes
| 
|}


{| border="1"
|+ '''week 12 (5.7.-11.7.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 30
| populate team.recall_list_ to be consistent with player_info.available_units
| 2
| yes
| 
|-
| 31
| add a reference to team.recall_list_ for each reference to player_info.available_units
| 2
| yes
| 
|-
| 32
| remove all references to player_info.available_units
| 1-2
| yes
| all remaining references are in class gamestatus
|}


{| border="1"
|+ '''week 14 (19.7.-24.7.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 33
| complete the removal of player_info
| 2
| yes
| 
|-
| 34
| develop a solution to remove the [player] tag from either replay_start/starting_pos or snapshot
| 1
| yes
| 
|-
| 35
| implement the removal of the player tag in replay_start or snapshot
| 1-2
| yes
| remove [player] from snapshot, keep for inactive sides only
|}



{| border="1"
|+ '''week 15 (25.7.-31.7.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 36
| develop a solution to remove the [player] tag from snapshot
| 1
| yes
| 
|-
| 37
| implement the removal of the [player] tag from snapshot
| 2
| yes
| 
|-
| 38
| analyze the handling of MP scenario files and develop a solution to add difficulty options to MP scenarioWML. begin with the implementation.
| 2
| partial
| difficulty options for MP games is more complex than it seems at first glance. implementation might be out of scope of GSoC
|}


{| border="1"
|+ '''week 16 (1.8.-7.8.), time budget: 5 days'''
! id
! task
! duration (days)
! complete
! note
|-
| 39
| remove vector<team>, unit_map, gamemap and tod_manager members from game_savegame by implementing savegame_config for play_controller. play_controller should build the snapshot out of the above objects via to_config() and pass it to game_savegame.
| 2-3
| yes
| 
|-
| 40
| polish some of the code created in GSoC. obvious candidates: get_player_info(), new teams_manager code, WML recruit tags
| 1-2
| no
| 
|}

==Questionaire==


hi, I'm euschn and I would like to contribute to wesnoth via GSoC

real name: Eugen

age: 26

location: Vienna, Austria

occupation: phd student for computer science, Vienna University of Technology


====1) Basics====

'''1.1) Write a small introduction to yourself.'''

My name is Eugen Jiresch, I live in Vienna, Austria, and I am 26 years old. I am a phd student in computer science at the Vienna University of Technology. My phd project is about formal models of computation and theory of programming languages.
Despite the theoretic focus of my phd, I like coding a lot, which is one of my reasons for applying for GSoC.

'''1.2) State your preferred email address.'''

jiresch_(atsign)_logic_(dot)_at

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

euschn (same as my gna.org account)

'''1.4) Why do you want to participate in summer of code?'''

There are several reasons. First, I would like to take part in an interesting software development project. 
By doing so, I want to improve my skills and learn new things about programming. Then, being a gamer myself, I am very interested
in contributing to the development a computer game, especially one that seems cool and fun to me (Wesnoth falls in that category). I have often dreamed about a job in game development in the future, and this could be a good opportunity to get started.
Additionally, if I want a job for the summer, I want it to be something that is meaningful to me and needed/appreciated by others - like adding desired feature to a game.
Finally, being a poor student, 4500$ is a lot of money to me.

'''1.5) What are you studying, subject, level and school?'''

As mentioned above, I am a phd student in computer science, at Vienna University of Technology

'''1.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 Wesnoth. If you have gained commit access to our S&shy;&shy;V&shy;&shy;N (during the evaluation period or earlier) please state so.'''

I submitted https://gna.org/patch/?1148 , improvement of random village (and landform) naming.

====2) Experience====

'''2.1) What programs/software have you worked on before?'''

Most of the software I have done was for university courses. I have done a bit of programming in games that support modding/custom maps like Starcraft or World of Warcraft, but nothing too fancy.
Recently, I became a contributor to the inets project (see 2.4.1)

'''2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)'''

Yes, in university courses and the inets project (see 2.4.1)

'''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.

====2.4) Open Source====

'''2.4.1) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.'''

Yes, I recently became contributor to the inets project ( https://gna.org/projects/inets/ ). inets is a compiler from an interaction nets based language to C (for more information, see http://www.interaction-nets.org/)
Interaction nets is an innovative formal model of computation, which is also a focus of my phd project.
My involvement so far has been the implementation of extended pattern matching for the computational rules of the inets language, and some bug fixing.

====2.5) Gaming experience - Are you a gamer?====
Yes, since early childhood!

'''2.5.1) What type of gamer are you?'''

I am a passionate gamer, maybe even hardcore - allthough the definition of hardcore is quite fuzzy depending on game and community :).
In short, I spend a *lot* of my free time playing computer games and checking out their respective communities.

'''2.5.2) What type of games?'''

My favorite genres and games include:

Role playing games: Final Fantasy series, Zelda series, Baldurs Gate series, Diablo series,...

Strategy games: Warcraft series, Starcraft, Spellforce, and just recently Wesnoth

Platforming: the usual old school nintendo stuff

Action: Quake series, Metroid series, Portal


singleplayer vs multiplayer:

I enjoy a good singleplayer game a lot. But I also like multiplayer, and I am doing a lot of online multiplayer gaming.
For example, a few years ago I was playing Warcraft 3 online a lot, and got to know the online community pretty well.
So while I have not played Wesnoth a lot, I have a good feeling for online gaming communities. (if they are comparable at all!)

'''2.5.3) What type of opponents do you prefer?'''

I like opponents that can teach me something and help me improve my skills in a game, or just generally make a game fun.
To me, playing against a good and fun oponent in a multiplayer game makes winning or losing of secondary importance.
Generally, I do not like oponents who are sore losers, and I am doing my best not to be one, either.

'''2.5.4) Are you more interested in story or gameplay?'''

I would say it depends on the game. Awesome gameplay can make a great game even with a lackluster story (or none at all). 
In my opinion, this is often true for multiplayer games, where most of the fun comes from human oponents (or allies). But singleplayer games 
with a weak story can be great, too (everyone who has ever enjoyed a Super Mario game has to agree).
Then again, I remember many cool games especially for their story (RPGs mostly, but also some strategy games).
So all in all, either can make a great game and I am interested in both.

'''2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.'''

I only recently got to know Wesnoth. I have played some of the singleplayer campaigns, and I like it a lot so far. It is a nice mix of strategy and roleplaying, and I plan to continue playing it 
(apart from getting to know it for GSoC!). I understand that being an experienced wesnoth player helps with some projects, I hope this is not so mandatory for savegame reorganization.

====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.'''

I am a German native speaker, but I feel I can fully express myself in English.

'''3.2) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.'''

Yes, I am fine with interacting with other players, even if it is going to be rough. As mentioned in 2.5.2), I have experience with online gaming communities (especially Blizzard games), 
so I am used to their not so friendly aspects.

'''3.3) Do you give constructive advice?'''

Absolutely, I try to keep my advice as constructive as possible.

'''3.4) Do you receive advice well?'''

Yes, constructive advice is a chance to improve myself, and I always give my best to take that chance.

'''3.5) Are you good at sorting useful criticisms from useless ones?'''

Yes.

====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?'''

Yes, I selected Savegame reorganization.

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

'''4.3) Why did you choose this project?'''

There are several reasons. First, I want to work on a project that is deemed necessary or desired by the wesnoth community. I think redesigning savegames is such a project.
I do not want to work on some feature that noone really wants.
Second, I like the concept of multiplayer campaigns. Cooperative multiplayer games are good fun (I like them a lot myself), but they are rare. Only few games have coop modes, especially in combination with 
story-driven game types like a campaign in wesnoth. So if I can help to promote cooperative game types by improving wesnoth's savegame design, I will be very glad to do so.
In general, it seems to me that studying a "messy" design (Im quoting the wiki here) and trying to come up with a better one is a good challenge that I would like to take. Also, I am
curious how this component works in a project of this size, as I have not yet worked on such a big program and I would like to learn what makes it tick.
Finally, I think I have the required skills to succeed at this project (with help from my mentor of course!). I have good C++ skills and I feel up to
study the current implementation and develop a deliberate design in cooperation with my mentor.

'''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".'''

My estimated timeline is affected by both "special things" mentioned in the question.
First, I will have to spend some time on university stuff up to mid June. In this period, I can of course still work on the GSoC project, just not full time. 
I think that I will be able to work 20-25h a week on wesnoth during that time. To tackle this problem, some people at #wesnoth-dev have suggested that I start early, which is generally possible.
I could start on the actual work as soon as May 16th, which is a week earlier than the official date. This could help me to regain the lost time.
Note that this estimation is more on the worst-case side. '''update:''' It looks like I will have more time in June anyways, but I still cannot guarantee it. I will do the "early start" in any case.

Still, if you think this is not feasible, please tell me so I can reconsider my options.
Second, I will most likely be on vacation from July 12th to July 19th. I hope this would not be too much of a problem.

see [[SummerOfCodeProposal_Euschn#Milestones_and_Timeline|below]] for a more detailed timeline.

'''4.5) Include as much technical detail about your implementation as you can'''

The description of the Savegame project in the wiki suggests that several technical details will be unclear until the design, which is a rather large milestone itself, is fleshed out.
Concerning the design milestone, I plan to deliver a UML model describing the new savegame organization.

'''4.6) What do you expect to gain from this project?'''

I would like to:
 * gain insight on the development of large open source projects
 * learn more about game design
 * improve my coding skills
 * last but not least, I want to gain the satisfaction of contributing something worthy to such a big project

'''4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?'''

The success of my project and/or the feeling that I have not completely made a fool of myself :).

====5) Practical considerations====

'''5.1) Are you familiar with any of the following tools or languages?'''

   * Subv&shy;&shy;ersion (used for all commits)
Yes, I have used S&shy;&shy;V&shy;&shy;N for university projects and my master thesis.
   * C++ (language used for all the normal source code)
Yes, I think I have good C++ skills. To elaborate with the C++ quiz on http://www.wesnoth.org/wiki/Hackingwesnoth : I fit in the "can answer most questions" category (I looked up the ones I did not know of course).
   * Python (optional, mainly used for tools)
Sorry, I do not have Python skills.
   * build environments (eg cmake/autotools/scons)
I used autotools in a university project.

'''5.2) Which tools do you normally use for development? Why do you use them?'''

For larger projects: Eclipse, Netbeans. I use them for their debugging capabilities and for convenience features like code completion
for smaller stuff: vi, sometimes jEdit, gdb. I use them for their simplicity and their wide availability.

'''5.3) What programming languages are you fluent in?'''

Java, C++, Haskell. I have mostly used them in university courses. Additionally, I have been a tutor for undergraduate Java courses and used Haskell for my masters project.

'''5.4) What spoken languages are you fluent in?'''

I am a German native speaker and I am fluent in English. I also speak a bit French and Russian

'''5.5) At what hours are you awake and when will you be able to be in IRC (please specify in UTC)'''

Austria is UTC+2, so my usual working/availability hours would be UTC: 7am - 3pm, but its flexible to some degree. On some days, I will most likely be available longer into the evening.

'''5.6) 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.'''

I would mind not at all. I am fine with both phone and voice chat if you can bear with my german accent :).

==Ideas on Savegame Reorganization==

===MP campaign problems===

The following issues were reported on the forums:
http://www.wesnoth.org/forum/viewtopic.php?f=15&t=25346 .

More details to come as I try out MP campaigns myself.


'''observers cannot directly advance to the next scenario'''

rejoin via lobby required.

'''problems when hosts are changed (i.e., someone other than the original host loads a game)'''

recall list is potentially messed up, e.g., doubled or lost.

'''side colors do not persist through the course of a campaign'''

side colors are initially costumizable, but reset to default at some point/condition.


'''todo's'''

- try Unnatural Winter by Rhuvaen

- try Mythological's MP campaign

- try World Conquest by TL 



===config_adapter vs game_state===
The game_state class populates its fields directly from a config object (supplied as constructor argument). config_adapter::get_player_info takes existing C++ objects - a vector of team objects, a unit_map, a gamemap,... -  and populates them with a config object and a game_state object.

While the layered approach of config_adapter does create some separation between C++ code and raw persistence information, it results in worse encapsulation: config_adapter needs to be able to access a lot of data of game_state and gamestatus. encapsulation could be improved with the method of directly populating game state.

It seems the current design favors the latter approach. I would stick to this general design for savegame processing.

This leads to the (already posed) question of how to remove config_adapter. Actually, the methods of config_adapter are already hardly used: only play_controller::init uses get_player_info(), get_first_human_team() and get_unique_saveid(). get_theme() is used by a couple of other classes, but that is only a few lines of code, which could be easily moved somewhere else.

From my first impression, it would make sense to move the code into game_state or gamestatus (which could be merged aswell, see below), as they already have code for similar purposes (e.g., the game_state constructor or game_state::get_player() ).

===player_info vs team_info===

most of player_info's fields are also stored in team.team_info. Therefore, it would make sense to merge those two.

From my current understanding, the only information that is exclusive to player_info is gold_add and the recall list available units. These should be added to team_info. This also makes sense with respect to multiplayer campaigns: Several teams might have recallable units and carryover gold from previous scenarios.

Note that at the moment, carryover gold is stored in player.gold, where as the current gold is stored in team_info.gold (meaning replays rely on player_info to determine the correct starting gold value). This seems confusing to me. An easy fix would be to add a carryover_gold member to each team_info. (see also: comparison of [player] and [snapshot.side] below)

===gamestatus vs game_state===

game_state contains most of the savegame information, such as general information (label, version, campaign_type, etc.), a list of players and the config objects corresponding to the snapshot, the initial state, and the replay data (basically all steps/events/moves since the start of the scenario).

gamestatus seems to act as a wrapper class for a game_state, containing some "global" game information itself (time of day, number of turns). gamestatus also contains a vector of team objects, whereas the player_info objects are held by game_state. Since they share a lot of information it would make sense to have them contained in the same class.

It could be an option to merge gamestatus and game_state. Both classes seem to serve the same purpose, and the distribution of game information between them seems arbitrary: why should game_state not contain the list of teams? why are some fields of game_state not considered "global status" (e.g., campaign_type or random_seed) and hence put in gamestatus? Additionally, merging these two classes might improve encapsulation aswell (Since gamestatus needs to access game_state fields at the moment).

===WML Mapping Redundancies===

In general, we can distinguish between two types of redundancies:

'''A:''' information is stored in two or more places in a savegame file (WML), but is mapped to the '''same c++ object.'''

'''B:''' information is stored in two or more places in WML, and is mapped to '''more than one c++ object'''.

Both types are worth fixing.

As mentioned on [[SoC_Ideas_Savegame]], WML events can change a lot of information of a scenario, which makes some redundancies, e.g., between [snapshot] and root/[replay_start], necessary. I will list some info in WML that I think is unnecessarily redundant. (and verify my thoughts with a WML expert).


'''root vs [snapshot] (type A)'''

serveral fields appear on the root and again under [snapshot]. The following are candidates for redundancy elimination:

 * abbrev
 * version
 * campaign (SP only)
 * campaign_type
 * campaign_define
 * random_seed
 * difficulty
 * random_calls
 * underlying_unit_id (task?)


I think these need to be stored twice: (as they can change through the course of the scenario)
 * label (different in root and [snapshot])
 * completion
 * end_text_duration (different endings possible)


'''[player] vs [snapshot.side] (type B)'''

[player] (SP only) only holds a few items, most of which occur in [snapshot.side]. Additionally, both map to different c++ objects, player_info and team.info_. These common attributes are:
 * save_id/id/current_player
 * name
 * gold
 * can_recruit/recruit

The only attribute of [player] that does not occur in some form in [side] seems to be gold_add (whether carryover gold is added to the start_gold or the max of the two is taken as start_gold).

Hence it makes sense to integrate [player] into [side], though there are a few things to consider. For example, the information on gold is saved in a messy way: For each team, the game needs to store the current gold, the starting gold and (in campaigns) the carryover gold. At the moment, the current gold is stored in snapshot.side, the starting gold is stored in [snapshot.side] and [replay_start], and the carryover gold is stored in [player] and [snapshot.side] (in start_gold, as a sum of start+carryover). So, assuming replays do not access snapshot data (its empty in replay files), they rely on [player] to get the correct starting gold.
Obviously this can be organized in a better way.



'''[player] vs [snapshot.player] (type A)'''

These two tags have exactly the same values. (depending on the status of http://www.wesnoth.org/wiki/EasyCoding#consistent_player_information , this might be fixed already?)



'''[replay_start.side] vs [snapshot.side] (type B ?)'''

[replay_start] needs to have information on the initial state of a side. Therefore, it should save all attributes of side that can be changed by WML. Yet, as replays do not access [snapshot], there are also some unchangeable (and hence redundant) attributes in [replay_start]. It would make sense to move them to a central place (e.g., the root).

These seem unlikely to be changed with WML events:

 * flag
 * flag_icon
 * flag_rgb

These are probably changeable:

 * controller
 * fog
 * shroud

the following keys are associated with units. They do not necessarily need to be saved in [snapshot.side], as side contains all unit information in [unit] tags anyways:

 * unrenamable
 * side
 * type
 * canrecruit
 * recruit
 * id
 * name

[replay_start.side] also has a 'gold' attribute storing the starting gold (without carryover), where [snapshot.side] stores the starting gold (with carryover) in 'start_gold' and uses 'gold' for current gold.


''' game events (type A?) '''

It seems that most game events are stored redundantly in [snapshot] and [replay_start]. Can WML events change other WML events? If not, they could be moved to a central place aswell?

update:

''<silene> yes, you can have more event in the snapshot (created events are added), and you can also have less events in it (consumed events are removed)''

An idea to reduce redundancy nevertheless: store all events in [replay_start] or a central place, and only track changes in [snapshot]: new tags for removed and added events could be added. To see if this idea is feasible, further investigation will be needed.


''' player.name vs player.leader.{name,id,current_player} '''

In the savegames of TLs World Conquest, the [player] tags have a [leader] tag describing the leader of the side. Both tags have a name key that stores the MP nickname of the player. leader.id and leader.current_player seem to derive from the MP nick aswell. This might be the cause of the bugs introduced by switching hosts (http://www.wesnoth.org/forum/viewtopic.php?f=15&t=25346).

MP nickname and the name of the leader should be made indepent to avoid problems when different players pick up a side. This might also be related to the persistence bug (https://gna.org/bugs/?13016).

=== How to improve the organization ===

To summarize the thoughts above, these are the first ideas to reorganize savegames:

'''C++ changes'''

 * remove config_adapter (add the code to game_state)
 * merge player_info and team.team_info
 * merge game_state and gamestatus (or make a clearer distinction between them)


'''Savegame WML changes'''

 * remove redundancies between root and [snapshot]
 * get rid of the [player] tag, add its exclusive information to [side]
 * remove redundancies between [replay_start.side] and [snapshot.side] (where possible)

Another suggestion from the developers is to change the layout of AI information in a [side]: currently, there are some AI related keys at the root of [side], others are wrapped in an [ai] tag. This could be improved to add all keys below a new top-level AI tag.



back to: [[SummerOfCodeIdeas| GSoC Ideas]]

[[Category:Summer of Code]]