The Battle for Wesnoth Wiki - User contributions [en]

SoC Ideas Content Server2011

2011-03-04T23:40:21Z

Dave: Created page with '= Submitted proposals: = {{#dpl: |resultsheader=''There are %PAGES% submitted student proposals for this idea'' |oneresultheader=''There is 1 submitted student proposal for th…'

= Submitted proposals: =

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas IDEA NAME
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

=Description=
<h2>Content Server Improvements</h2>
The Wesnoth Content Server could be improved in a number of ways:

- Add a system for users to rate content and allow others to view the ratings; this rating system should be sophisticated enough to avoid being easily gamed.
- Add a system to see richer details about content, showing screenshots, more descriptions, etc.
- Allow users to write reviews of content.
- Allow content to be flagged as inappropriate.

UsingGooglePerformanceTools

2011-02-06T14:04:09Z

Dave: Created page with 'The Google performance tools are recommended for profiling Wesnoth's CPU and memory usage, especially on Linux. [http://goog-perftools.sourceforge.net/doc/cpu_profiler.html] [ht…'

The Google performance tools are recommended for profiling Wesnoth's CPU and memory usage, especially on Linux.

[http://goog-perftools.sourceforge.net/doc/cpu_profiler.html]
[http://goog-perftools.sourceforge.net/doc/heap_profiler.html]

These performance tools are now shipped with Debian GNU/Linux and many other Linux-based systems.

Wesnoth has been tested successfully using LD_PRELOAD to load the libraries in. Thus on Linux if you just want to profile a run of Wesnoth all you have to do is have the Google performance tools on your system and use something like this before running Wesnoth:

export LD_PRELOAD=/path/to/libprofiler.so
export CPUPROFILE=./cpu-profile.dat

To profile the CPU, or,

export LD_PRELOAD=/path/to/libtcmalloc.so
export HEAPPROFILE=./heap-profile.dat

To profile memory usage.

Then run Wesnoth, exit it cleanly, and you should have a cpu-profile.dat or heap-profile.dat file. The memory profile actually dumps out profile files periodically as it runs.

Then use,

pprof /path/to/wesnoth/binary ./cpu-profile.dat

To read a profile file. There are a number of commands you can run, but suggested is 'gv' to get graphical output.

DevelopersHome

2011-02-06T13:58:44Z

Dave: /* Tools and Packaging */

= General Information =
* Links
** [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
** [http://cia.vc/stats/project/wesnoth Latest commits] - Up-to-date commit messages

* Coding Guidelines
** [[HackingWesnoth]] - guide for programmers
** [[CodingStandards]] - for programmers
** [[DeveloperGuide]] - for those who received SVN commit rights

* Library documentation
** http://www.sgi.com/tech/stl/ - Standard Template Library

= Tools and Packaging =
* Supporting Websites
** [[WesnothSVN]] - accessing the source code
** http://websvn.wesnoth.org/ Web-Access to svn - Gna! - websvn -
** http://gettext.wesnoth.org/ - gettext status
* Compiling and Building
** [[CompilingWesnoth]] - how to compile Battle for Wesnoth (it's not hard)
** [[SCons]]
** [[UsingAutotools]]
* Packaging and Releasing
** [[ReleasingWesnoth]] - steps to follow to release a new version
** [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* Documentation
** [[Doxygen]] - Documentation generator
* More stuff
** [[ExternalUtilities]] (Wercator, CampGen, wmllint, etc.)
** [[MaintenanceTools]] WMLLint, WMLIndent and WMLScope
** [[UsingGooglePerformanceTools]] to profile Wesnoth CPU and memory usage.

= I want to start coding, what can I do? =
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[GettingStarted]]
* [[FrequentlyProposedIdeas]] - summary of past often-repeated forum discussions
* [[Wesnoth_Acronyms_and_Slang]]

= Game - Create content =
* [[BuildingScenarios]] and related useful forum discussions:
** [http://www.wesnoth.org/forum/viewtopic.php?t=4188 Beginning Campaign Development]
** [http://www.wesnoth.org/forum/viewtopic.php?t=4301 A Balancing Act]
* [[ReferenceWML]]

= Code documentation =
* http://devdocs.wesnoth.org - generated code documentation
* AI
** [[AI_Module]] - guide to AI module (src/ai)
** [[FormulaAI]] - Guide to the experimental formula AI branch
* Themes
** [[ThemeSystem]] - customizing the screen layout for the game and the editor
* Multiplayer
** [[WesnothdDesign]] - Guide to the design of wesnothd, the multiplayer server.
* Gui2 - The new Gui-Framework
** [[GUIToolkit]]
** [[GUILayout]]
** [[GUIVariable]]
** Gui2 WML
*** [[GUICanvasWML]]
*** [[GUIToolkitWML]]
*** [[GUIWidgetDefinitionWML]]
*** [[GUIWidgetInstanceWML]]
*** [[GUIWindowDefinitionWML]]
* Savegames
** [[SavegameClassHierarchy]]

= Communication, Feedback, Events =
* Gna! links
** http://bugs.wesnoth.org/ - Gna! - bugs and feature requests
** http://patches.wesnoth.org/ - Gna! - patches

* Mailing lists
** https://mail.gna.org/listinfo/wesnoth-dev/ - wesnoth-dev
** https://mail.gna.org/listinfo/wesnoth-commits/ - wesnoth-commits

* IRC
** [irc://irc.wesnoth.org/#wesnoth-dev freenode/#wesnoth-dev] - IRC (alias to irc.freenode.net)
** http://irclog.wesnoth.org/ - IRC logs

* Forum - http://forum.wesnoth.org

* This wiki - http://www.wesnoth.org/wiki/Main_Page

* FOSDEM
** [[Fosdem2008]]
** [[Fosdem2009]]

* Google Summer of Code
** [[SummerOfCodeIdeas]] - Ideas for GSoC
** [[SoC_Information_for_Google]] - Our organization profile for Google
** [[SoC_People_to_bug_on_IRC]] - Who GSoC students can ask for help

= Miscellaneous =
* [[DebugMode]] and [[CommandMode]] - in game debugging commands
* [http://www.wesnoth.org/units/trunk/animations.html Missing unit animations] - what's available and what's missing
* http://units.wesnoth.org/ - Unit reference

[[Category:Development]]

SoC Ideas WML Debugging

2010-03-24T19:35:42Z

Dave: Created page with '{{SoC2010Idea}} = SoC Ideas: WML Debugging Support = == Background == Wesnoth Markup Language (WML) is used to create most kinds of Wesnoth content: campaigns, scenarios, and …'

{{SoC2010Idea}}

= SoC Ideas: WML Debugging Support =

== Background ==

Wesnoth Markup Language (WML) is used to create most kinds of Wesnoth content: campaigns, scenarios, and so forth. WML is a fairly powerful language, but its debugging features often make it difficult to debug. Incorrect WML typically results in cryptic error messages or unusual and difficult to understand misbehavior.

== Project ==

There are several possible steps in improving WML:

- ensuring that any WML error results in an accurate line number for the error being displayed. This will require modifying the WML pre-processing system to properly map all expanded macros to their original lines.
- improving the quality of error messages: trying to map unterminated strings and tags back to their starting positions.
- schema system: a WML schema system would be developed which would enable WML documents to be validated to make sure they have correct attribute names with values that are formatted correctly.

SoC Ideas Multiplayer server

2009-03-25T18:41:34Z

Dave: /* Required knowledge and talent */

=== Extending the Multiplayer server ===

Our multiplayer community is generally strong and healthy, but we believe its growth is limited by some problems in the interface of the multiplayer lobby.

==== General Description ====
The general idea of this project would be
* To study the current lobby,
* To develop ideas about how our multiplayer interface could evolve to allow it to scale to a much larger community
* And to implement as many of those changes as practical

Some ideas that we had (but that are in no way mandatory):
* Having a simple room system? Again, inspired by IRC
* Having some way to find the type of games you are interested in. filtering by:
** game type
** number of free slots/players
** any other criteria you might find interesting

Other ideas we are not yet convinced are good, but that are certainly worth studying (especially how the communities based around these concepts are different from ours)
* ranking players
* guilds
* official tournaments
* titles for players
* metaservers
* game matching when players are ranked (poker, bridge...)

The scalability of the design (both in term of number of players, and in term of the possibility for players and developers to extend the concept) will be an important criterion.

Administration/moderation problems and techniques should also be studied.

Interaction with the Add-On server/forum should be explored.

An additional feature that could be considered is more secure random number generation to prevent cheating. At the moment, random numbers are generated on the client side. Things could be changed

==== Required knowledge and talent ====

* A fair amount of experience with C++ is required. Wesnoth uses some advanced C++ features and is heavily based on BOOST and STL. We can train you in some of the libraries used, but learning all of them would be a big hurdle.
* Experience with multiplayer games, in order to have a good idea of what multiplayer lobbies of other game look like, and (more importantly) a good idea of the social behaviours of multiple MP communities, how teams are formed in games and things like that.

==== Milestones and deliverables ====

* A first milestone would be a presentation summarizing the different studies, and the proposed interface. preliminary informal stages would probably be desirable, to make sure the proposed idea is already a consensus within devs
** Study of other MP game-matching interfaces and functionalities
** Study of other MP communities
** Study of other MP moderation practices
** Study of the Wesnoth MP community, including needs, various opinions from different developers and players
* A second milestone would be the main code delivery. Code should be functional for it will be delivered in the next Wesnoth development release

=== See also ===
* [[SummerOfCodeIdeas|Summer of Code Ideas]] - The root where all information regarding SoC is (or better should be) linked from.
* [[http://www.wesnoth.org/wiki/EasyCoding#GUI2_related_features]] Easy coding tasks regarding the GUI.
* [[http://wesnoth.org/wiki/GUIToolkit]] Main entry point for the new GUI.

[[Category:Summer of Code]]

SoC Ideas Stats Server

2009-03-24T18:19:25Z

Dave:

Wesnoth has an infrastructure which records details of campaigns that players play into a centralized MySQL database. However, we only have rudimentary reports based on this MySQL database available at this time, at [stats.wesnoth.org]

This project would involve writing a stats reporting web site which would take the data from the MySQL database and produce reports in chart and table form. Campaign designers would be able to use these reports to gather feedback on their campaigns and get ideas for improvements.

A student could largely make their choice of infrastructure for creating the Website -- whether they prefer Python, Perl, Ruby, PHP, etc. This is a great opportunity for someone who doesn't want to dive into hardcore C++ to make a valuable contribution to Wesnoth.

It maybe worth while to track stats from multiplayer games. It could provide useful insights. There are some major difficulties because Wesnoth does not record the outcome of multi-player games.

== Database Details ==

The MySQL database is created with these commands:

CREATE TABLE GAMES (game_id INT NOT NULL AUTO_INCREMENT, timestamp DATETIME NOT NULL, user_id CHAR (14) NOT NULL, serial CHAR (18) NOT NULL, platform CHAR(8), version CHAR (14), campaign CHAR(40), difficulty CHAR(20), gold INT, turns INT, scenario CHAR (40), start_turn INT, time INT, result ENUM ('victory', 'defeat', 'quit'), end_time INT, end_gold INT, end_turn INT, PRIMARY KEY (game_id));

CREATE TABLE SPECIAL_UNITS (game_id INT, name CHAR (40), level INT, experience INT, FOREIGN KEY (game_id) REFERENCES GAMES(game_id) ON DELETE CASCADE);

CREATE TABLE UNITS (game_id INT NOT NULL, level INT NOT NULL, type CHAR (30), count INT NOT NULL, FOREIGN KEY (game_id) REFERENCES GAMES(game_id) ON DELETE CASCADE)

There is a page dumping a sample of data from each table in the database here: [[http://www.wesnoth.org/cgi-bin/stats/dump.pl]]

== Example ==

There is an example of a website which queries from the stats database here: [[http://www.wesnoth.org/cgi-bin/stats/usage-1.6.pl]] -- this website reports the number of Wesnoth scenarios that have been completed, each day since the release of Wesnoth 1.6.

It is an interesting statistic, but what we want is a generic framework for building lots of different, interesting reports. For instance, someone might want to see how many people who use Windows have played, or how many people have been defeated in scenarios, or how many people have played a specific campaign. There are many possibilities, and we'd like a very user friendly framework which allows displaying many different interesting reports.

== Aggregation ==

An additional problem is that the framework can't afford to do a full table scan for every single query. That will just grow too expensive, especially as our database grows larger and larger. Instead, a proposal should work out a way to aggregate common queries into an 'aggregate' table. These aggregate tables would be computed periodically by a separate job.

SoC Ideas Stats Server

2009-03-20T05:27:55Z

Dave:

SoC Ideas Stats Server

2009-03-20T05:27:29Z

Dave: New page: Wesnoth has an infrastructure which records details of campaigns that players play into a centralized MySQL database. However, we only have rudimentary reports based on this MySQL database...

SummerOfCodeIdeas

2009-03-20T05:24:52Z

Dave:

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== I want to be one of your Google Summer of Code students, what should I do... ==

Here is a quick list of things to do to get you started
* Create an account on gna.org
* Create an account on the wesnoth forum, and tell an admin on the IRC channel to mark is as a GSoC Student account (Admins are boucman, Ivanovic, mordante, Shadow_Master, Sirp and Turuk)
* Join the irc channel (#wesnoth-dev on irc.freenode.net) and introduce yourself. We will not give formal interviews, but we will clearly favor people we have learned to know during the selection process (basically communication via IRC is mandatory for our project! it is the main way of "every day communication" for Wesnoth. For the same reason, it's also a good idea to regularly read the [http://wesnoth.debian.net/?C=M;O=A IRC logs].).

* Start a wiki page about your idea, add a link on the bottom of this page and add this information on it:
** List your account names (gna, forum, irc nick) so that we can recognize you
** Fill the questionnaire on this page: [[SoC_Information_for_Google#Does_your_organization_have_an_application_template_you_would_like_to_see_students_use.3F_If_so.2C_please_provide_it_now.| List of questions to answer]]
** Detail your idea as much as possible, look at other students pages, and please give milestones and studies you've done
** Add a link to the page at the bottom of this page

* Though not mandatory, it is highly advisable to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from. You can also implement some features from our feature request database at gna. When you implement something, also list it on your own page with a reference to the patch.

* For working on Wesnoth you have to be able to compile trunk. To do so you should have a look at the [[WesnothSVN|page about svn]] and afterwards [[CompilingWesnoth|compile Wesnoth svn]].

* Once you have everything done here and think your idea is okay, go to [http://groups.google.com/group/google-summer-of-code-announce/web/guide-to-the-gsoc-web-app-for-student-applicants page at google] to submit your application. You have to submit it before '''Date to be supplied later''' or you have no chance to get in!

== List of Ideas for the Project (Suggestions from the wesnoth developers) ==

Here is only a short description of possible Ideas we have, each has a page of its own with a more detailed version on it.

=== Optimize implementation of WML for memory usage ===

Based on this idea: [http://dave.wesnoth.org/?p=9] optimize WML to minimize its memory usage. High memory usage has been a problem for Wesnoth, and this project will aim to reduce it.

=== Implement campaign statistics reports on stats.wesnoth.org ===

Wesnoth has an infrastructure which records details of campaigns that players play into a centralized MySQL database. However, we only have rudimentary reports based on this MySQL database available at this time, at [http://stats.wesnoth.org].

This project would involve writing a stats reporting web site which would take the data from the MySQL database and produce reports in chart and table form. Campaign designers would be able to use these reports to gather feedback on their campaigns and get ideas for improvements.

A student could largely make their choice of infrastructure for creating the Website -- whether they prefer Python, Perl, Ruby, PHP, etc. This is a great opportunity for someone who doesn't want to dive into hardcore C++ to make a valuable contribution to Wesnoth.

[[SoC Ideas Stats Server]] - Full Version of the idea, with detailed information

=== Extending the Multiplayer server ===

Our multiplayer community is generally strong and healthy, but we believe its growth is limited by some problems in the interface of the multiplayer lobby.

[[SoC Ideas Multiplayer server]] - Full version of the idea, with detailed information

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user-made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

[[SoC Ideas Addon Server]] - Full version of the idea, with detailed information

=== WML validation schemes ===
Wesnoth uses WML as basic data structure. Over the years
this language has evolved and got more complex. At the
moment the WML is validated at runtime and in case of a
problem the engine stops. With schemes these problems can
be validated when loading the WML, making it easier to find
problems before running into them.

[[SoC Ideas Schemes]] - Full version of the idea, with detailed information

=== Write a primitive library for Formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth: [[FormulaAI]]

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately, because the skills required to understand and modify it are rather arcane, it is also one of the most neglected parts of the Wesnoth code. This is a place where a lot of research and useful work could be done. But keep in mind that [[WhyWritingAWesnothAIIsHard|writing an AI for Wesnoth is difficult]].

Writing a whole AI is so complicated that we believe it can't be done in a single Summer of code. All proposals should keep that in mind and try to identify an interesting subset that would be workable in the limited time of a summer of code

[[SoC Ideas FormulaAI]] - Full version of the idea, with detailed information

=== Savegame reorganization ===
The savegame formats of Wesnoth for single player campaigns
and multiplayer differ from each other. And they are processed
differently as well. Now there is an additional request coming
up: Multiplayer campaigns. The task will be to unify the savegames
for all types of scenarios in order to provide a maintainable code
again.

[[SoC Ideas Savegame]] - Full version of the idea, with detailed information

=== Other possible ideas to be fleshed out ===
A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the cave generator) etc.

=== Make your own ideas ===
If you have your own idea the best thing is to join IRC wesnoth-dev at irc.freenode.net and discuss the idea with the developers there. If the developers think your idea is interesting and like the feature you can start to turn it into a full proposal. Once done discuss it again on IRC so the developers can accept your idea.

== Information about our Project ==
The information we provided google with about our project can be looked up at the site [[SoC Information for Google]].

Also see the [[DeveloperResources]] link (from the [[Project]] page).

== People to bug on IRC ==
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

[[SoC People to bug on IRC]]

== GSoC Student pages ==

Please add a link to your wiki page below

[[SummerOfCodeProposal_Velory| Velory - SoC Proposal]]

[[SummerOfCodeProposal_AI_Improvement_Crab| Crab - SoC Proposal - AI Improvement]]

[[SummerOfCodeProposal_Sparksteel | Sparksteel - Improving the AI engine design]]

[[Category:Summer of Code|*]]

SoC People to bug on IRC

2009-03-19T20:17:33Z

Dave:

== People to bug on IRC ==
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

=== boucman ===
As our "patch monkey" he accustomed to critiquing patches of every kind. Beside this, he knows many areas of the game due to working on applying patches. He is particularly used to answering question from new coders, and doesn't mind explaining trivial stuff. He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project.

=== Daniel Franke (dfranke) ===
Daniel is the devteam's most recent addition, and has been primarily concerned with security auditing. Bug him <i>privately</i> if you think you've found a security issue.

=== Dave alias Sirp ===
Sirp started Wesnoth and is our lead developer. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

=== Elias Pscherning (elias) ===
He wrote the original version of campgen and as such will know a lot about what is needed to to make such an editor work correctly. The work on a scenario editor might be based upon campgen and as such his knowledge will be really helpful.

=== Eric S. Raymond (ESR) ===
ESR is our project toolsmith; he has written several tools that semi-automate various aspects of WML maintenance. While most of our developers/designers concentrate on either the C++ core or WML but not both, he has a balanced understanding of both levels and may be helpful in helping students develop a grasp of the overall architecture. Finally, he did the last overhaul of the Wesnoth UI and understands UI design principles; he is well-equipped to guide students working in that area.

=== ilor ===
2008 GSoC student, worked on and maintains the new map editor in Wesnoth 1.5/1.6. Has some fairly recent experience with getting "in" the Wesnoth codebase.

=== Karol Nowak (grzywacz) ===
Two years he participated at GSoC as a student, so he will understand the situation of GSoC students. Beside this he is our top expert on Wesnoth for embedded devices as he worked on the gp2x support.

=== loonycyborg ===
Maintainer of Wesnoth's SCons build system and windows packager. Might also help out with other buildsystems.

=== Mordante ===
Many of the possible projects involve the code for which he is an area expert. Also, many of the possible projects currently listed on the ideas page require GUI parts to work. Mordante is currently busy rewriting the old gui engine, he will be our expert there as well as already being our area expert for the terrain engine.

=== Nils Kneuper (Ivanovic) ===
He is doing nothing special, he just does some "administrative work" like packaging fresh tarballs when it is time for them and works on setting up any kind of deadlines and timetables related to releasing. He has administrative powers in most areas, no matter if website, forum or IRC. Beside this he uploads translation updates, tries to communicate with the translation teams when it is required and translates a little bit himself every now and then. But in general he is not a real expert in anything, just has a look at things that come up and redirects people to the correct contacts.

=== Noy ===
Noy is an oddity among developers; he's got no coding skills whatsoever and possesses a limited understanding of computers, which is illustrated by his difficulty operating a Mac. Instead, Noy makes his contribution in gameplay and multiplayer design, drawing upon his background in social sciences research, military strategy and playing games online, to understand the effects of development on the playing community behavior. Along with Soliton, Noy is a useful conduit to discuss any issues in this area; just don't ask him about revising the level of randomness in the game.

=== Noyga ===
Another versatile developer, on the C++ side he doesn't concentrate on a particular area, did some tweaks to improve translations in some languages (like enabling the female forms for names in various place) but know quite well the C++ side of units, abilities and WML. On the WML side he's an expert.

=== Sapient ===
This developer started working on the GUI and widgets, but recently he focused more on improving the internal mechanics of the WML engine such as variable look-ups and filtering. Sapient is not very active anymore but he does come one IRC in the evenings (U.S.A.). He has touched-up many areas of the code in small ways over time, thus he has a good general knowledge of the C++ code and also has worked a little on some python maintenance scripts. He keeps an eye on the quality of incoming C++... especially if you plan on making any changes to GUI or WML, Sapient will be reviewing it closely and with a critical eye.

=== Shadow Master/ShikadiLord ===
He joined the development team very recently, but has enough knowledge to help newcomers with trivial questions about the code and/or the C++ language. His primary focuses are the various WML handlers, such as game events code. His knowledge of the WML language itself is also enough to answer most questions and solve most problems, but only if they are not related to multiplayer games. He also has some basic knowledge of the autotools machinery we use to configure Wesnoth for foreign computers.

=== Dragonking ===

He is one of our best Wesnoth players, and understands the various strategies well. He has also programmed much of the Wesnoth Formula AI system and understands it well.

=== Soliton ===
He knows our MP server setup best. Beside this he has already done a lot of work on the MP server himself. So he probably has most knowledge about it and, being one of our MP-developers, might provide important help from the perspective of the MP player community and what is needed there.

=== YogiHH or Piotr Cychowski (cycholka) ===
Since they are the two developers who know most about building under Windows, they will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.

=== zookeeper or Mythological or Rhuvaen ===
As our leading WML experts those are to be contacted when it comes to anything related WML problems since they know this stuff best. They do maintain most of the campaigns and improve them whenever they have a good idea for changes.

=== See also ===
[[SummerOfCodeIdeas|Summer of Code Ideas]] - The root where all information regarding SoC is (or better should be) linked from.

[[Category:Summer of Code]]

SoC Information for Google

2009-03-10T18:40:05Z

Dave: /* Who will be your backup organization administrator? Please include Google Account information. */

== SoC Information for Google ==
==== Describe your organization. ====
The Battle for Wesnoth, or simply Wesnoth, is a free turn based strategy game with role playing elements designed in June 2003 by David White (Sirp), who currently works at Google.

The game's general [http://www.wesnoth.org/wiki/WesnothPhilosophy philosophy] (both for gameplay and coding) emphases simplicity. The core rules are meant to be easily learned but also provide interesting gameplay and diverse strategies. Strength of the project is reflected in application of Wesnoth Markup Language (WML), which provides a simple language to easily customize scenarios. It has created a significant modding community that has generated a considerable amount of user content.

The first stable release (1.0) was on October 2 2005, with the latest stable release (1.6) anticipated in the next few weeks. According to Ohloh, a site that collects activity statistics on open-source projects, the Wesnoth development effort is in the top 2% of largest and most active projects.

Wesnoth has grown substantially and is considered one of the largest open source games around.
* two servers (stable and developement) with a usual minimum load of more than a hundred players
* more than two thousands downloads a day
* 3 million downloads via sourceforge.net, many more via various mirrors of Linux Distributions
* best rated game at the [http://www.happypenguin.org/list?sort=avg_rating linux game tome]
* game of the year 2007 and 2008 at [http://www.linuxquestions.org/questions/2007-linuxquestions.org-members-choice-awards-79/open-source-game-of-the-year-610236/ linuxquestions.org]
* One of the top 20 rated projects on [http://freshmeat.net/stats/#rating Freshmeat] (currently 14th highest rating, and the highest rated game).

Wesnoth's most notable features include;
* A mature project, but with active development and many improvements
* High quality artwork: both graphics and music
* Very well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after five years of development, and a very solid, fun product has been created, there are still plenty of new developers, and the number of commits to SVN is still increasing
* Strong support of internationalization with many supported languages and thus experience in working with not native English speakers (more than half of our developers are not native English speakers)

==== Why is your organization applying to participate in GSoC 2008? What do you hope to gain by participating?====

Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

If a student were dedicated to any of these uncovered areas, we believe that person could be brought up to speed relatively quickly and function as a peer of the existing developers.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that have lagged behind

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation.====
Wesnoth participated in GSoC 2008 with four students. Out of these, two were great success (that is they became full-fledge developers before the actual start of GSoC), did huge improvement during GSoC (A new recruitment algorithm for the AI and the basic structure for a new level editor), and are still active developers in the Wesnoth community.

Of the two other, one of them was very active for the first half of GSoC and provided some useful infrastructure for AI development that we plan to use this year in GSoC, but was much less active and didn't reach expectations for the second half of GSoC. The lesson we learned is that great students should be left on their own, that's the best way to have them work, but average students should be monitored much more closely than we did. If things seems to start to go wrong, it's important to react very quick, to meet with other mentors and get things back on track early.

Timezone problems were also a serious barrier for student/mentor communication, and we will take that more seriously into account when pairing mentors and students

For our other students, multiple problems collectively led to failure
* We should enforce IRC communication, E-mail is a barrier. This applies both for students and mentors. Both should be on IRC several hours a day, with a huge overlapping of the hours.
* We should be more strict about mid-term evaluation. If the student is slightly lacking at mid-term we should get the message clear that he needs to get back on track.

==== If your organization has not previously participated in GSoC, have you applied in the past? If so, for what year(s)?====

We only applied and participated in GSoC 2008

==== Who will your organization administrator be? Please include Google Account information.====
Nils Kneuper (Ivanovic)

crazy.ivanovic |ATTT| googlemail.com

==== What license(s) does your project use?====
Our project is entirely GPL.

All code is GPL.

All art is GPL, 99% was made for the project, everything else was taken from content that was checked to be GPL.

For more information on the licenses for the game and wiki, see [[Wesnoth:Copyrights]].

==== What is the URL for your ideas page?====
Our main summer of code page is located at http://www.wesnoth.org/wiki/SummerOfCodeIdeas

This page contains various coding ideas and the thought the development team has already given them.

It also contains a list of the developers that are the most active on IRC and their domains of interest.

==== What is the main development mailing list or forum for your organization?====
Regarding development, the most important discussions are also posted on "wesnoth-dev@gna.org". Beside this some work happens at http://www.wesnoth.org/forum/. In particular, all art development takes place on the forum.

Most work and discussions take place in our (logged) IRC channel ''#wesnoth-dev''.

==== What is the main IRC channel for your organization?====

All our IRC channels are on the ''freenode'' network

* ''#wesnoth-dev'' is the main development channel, where most discussion takes place and students are required to be in regularly if accepted in our org for SoC
* ''#wesnoth'' is a generic channel for the community
* ''#wesnoth-mp'' is a separate channel for multiplayer games and balancing

==== Does your organization have an application template you would like to see students use? If so, please provide it now.====
We plan mainly to meet potential students through our IRC channel, but the following questions are Wesnoth specific and are worth pondering for any student, even if we don't need a formal answer

* Basics
** Write a small introduction to yourself.
** State your preferred email address.
** If you have chosen a nick for IRC and Wesnoth forums, what is it?
** Why do you want to participate in summer of code?
** What are you studying, subject, level and school?

* Experience
** What programs/software have you worked on before?
** Have you developed software in a team environment before? (As opposed to hacking on something on your own)
** 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?
** What development model would you use (e.g. keywords: V-model, XP programming, agile programming, iterative; with the help of prototyping, formal specifications, tests, etc).
** Open Source
*** Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.
** Gaming experience
*** Are you a gamer? If so...
*** What type of gamer are you?
*** What type of games?
*** What type of opponents do you prefer?
*** Are you more interested in story or gameplay?
*** 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.

* Communication skills
** Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
** Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
** Do you give constructive advice?
** Do you receive advice well?
** Are you good at sorting useful criticisms from useless ones?

* Project
** Did you select a project from our list? If that is the case, what project did you select?
** If you have invented your own project, please describe the project and the scope.
** Why did you choose this project?
** Include an estimated timeline for your work on the project
** Include as much technical detail about your implementation as you can
** What do you expect to gain from this project?
** What would make you stay in the Wesnoth community after the conclusion of SOC?

* Practical considerations
** Are you familiar with any of the following tools?
*** Subversion (used for all commits)
*** C++ (language used for all the normal source code)
*** Python (optional, mainly used for tools)
*** build environments (eg cmake/autotools/scons)
** Which tools do you normally use for development? Why do you use them?
** What programming languages are you fluent in?
** What spoken languages are you fluent in?
** At what hours are you awake and when will you be able to be in IRC (please specify in UTC)
** Would you mind talking with your mentor on telephone / internet phone?

* Detailed answer (optional, but writing skill is a good predictor of ability to work on a programming team, so you will improve your chances by responding to this).
** Write a small essay (750-1000 words or more) explaining why you want to participate in a Wesnoth GSoC project. You can use the above questions as guides, but feel free to throw in more information if you feel it is relevant.
** What is your perception of 'open source'? Briefly explain what you think of the whole 'open source' concept, how you discovered open source, what you expect to gain/experience by participating in an open-source project. (Answer separately or as part of above mini-essay)
** What motivates or inspires you to write programs and develop software?

''''to be completed''''

==== Who will be your backup organization administrator? Please include Google Account information.====
David White (davewx7@gmail.com) -- Link ID: sirp

==== Who will your mentors be? Please include Google Account information.====

David White (davewx7@gmail.com)

Jeremy Rosen alias Boucman (boucman2|ATTT|gmail.com)

Mark de Wever aka Mordante (mordante.wesnoth|ATTT|gmail.com)

Jörg Hinrichs alias YogiHH (joerghh.hinrichs|ATTT|googlemail.com)

Patrick Parker a.k.a. "Sapient" (patrick.x99|ATTT|gmail.com)

==== What criteria did you use to select these individuals as mentors? Please be as specific as possible.====

Our first criterion was that all the people had to be volunteers. According to other open source projects, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Dave is the project leader and one of the most knowledgeable in C++. He has also written the Formula AI code which we plan to develop via the SoC. He is well known in our community for formulating simple but effective explanations for complicated topics, and has good design intuition. The growth of Wesnoth demonstrates his capacity to get other developers to work together and keep them involved in a thriving community.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the [http://wiki.wesnoth.org/UnsortedContrib Art Contribution] section of the wiki (now automated) and the [http://wiki.wesnoth.org/ReferenceWML WML Reference Manual]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org and has created the new developer process we currently use.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base.

YogiHH has been with the project for more than two years. He did a major refactoring to the gameplay engine and worked quite a bit on the multiplayer code. He also has been a professional trainer for C/C++, Java and C# for many years. Right now he works in a project where he serves as a mentor for a junior developer.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of people who to contact for which regards. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

==== What is your plan for dealing with disappearing students?====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensible about criticism and our community is used to people being sensible to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, his mentor will be in charge of recontacting him to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to him, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors?====

All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We took the time to ask other former GSoC projects about the workload needed to be a mentor, and our mentors accepted the job knowing the amount of work it involved.

However, should it happen, we would continue to mentor as a developer community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program?====

Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two patch... you're in" In other word, anybody that is able to get two non-trivial patches applied is offered commit privileges.

We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our [[EasyCoding]] pages (these project are usually a couple of hours long and has been chosen to provide easy access to code)

Usually, patches go back and forth a couple of time, to make sure that all secondary things are in place (indenting, coding style, modified makefiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to maintain our project alive.

If the student is proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can be rough at time.

==== What will you do to ensure that your accepted students stick with the project after GSoC concludes?====

Since our community has a history of having developers easily and quickly join, we expect the student to be a full-fledged developer quite fast (probably a little after the end of the bonding period).

Thus there will be no "end of GSoC" transition. At the end of the Summer of code we expect the student to be responsible for the part he developed, and to continue taking care of it, just as other developers are responsible for their part.

== See also ==
[[SummerOfCodeIdeas|Summer of Code Ideas]] - The root where all information regarding SoC is (or better should be) linked from.

[[Category:Summer of Code]]

SoC Ideas Multiplayer server

2009-02-15T19:38:24Z

Dave: /* General Description */

=== Extending the Multiplayer server ===

Our multiplayer community is generally strong and healthy, but we believe its growth is limited by some problems in the interface of the multiplayer lobby.

==== General Description ====
The general idea of this project would be
* To study the current lobby,
* To develop ideas about how our multiplayer interface could evolve to allow it to scale to a much larger community
* And to implement as many of those changes as practical

Some ideas that we had (but that are in no way mandatory):
* Having a simple way to register and authenticate nicknames, similar to what IRC offers. The point is not to have cryptographically safe logins, but to have something simple that gets the job done
* Having a simple room system? Again, inspired by IRC
* Having some way to find the type of games you are interested in. filtering by:
** game type
** number of free slots/players
** any other criteria you might find interesting

Other ideas we are not yet convinced are good, but that are certainly worth studying (especially how the communities based around these concepts are different from ours)
* ranking players
* guilds
* official tournaments
* titles for players
* metaservers
* game matching when players are ranked (poker, bridge...)

The scalability of the design (both in term of number of players, and in term of the possibility for players and developers to extend the concept) will be an important criterion.

Administration/moderation problems and techniques should also be studied.

Interaction with the Add-On server/forum should be explored.

An additional feature that could be considered is more secure random number generation to prevent cheating. At the moment, random numbers are generated on the client side. Things could be changed

==== Required knowledge and talent ====

* A fair amount of experience with C++ is required. Wesnoth uses some advanced C++ features and is heavily based on BOOST and SDL. We can train you in some of the libraries used, but learning all of them would be a big hurdle.
* Experience with multiplayer games, in order to have a good idea of what multiplayer lobbies of other game look like, and (more importantly) a good idea of the social behaviours of multiple MP communities, how teams are formed in games and things like that.

==== Milestones and deliverables ====

* A first milestone would be a presentation summarizing the different studies, and the proposed interface. preliminary informal stages would probably be desirable, to make sure the proposed idea is already a consensus within devs
** Study of other MP game-matching interfaces and functionalities
** Study of other MP communities
** Study of other MP moderation practices
** Study of the Wesnoth MP community, including needs, various opinions from different developers and players
* A second milestone would be the main code delivery. Code should be functional for it will be delivered in the next Wesnoth development release

=== See also ===
[[SummerOfCodeIdeas|Summer of Code Ideas]] - The root where all information regarding SoC is (or better should be) linked from.

[[Category:Summer of Code]]

SummerOfCodeIdeas

2009-02-15T19:36:26Z

Dave:

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== I want to be one of your Google Summer of Code students, what should I do... ==

Here is a quick list of things to do to get you started
* Create an account on gna.org
* Create an account on the wesnoth forum
* Join the irc channel (#wesnoth-dev on irc.freenode.net) and introduce yourself. We will not give formal interviews, but we will clearly favor people we have learnt to know during the selection process
* Contact one of our SummerOfCode people (Ivanovic, Sirp, Boucman, Mordante) to have your forum nick marked as a Summer of code student

* Start a wiki page about your idea, add a link on the bottom of this page and add this information on it:
** List your account names (gna, forum, irc nick) so that we can recognize you
** Fill the questionnaire on this page: [[SoC_Information_for_Google#Does_your_organization_have_an_application_template_you_would_like_to_see_students_use.3F_If_so.2C_please_provide_it_now.| List of questions to answer]]
** Detail your idea as much as possible, look at other students pages, and please give milestones and studies you've done

* Though not mandatory, it is highly advisable to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from. You can also implement some features from our feature request database at gna. When you implement something, also list it on your own page with a reference to the patch.

* For working on Wesnoth you have to be able to compile trunk. To do so you should have a look at the [[WesnothSVN|page about svn]] and afterwards [[CompilingWesnoth|compile Wesnoth svn]].

* Once you have everything done here and think your idea is okay, go to [http://groups.google.com/group/google-summer-of-code-announce/web/guide-to-the-gsoc-web-app-for-student-applicants to page at google] to submit your application. You have to submit it before '''Date to be supplied later''' or you have no chance to get in!

== List of Ideas for the Project (Suggestions from the wesnoth developers) ==

Here is only a short description of possible Ideas we have, each has a page of its own with a more detailed version on it.

=== Optimize implementation of WML for memory usage ===

Based on this idea: [http://dave.wesnoth.org/?p=9] optimize WML to minimize its memory usage. High memory usage has been a problem for Wesnoth, and this project will aim to reduce it.

=== Implement campaign statistics reports on stats.wesnoth.org ===

Wesnoth has an infrastructure which records details of campaigns that players play into a centralized MySQL database. However, we only have rudimentary reports based on this MySQL database available at this time, at [http://stats.wesnoth.org].

This project would involve writing a stats reporting web site which would take the data from the MySQL database and produce reports in chart and table form. Campaign designers would be able to use these reports to gather feedback on their campaigns and get ideas for improvements.

A student could largely make their choice of infrastructure for creating the Website -- whether they prefer Python, Perl, Ruby, PHP, etc. This is a great opportunity for someone who doesn't want to dive into hardcore C++ to make a valuable contribution to Wesnoth.

=== Writing an AI based on the formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth: [[FormulaAI]]

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately, because the skills required to understand and modify it are rather arcane, it is also one of the most neglected parts of the Wesnoth code. This is a place where a lot of research and useful work could be done. But keep in mind that [[WhyWritingAWesnothAIIsHard|writing an AI for Wesnoth is difficult]].

[[SoC Ideas FormulaAI]] - Full version of the idea, with detailed information

=== Extending the Multiplayer server ===

Our multiplayer community is generally strong and healthy, but we believe its growth is limited by some problems in the interface of the multiplayer lobby.

[[SoC Ideas Multiplayer server]] - Full version of the idea, with detailed information

=== Scenario/Campaign editor ===

Currently, in order to create campaign or multiplayer scenarios, it is necessary to manually edit WML files - XML-like configuration files. The goal of this project would be to create a graphical editor to make the creative process easier.

[[SoC Ideas Scenario and Campaign Editor]] - Full version of the idea, with detailed information

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user-made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

[[SoC Ideas Addon Server]] - Full version of the idea, with detailed information

=== Map editor ===
The map editor in Wesnoth serves two goals, making it easy to create
a new map and helping the terrain artists to test their new terrains.

[[SoC_Ideas_Map_Editor]] - Full version of the idea, with detailed information

=== Other possible ideas to be fleshed out ===
A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the cave generator) etc.

=== Make your own ideas ===
If you have your own idea the best thing is to join IRC wesnoth-dev at irc.freenode.net and discuss the idea with the developers there. If the developers think your idea is interesting and like the feature you can start to turn it into a full proposal. Once done discuss it again on IRC so the developers can accept your idea.

== Information about our Project ==
The information we provided google with about our project can be looked up at the site [[SoC Information for Google]].

Also see the [[DeveloperResources]] link (from the [[Project]] page).

== People to bug on IRC ==
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

[[SoC People to bug on IRC]]

== GSoC Student Applicant Ideas ==

Every student interested to work on Wesnoth as part of Summer of Code should create a page of his own where several things should be listed. Here is a short list of what should be mentioned on the list (the more info for us, the better...):

* Who are you? Please list your IRC and forum nickname in here and describe yourself so that we get you to know.
* What do you want to work on? Please flesh out your personal ideas, so that we get to know what you plan to work on.
* If you already submitted patches, please list those so that we have a reference.

[[Category:Summer of Code|*]]

Wesnoth1.6Features

2008-11-10T20:10:29Z

Dave:

== Mordante ==
=== Will complete ===
* Add new dialog to show the transparent portraits Kitty made.
* Improvement to gold carry over (https://gna.org/bugs/?12227).
* UI sounds for the new widgets.
* Popups for new widgets.
* Improve campaign selection dialog (http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=497655)

=== Wants to complete ===
* Finish the new widgets (Won't be done before 1.6)
* Open bugs assigned to me

=== Hopes to complete ===
* Open FRs assigned to me

== Sapient ==
=== Wants to complete ===
* Allow math to be used in any WML tag (http://www.wesnoth.org/forum/viewtopic.php?p=317204#p317204)

== zookeeper ==
=== Wants to complete ===
* Finalizing the gold carryover changes in mainline campaigns (as long as the maintainer doesn't oppose it, naturally) and rebalancing accordingly.
* Implementing a final version of the ai controller, and then deciding whether we want to use it across all/most the mainline campaigns or not.

== esr ==
=== Am Done With ===
* Substantive changes to existing mainline campaigns. As far as I am concerned, existing mainline WML could freeze for translation in 7 days (e.g. 9 Nov).
* I have no C++ core features planned for 1.6.
=== Will complete ===
* Custom music lists for all mainline scenarios that don't already have them

=== Wants to complete ===
* Mainlining Delfador's Memoirs
=== Hopes to complete ===
* Get the bug count below 30

== David ==

=== Am Done With ===
* Fix bugs which make AI unplayable

=== Wants to complete ===
* New stats system
* Sophisticated rooms system on mp server

== BUGS / features that we would like to address ==
* The AI mess (https://mail.gna.org/public/wesnoth-dev/2008-10/msg00077.html)
** Update: Fixed by Sirp
* spawned/recruited Unit ID's in WML are no longer unique
** Update: Fixed by Sapient in r30685
* Multiplayer OOS / Replay corruption (https://mail.gna.org/public/wesnoth-dev/2008-10/msg00080.html)
* all the rest.

[[Category:Development]]

WhyWritingAWesnothAIIsHard

2008-03-19T19:41:14Z

Dave: New page: = Why Writing a Wesnoth AI is Hard = == Overview == I'm largely writing this in response to the number of people who have historically wanted to write a Wesnoth AI, as well as the number...

= Why Writing a Wesnoth AI is Hard =

== Overview ==

I'm largely writing this in response to the number of people who have historically wanted to write a Wesnoth AI, as well as the number of students who are interested in developing an AI for Wesnoth as part of Summer of Code.

Having an AI for Wesnoth is very useful, but one shouldn't underestimate its difficulty. Most traditional AI methods cannot be applied to Wesnoth, so it is necessary to use highly innovative solutions.

Many people think that a very powerful AI for Wesnoth should be fairly easy. After all, computers can beat the world's best players in chess and backgammon, both of which are turned based games, so why not Wesnoth? This document will give an overview of why techniques used in chess and backgammon will not be near as successful in Wesnoth.

== Wesnoth's flexibility hurts us ==

Wesnoth is very flexible. There are many different maps, of different sizes, and different units. Players can even add their own units. This makes it much more difficult to make a general AI.

Computers are very good at chess because chess is played on a relatively small board, that is always the same, and the pieces always start in the same position. This means there are a relatively limited set of positions that the computer has to deal with, and in particular, the types of positions a computer has to deal with are very limited. Patterns such as three consecutive pawns in front of a castled king are common in chess, and so it is relatively easy for a chess evaluation engine to recognize such patterns and evaluate their strength.

Wesnoth is much different. To even compare Wesnoth with chess, you would have to consider a chess program written for a chess game where the board can be any size and shape. It could have impassable squares in the middle. It could have corners that are inaccessible and so forth. Additionally, players could have various 'fantasy pieces' which are defined according to complex rules. Pieces that move like knights, but with extra steps. Pieces that can move likes knights and like bishops, and so forth.

Such a program would not play near as well against skilled humans. Humans could adapt to the new pieces far more readily than a computer program can.

But that still doesn't begin to approach the complexity of Wesnoth. Wesnoth has uncertain information, and random outcomes. Chess programs rely heavily on chess's deterministic nature. Wesnoth is more like backgammon in this way: you don't know what the outcome will be. But, backgammon has a tiny state space, while Wesnoth has a huge one.

== Wesnoth's computational complexity ==

The computational complexity of Wesnoth is immense compared to board games such as chess, backgammon, shogi, and go.

If one considers a 30x20 map -- a typical size for a Wesnoth map -- and one considers 16 standard terrain types. This can be represented in 2400 bits of data. There are thus 2^2400 possible maps of this size. This is without even considering the many combinations of units that can be on the map, in different locations, in different states of health, and so forth. The number of possible positions is truly immense. The state space of Wesnoth certainly easily exceeds 10^1000, and probably 10^10000.

This dwarfs the complexity of even Go, which has a state space complexity of 'only' around 10^171.

The branching factor of Wesnoth is also huge. In most traditional board games, where much computational analysis has been done, typically a player moves one piece, then the other player moves a piece. In Wesnoth, one moves all their pieces, before the other player moves. Wesnoth also typically has many options as to where one can move a piece. It is not uncommon for a piece to have 20 or more tiles it can move to, and for a player to have a dozen or more pieces. Pieces can also choose to attack, and have a choice of weapon to attack with, and so forth. When an attack does occur, there are many possible results, based on number of strikes that land.

The branching factor of Wesnoth is thus also huge. The game tree complexity of Wesnoth is incalculably large. Thinking ahead many moves is difficult.

== Wesnoth as a fuzzy game ==

Discrete analysis fails badly on Wesnoth because, though technically Wesnoth is a discrete game, there are so many positions that discrete analysis techniques fail.

Fortunately, Wesnoth can be treated much like a continuous game, because many positions tend to be very similar to each other. Additionally, unlike discrete board games, it is not common that a very small wrong move in Wesnoth is disastrous.

WritingYourOwnAI

2008-03-19T18:28:49Z

Dave: /* Writing your own AI */

== Writing your own AI ==

Wesnoth supports a pluggable AI system that allows programmers to write their own AIs in C++ or Python.
You might like to look this over before starting: [[WhyWritingAWesnothAIIsHard]]

== Python ==

For information on the Python AI API look at [[ReferencePythonAPI]].

== C++ ==

The rest of this page describes the C++ AI API. To write an AI in C++, you need to derive a class from ''ai_interface'' (defined in '''ai.hpp'''), and implement the function ''play_turn()'' which will be called every time your AI is expected to play a turn.

Class ''ai_interface'' contains three important functions
which allow you to execute the three basic types of move available in the game:

* ''attack_enemy()'', which is used to order an attack on an enemy unit,
* ''move_unit()'', which is used to order a unit to move from one location to another, and
* ''recruit()'', which is used to recruit a new unit.

Of course, to decide where units are to move and attack, you must have information about the state of the game - the dimensions and layout of the map, the locations and type of units on the map, the types of units your side can recruit, and information about your allies and enemies.

Firstly, a type ''location'' is defined, which defines any location on the map. It has members ''x'' and ''y''. In '''pathfind.hpp''' there are a number of functions which will tell you useful things about locations -- whether two locations
are adjacent, all the locations adjacent to a certain location,
and the distance between locations.

A type ''move_map'' is defined as a ''std::multimap<location,location>''. Note that ''std::multimap'' is of course a standard C++ container, and cannot be documented here. http://www.sgi.com/tech/stl/ is a good reference on standard C++ containers. The purpose of a ''move_map'' is to show all the possible moves for a side. It can either be a ''source -> destination'' map, which associates the locations of all the units a side has to all the possible places they can move to, or a ''destination -> source'' map, which associates all the locations all the units a side has can get to, to all the places they are now.

The function ''calculate_possible_moves()'' is provided
as a useful utility function. It can give you maps for where all
your units can move, or where all your enemy's movements
can move when it's their turn. This is a very important
function to use to work out all the possible places your units can move to.

''ai_interface'' also defines an ''info'' type. This type contains a number of references to various game objects which you
will need access to in order to make moves. The two most important of these objects are the unit map (unit_map units)
and the game map (gamemap map).

The unit map is of type ''std::map<location,unit>''
and associates locations with units. This object can be used to find the location of, and information about, every unit on the board. See '''unit.hpp''' for a definition of the ''unit'' object.

The game map allows you to inspect the dimensions and layout of the playing board. Given a location, it can tell you the
terrain type at that location. See '''map.hpp''' for a definition of this object. You can combine this class with use of the functions in '''pathfind.hpp''' to find various
information about where units can move to.

The team class (defined in '''team.hpp''') is also very important. Each side is represented by a ''team'' object. The team object can tell you the gold balance of a team, which villages (note that internally, villages are often called 'towers') the team owns, what units the team can recruit,
and which other teams are this teams friends or enemies.

The utility function ''current_team()'' can be used to get a reference to the team that your AI is in control of, but you
can also use the vector ''teams'' inside the info object to get a list of all teams.

If you want to make your AI customizable within the configuration file, you can gain access to any parameters passed to your AI using ''team::ai_parameters()''. This returns an object of type ''config'' (see '''config.hpp'''). These ''config'' objects are representations of WML document fragments. When the user defines your side, if they put an [ai] tag inside it, everything inside the [ai] tag will be returned by ''team::ai_parameters()''.

== Using your AI ==

Finally, when you have your AI ready to go, you can add it to the ''create_ai()'' function in '''ai.cpp'''. Suppose you called your class ''killer_ai'', you could add it like so:

if(name == "killer_ai")
return new killer_ai(info);

Then, you can define a side to use your AI in [[ReferenceWML|WML]]:

ai_algorithm=killer_ai

and when that side is created, it'll use your AI!

== An example ==

Let us conclude with a small sample AI, called ''sample_ai''. How should this AI behave?

* First it should detect if there are any enemies in range,
and if there are it should attack them by moving onto the
best defensive terrain next to them. Attacks should be made with the weapon for which damage*strikes*chance to hit is
the highest.
* If there are no enemies in range, it should move units onto villages that don't already belong to it.
* If there are no enemies or villages in range, it should move toward the enemy leader along the shortest possible route.
* At the end of its turn, it should recruit random units until it runs out of money or doesn't have any space.

In the following example, I will place all functions in-line
rather than in the cpp file. To do this properly, of course you should put them in the cpp file. The entire definition of this AI can be found in '''ai.cpp''' and '''ai.hpp''' in the source distribution.

We start the definition,

class sample_ai : public ai_interface {
public:
sample_ai(info& i) : ai_interface(i) {}

We have defined the constructor which takes an ''info'' object
and passes it straight onto ai_interface. We don't need to
store anything ourselves in this simple AI. (Although it would be fine to have data members if we wanted them.)

Next we define the main function, ''play_turn()'':

void play_turn() {
do_attacks();
get_villages();
do_moves();
do_recruitment();
}

Just a series of calls to functions we are about to write which do the actual work. Firstly, ''do_attacks()''. We start by
calculating all the moves our units can make:

private:
void do_attacks() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Note that the ''possible_moves'' thing is of little direct interest. It contains details of exactly which tiles the unit
moves along to get from one tile to another. This is useful for the display to know about when it draws the unit moving, but as an AI programmer, it's not likely you'll ever care about
what it contains. Just pass it along to the ''move_unit()'' function so it can draw the unit moving along the correct path.

The things we're interested in are ''srcdst'', and especially ''dstsrc'', which will tell us all the hexes our units can reach.
We want to check if any of these hexes are next to an enemy unit. Let's walk over the units and see if we can reach any of them:

for(unit_map::const_iterator i = get_info().units.begin(); i != get_info().units.end(); ++i) {
if(current_team().is_enemy(i->second.side()) {

We're iterating over all units, but we're only interested in units that are enemies of our side. So, we access our team object, and ask if the side the unit is on is an enemy. If it is, then we're interested in seeing if any of our units can move to a hex that's adjacent to the enemy unit. We do this by getting the six locations around the enemy unit:

location adjacent_tiles[6];
get_adjacent_tiles(i->first,adjacent_tiles);

This kind of call is very common in the game's code -- make an array of 6 locations, and fill them up with the locations adjacent to a certain location. We actually want to find the position to attack from which gives our unit the best possible defense. So, we initialize some variables to find the best possible defense:

int best_defense = -1;
std::pair<location,location> best_movement;

The value of ''best_defense'' will of course be between 1 and 100, but we give it a value of -1 to mean 'not initialized', since we haven't found any possible attacks at all yet. Variable ''best_movement'' will contain the destination/source pair that gives the best possible defense for our attacking unit.

for(size_t n = 0; n != 6; ++n) {
typedef move_map::const_iterator Itor;
std::pair<Itor,Itor> range = dstsrc.equal_range(adjacent_tiles[n]);

If you don't understand how ''equal_range'' works, then look up documentation on how the standard container multimap works. ''range'' now refers to all the possible movements that can end
with our unit being at ''adjacent_tiles[n]''. Let's iterate over all those movements, and find if any of them give a better defensive rating than our current best defense. We'll start our iteration by creating some aliases that ensure we don't go crazy ;)

while(range.first != range.second) {
const location& dst = range.first->first;
const location& src = range.first->second;

Now let's find out about the unit that we're planning to send to this destination:

const unit_map::const_iterator un = get_info().units.find(src);
assert(un != get_info().units.end());

We can assume that the unit is in that location (hence the assert), because ''calculate_possible_moves()'' said that it's the possible source of a move. Let's find out the type of terrain we're planning to move to:

const gamemap::TERRAIN terrain = get_info().map.get_terrain(dst);

Okay, so we have the unit, and we have the terrain, now we should be able to find out the unit's defensive rating on this terrain.
The ''unit'' class has a convenient ''defense_modifier()'' function which will tell us the chance of hitting that unit on a certain terrain.

const int chance_to_hit = un->second.defense_modifier(get_info().map,terrain);

So, now we have all that, if it's the best chance to hit we've seen so far, or we haven't seen any other chances to hit at all, then we add it as our best option seen.

if(best_defense == -1 || chance_to_hit < best_defense) {
best_defense = chance_to_hit;
best_movement = *range.first;
}

That's it for these two loops. Iterate and close:

++range.first;
}
}

Now if we found a possible move, best_defense will not be -1,
and the movement will be stored in ''best_movement''. So, if ''best_defense'' is -1, we want to move from ''best_movement.second'' to ''best_movement.first''.

if(best_defense != -1) {
move_unit(best_movement.second,best_movement.first,possible_moves);

Remember that ''possible_moves'' thing? That comes in useful here, where we have to give it to the display object so it can know the path to move the unit along. This is the only time we need to touch it.

Immediately after moving, we want to attack. First we need to know which weapon to use. We'll write a ''choose_weapon()''
function later which will choose our weapon. It'll have to take the location of the attacker and the location of the defender, and it'll return an int referring to our weapon of choice. For now we'll just make use of this function:

const int weapon = choose_weapon(best_movement.first,i->first);
attack_enemy(best_movement.first,i->first,weapon);

This will implement our attack. What now? We've attacked once, but we want to attack with as many units as we can attack with, right? We can't use the same move_maps again, because they'll be invalid now that we've moved and attacked. What we'll do is we'll call ''do_attacks()'' all over again, recursively, and return immediately. This way all our maps will be recalculated.

do_attacks();
return;
}
}
}
}

That's the entire function done. It'll keep attacking while it finds attacks, and when it finally runs out of attacks to execute, it'll return nicely. Let's write that ''choose_weapon()'' function now:

int choose_weapon(const location& attacker, const location& defender) {
const unit_map::const_iterator att = get_info().units.find(attacker);
assert(att != get_info().units.end());

const std::vector<a ttack_type>& attacks = att->second.attacks();

unit contains a convenient ''attacks()'' function which returns a vector of all a unit's possible attacks. We'll store the
best attack found so far, and iterate over all attacks:

int best_attack_rating = -1;
int best_attack = -1;
for(int n = 0; n != attacks.size(); ++n) {

There is a nice function called ''evaluate_battle_stats()'' in '''actions.hpp''' which will give us all sorts of information about a potential battle. We make use of it here:

const battle_stats stats = evaluate_battle_stats(get_info().map,
attacker, defender, n, get_info().units,
get_info().state, get_info().gameinfo, 0, false);

A rather complicated function call, but most of the parameters can be pulled straight from ''get_info()''. The last two parameters are a little confusing. The first one of these, ''attacker_terrain_override'', is used if we wanted to know what the combat would look like if the attacker was on different terrain to what it is on now. If this is non-0, the function will assume the attacker is on the type of terrain given. This is useful if you want to test the possibility of moving to many different hexes without actually moving there. The last parameter is false, meaning that strings won't be included in the results. Strings are useful for showing to a player in a dialog,
but not useful for an AI, and are expensive to calculate, so this should always be false from within AI algorithms.

Let's use our stats to come up with a rating for this attack:

const int attack_rating = stats.damage_defender_takes*stats.nattacks*stats.chance_to_hit_defender;

Now if this is the best attack, we can use it,

if(best_attack == -1 || attack_rating > best_attack_rating) {
best_attack = n;
best_attack_rating = attack_rating;
}
}

return best_attack;
}

Now we're done with that, we can move onto our ''get_villages()'' function. We start off by calculating possible moves,

void get_villages() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Now it's a simple matter of iterating over possible destinations,
and seeing if they are villages not controlled by us:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
if(get_info().map.is_village(i->first) &&
current_team().owns_village(i->first) == false) {

First it checks whether the destination is a village. The right side of the ''&&'' simply sees if our team owns the village at that location or not. If we don't own the village, we've found the movement we want to make, and we recurse and return.

move_unit(i->second,i->first,possible_moves);
get_villages();
return;
}
}
}

Just a couple more functions now. Firstly, ''do_moves()'' is meant to move our units toward the enemy leader. Well, there may be multiple enemies and thus more than one leader, so we'll just go for the first enemy leader we can find. We start off by trying to find the enemy leader:

void move_units() {
unit_map::const_iterator leader;
for(leader = get_info().units.begin(); leader != get_info().units.end(); ++leader) {

A unit is a leader if it can recruit -- so we use the ''can_recruit()'' function to test if it's a leader.

if(leader->second.can_recruit() && current_team().is_enemy(leader->second.side())) {
break;
}
}

We better have found an enemy leader, otherwise we'll just return...

if(leader == get_info().units.end())
return;

Now, let's find all our unit's possible moves:

std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

We want to find the move that'll take us as close as possible to the enemy leader. Let's make our variables to show us the best move so far,

int closest_distance = -1;
std::pair<location,location> closest_move;

Now iterate and find the destination closest to the enemy leader:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
const int distance = distance_between(i->first,leader->first);
if(closest_distance == -1 || distance < closest_distance) {
closest_distance = distance;
closest_move = *i;
}
}

If ''closest_distance'' is not -1, we've found a valid move that'll take one of our units toward the enemy leader. We can make the move and recurse

if(closest_distance != -1) {
move_unit(closest_move.second,closest_move.first,possible_moves);
do_moves();
}
}

Okay, all our movement functions are done! Now all we've got left is the recruitment function. We start by getting the units that we can recruit.

void do_recruitment() {
const std::set<std::string>& options = current_team().recruits();

We can choose the number of a unit to recruit at random:

const int choice = (rand()%options.size());
std::set<std::string>::const_iterator i = options.begin();
std::advance(i,choice);
const bool res = recruit(*i);

And if the recruitment succeeds, we will try to recruit another unit,

if(res) {
do_recruitment();
}
}
};

That's it! We've made our ''sample_ai''. All we have to do is add it to ''create_ai'' in '''ai.cpp''' and we're done!

== AI - specific parameters ==

wesnoth --multiplayer --controller1=ai --controller2=ai --algorithm1=z_ai --algorithm2=sample_ai

Use the ''--nogui'' switch before ''--multiplayer'' to make the game run without displaying a GUI. The winner will be reported on stdout.

== See Also ==

* [[DeveloperResources]]
* [[PythonTestScript]] - Simple Python AI test script

[[Category:Create]]

WesnothdDesign

2008-03-19T01:59:04Z

Dave: /* The string_span class */

= Wesnothd Design =

== Overview ==

This page documents the design of wesnothd, Wesnoth's multiplayer server. This document was written after I (Dave) re-designed wesnothd to try and make it more efficient.

Wesnothd is a network server written in C++. It shares some of Wesnoth's code, in particular the networking code. Wesnothd manages requests from Wesnoth, that are sent in WML. It manages a lobby of players who can chat with each other, create games, join games, observe games, and so forth. Wesnothd maintains a list of games, users, and so forth. Wesnothd largely operates by relaying messages to the appropriate clients. For instance, if a player in a game makes a move, wesnothd will relay this to all clients who are participating in the game. Wesnothd may also perform appropriate filtering and so forth, and allows administrators to administer a game by kicking or banning users and so forth.

== simple_wml ==

Wesnothd originally used the same WML module, the config object, and serialization code as Wesnoth. This allowed code reuse and easy interoperability. However, Wesnoth's WML module is designed for ease of use by coders, and supports rich functionality, parsing user-written WML. This approach proved to be inefficient for wesnothd. config objects store all name/value pairs in attributes and element names as std::string objects. This typically means a dynamically allocated buffer for each and every name and value and element name. This leads to slow parsing as well as high memory use.

Since wesnothd uses WML in a relatively limited way, a specialized WML parser and in-memory representation was developed, called simple_wml. Simple_wml can parse only a subset of WML: it assumes that all attribute values are surrounded by quotes, and that attributes are in lexicographical (alphabetical) order. This allows very quick parsing.

Additionally, the in-memory representation has some limitations. It cannot perform near the same number of operations as config objects can.

=== Documents vs nodes ===

A config object is both a WML document and a node within a document. Simple_wml is different: there is a document object and a node object. A document automatically has a root node, and a node may create child nodes. Nodes may not be transferred between documents (except by swapping documents; see below).

Nodes all track their parents, as well as the document that owns them. This approach allows for several important optimizations.

=== The string_span class ===

Simple_wml defines a string_span class. A string_span is a portion of a string: a pointer to a buffer, and the size of the buffer. A string_span is not seen as owning the string it points into. Rather, it is an immutable 'view' of a part of a string.

All attribute names and values and element names in simple_wml nodes are stored as string_spans. This often allows allocation to be minimized or avoided.

=== Ownership semantics ===

A document contains a vector with a list of all buffers it is considered to 'own'. These are buffers its nodes depend on (i.e. string_spans within the nodes refer to within these buffers). When the document is destroyed it will free these buffers.

A document may be constructed by a text buffer or a gzip compressed buffer. The caller may transfer control of the buffer to the document. If it does not, the document will make a copy of the buffer. If the buffer is compressed, the document will make an uncompressed version. The buffer will be added as an owned buffer.

The document will then parse the text buffer, creating nodes. All the nodes will initialize their string_spans for element and attribute values pointing into the text buffer being parsed.

This means that when a WML document is parsed, it will only allocate the node objects. All strings will simply point into the buffer for the document.

Of course, nodes within a WML document might be modified programmatically. Nodes have several methods for setting an attribute, which each have different ownership semantics for the buffers being set:

set_attr(const char* name, const char* value): this function will take two C-style strings, and refer to them with string_spans. The strings are NOT copied. Rather, it is the responsibility of the caller to ensure that these buffers will remain valid throughout the lifetime of the document. This is most often ensured by using data in static memory as input. For instance, you might call some_node.set_attr("has_object, "1"); Because you pass string literals in, you know the memory is guaranteed to be valid through the life of the program.

This method is very efficient, since no allocation takes place

set_attr_dup(const char* name, const char* value): this function will take two C-style strings. The name will be treated as in set_attr, but a copy will be made of the value. The buffer the copy is made in will be stored as an owned buffer of the document, and so will be destroyed when the document is destroyed.

A copy of the name is not made, since having a dynamically generated name is not common, and usually one can use a string literal.

set_attr_dup_name_and_value(const char* name, const char* value): This function works as above, but duplicates both the name and value.

set_child(const char* name): this function creates a new child node and returns a reference to it. The name will be treated as in set_attr(), with no copy being made; it should be in static memory.

It is also possible to duplicate a buffer and make it owned by the document manually. The document class contains a dup_string() method which duplicates a string buffer and stores it as owned by the document.

=== Cool simple_wml optimizations ===

Simple_wml allows for some very nice optimizations. When a document is constructed by parsing, every node contains a string_span referring to the portion of the buffer that it was parsed from. Every node also keeps track of whether it has been modified since parsing or not. When a node is modified, it walks up its parents and marks each one as 'dirty' -- i.e. modified.

When a simple_wml document is output, it will look and see if the root node is dirty. If the root node is not dirty, then the document has not been modified since parsing. We still have access to the buffer that the document was parsed from, so we can simply spit it back out, and do no work in emitting the document.

Additionally, each node contains the portion of the buffer it was parsed from. If the document was modified, then nodes that are dirty will output themselves, but nodes that are not dirty will simply output the portion of the buffer they were parsed from.

Also, when outputting, we generate a full, compact text document. The string_spans in the nodes will, after outputting themselves to the output buffer, be reassigned to point into the output buffer, instead of where they were pointing before. This means that after output is complete, all of our string_spans will be pointing into the output buffer. This means that all other buffers are no longer needed, and will be released by the document.

A simple_wml document can also be queried for its compressed (gzipped) form, ready for sending over the network. If it is parsed from a gzipped buffer, it will keep a reference to this. If the document is not dirty, it will return this gzipped buffer. If it does not have the buffer, or is dirty, then it will generate the text output, compress it, and also cache the gzipped version.

Documents support a compress operation which will store a gzipped buffer of the document, and delete the text buffer and all the nodes and any other buffers. The document will automatically re-construct the nodes if the root node is ever queried for in code. This is very useful if one wants to store a document and perhaps transmit it over the network but it's unlikely that further operations will be performend on the document.

Documents support a swap() operation that allows the contents of two documents to be swapped. This is relatively inexpensive since it simply twiddles pointers. It is very useful, for instance, to populate a long-held document containing level data for a game with the game's definition sent by a client.

This all implies that simple_wml is very efficient at being used to store WML portions sent by clients, and then re-transmit to other clients.

=== simple_wml vs regular WML ===

Performance tests show simple_wml to be MUCH faster than WML used in Wesnoth. Parsing a WML document is between 10 and 30 times faster with simple_wml. Of course, benefits of simple_wml include smart optimizations to try and avoid parsing and outputting at all when unnecessary.

It should be noted though that simple_wml is 'simple' in that it is a stripped down, simplified version of WML. It itself is NOT 'simple' to use, and should never be considered for use in main Wesnoth code. It is very complicated to use, and should not be touched at all except by experienced C++ developers.

== The network layer ==

The Wesnoth network layer originally transmitted only config objects. One called send_data with a config object, and the network layer would serialize it and send it to the given socket. Unfortunately this is rather inefficient from a server's perspective, not least because it means that the config object will have to be serialized and compressed for each client. Additionally, of course, it ties one to config objects.

The network layer was thus given additional 'raw' send functions, which allow one to send a raw buffer. Wesnothd uses this to get the gzipped version of documents and send them. Additionally, a flag was added to the network layer to make it receive in 'raw' mode too, allowing one to get a vector<char> containing a buffer which would then be used to construct a simple_wml document.

=== Sharding the network layer ===

The network layer was also refactored to make it scale better. The network layer uses blocking socket operations to send and receive data. Of course, it is intractable for the server to block when communicating with a client, so these operations are performed in worker threads. When one sends data, one places the data in a queue and sends a signal to a worker thread which wakes up and processes the queue. A pool of worker threads operate on the queue. Similarly this pool of threads handles incoming requests, using select() to block until data is available.

This approach created performance problems with the queue that would have to be accessed from the main thread and from this pool of worker threads. A mutex would have to be locked, and many times threads would block on this mutex, all having to access the same queue.

This problem was alleviated by sharding the system: A #define NUM_SHARDS was introduced. The recommended value for this macro is 7 when compiling wesnothd. Instead of one queue and mutex, an array of NUM_SHARDS queues and mutexes is kept. Every socket is hashed into one of these shards based on its memory address. There are also NUM_SHARDS pools of worker threads available. When the main thread queues data, it only has to lock the mutex for the shard it is accessing, meaning worker threads on other shards are not blocked. Similarly for receiving data. This greatly reduces contention amongst threads.

WesnothdDesign

2008-03-19T01:54:27Z

Dave:

= Wesnothd Design =

== Overview ==

This page documents the design of wesnothd, Wesnoth's multiplayer server. This document was written after I (Dave) re-designed wesnothd to try and make it more efficient.

Wesnothd is a network server written in C++. It shares some of Wesnoth's code, in particular the networking code. Wesnothd manages requests from Wesnoth, that are sent in WML. It manages a lobby of players who can chat with each other, create games, join games, observe games, and so forth. Wesnothd maintains a list of games, users, and so forth. Wesnothd largely operates by relaying messages to the appropriate clients. For instance, if a player in a game makes a move, wesnothd will relay this to all clients who are participating in the game. Wesnothd may also perform appropriate filtering and so forth, and allows administrators to administer a game by kicking or banning users and so forth.

== simple_wml ==

Wesnothd originally used the same WML module, the config object, and serialization code as Wesnoth. This allowed code reuse and easy interoperability. However, Wesnoth's WML module is designed for ease of use by coders, and supports rich functionality, parsing user-written WML. This approach proved to be inefficient for wesnothd. config objects store all name/value pairs in attributes and element names as std::string objects. This typically means a dynamically allocated buffer for each and every name and value and element name. This leads to slow parsing as well as high memory use.

Since wesnothd uses WML in a relatively limited way, a specialized WML parser and in-memory representation was developed, called simple_wml. Simple_wml can parse only a subset of WML: it assumes that all attribute values are surrounded by quotes, and that attributes are in lexicographical (alphabetical) order. This allows very quick parsing.

Additionally, the in-memory representation has some limitations. It cannot perform near the same number of operations as config objects can.

=== Documents vs nodes ===

A config object is both a WML document and a node within a document. Simple_wml is different: there is a document object and a node object. A document automatically has a root node, and a node may create child nodes. Nodes may not be transferred between documents (except by swapping documents; see below).

Nodes all track their parents, as well as the document that owns them. This approach allows for several important optimizations.

=== The string_span class ===

Simple_wml defines a string_span class. A string_span is a portion of a string: a pointer to a buffer, and the size of the buffer. A string_span is not seen as owning the string it points into. Rather, it is an immutable 'view' of a part of a string.

All attributes and names in simple_wml nodes are stored as string_spans. This often allows allocation to be minimized or avoided.

=== Ownership semantics ===

A document contains a vector with a list of all buffers it is considered to 'own'. These are buffers its nodes depend on (i.e. string_spans within the nodes refer to within these buffers). When the document is destroyed it will free these buffers.

A document may be constructed by a text buffer or a gzip compressed buffer. The caller may transfer control of the buffer to the document. If it does not, the document will make a copy of the buffer. If the buffer is compressed, the document will make an uncompressed version. The buffer will be added as an owned buffer.

The document will then parse the text buffer, creating nodes. All the nodes will initialize their string_spans for element and attribute values pointing into the text buffer being parsed.

This means that when a WML document is parsed, it will only allocate the node objects. All strings will simply point into the buffer for the document.

Of course, nodes within a WML document might be modified programmatically. Nodes have several methods for setting an attribute, which each have different ownership semantics for the buffers being set:

set_attr(const char* name, const char* value): this function will take two C-style strings, and refer to them with string_spans. The strings are NOT copied. Rather, it is the responsibility of the caller to ensure that these buffers will remain valid throughout the lifetime of the document. This is most often ensured by using data in static memory as input. For instance, you might call some_node.set_attr("has_object, "1"); Because you pass string literals in, you know the memory is guaranteed to be valid through the life of the program.

This method is very efficient, since no allocation takes place

set_attr_dup(const char* name, const char* value): this function will take two C-style strings. The name will be treated as in set_attr, but a copy will be made of the value. The buffer the copy is made in will be stored as an owned buffer of the document, and so will be destroyed when the document is destroyed.

A copy of the name is not made, since having a dynamically generated name is not common, and usually one can use a string literal.

set_attr_dup_name_and_value(const char* name, const char* value): This function works as above, but duplicates both the name and value.

set_child(const char* name): this function creates a new child node and returns a reference to it. The name will be treated as in set_attr(), with no copy being made; it should be in static memory.

It is also possible to duplicate a buffer and make it owned by the document manually. The document class contains a dup_string() method which duplicates a string buffer and stores it as owned by the document.

=== Cool simple_wml optimizations ===

Simple_wml allows for some very nice optimizations. When a document is constructed by parsing, every node contains a string_span referring to the portion of the buffer that it was parsed from. Every node also keeps track of whether it has been modified since parsing or not. When a node is modified, it walks up its parents and marks each one as 'dirty' -- i.e. modified.

When a simple_wml document is output, it will look and see if the root node is dirty. If the root node is not dirty, then the document has not been modified since parsing. We still have access to the buffer that the document was parsed from, so we can simply spit it back out, and do no work in emitting the document.

Additionally, each node contains the portion of the buffer it was parsed from. If the document was modified, then nodes that are dirty will output themselves, but nodes that are not dirty will simply output the portion of the buffer they were parsed from.

Also, when outputting, we generate a full, compact text document. The string_spans in the nodes will, after outputting themselves to the output buffer, be reassigned to point into the output buffer, instead of where they were pointing before. This means that after output is complete, all of our string_spans will be pointing into the output buffer. This means that all other buffers are no longer needed, and will be released by the document.

A simple_wml document can also be queried for its compressed (gzipped) form, ready for sending over the network. If it is parsed from a gzipped buffer, it will keep a reference to this. If the document is not dirty, it will return this gzipped buffer. If it does not have the buffer, or is dirty, then it will generate the text output, compress it, and also cache the gzipped version.

Documents support a compress operation which will store a gzipped buffer of the document, and delete the text buffer and all the nodes and any other buffers. The document will automatically re-construct the nodes if the root node is ever queried for in code. This is very useful if one wants to store a document and perhaps transmit it over the network but it's unlikely that further operations will be performend on the document.

Documents support a swap() operation that allows the contents of two documents to be swapped. This is relatively inexpensive since it simply twiddles pointers. It is very useful, for instance, to populate a long-held document containing level data for a game with the game's definition sent by a client.

This all implies that simple_wml is very efficient at being used to store WML portions sent by clients, and then re-transmit to other clients.

=== simple_wml vs regular WML ===

Performance tests show simple_wml to be MUCH faster than WML used in Wesnoth. Parsing a WML document is between 10 and 30 times faster with simple_wml. Of course, benefits of simple_wml include smart optimizations to try and avoid parsing and outputting at all when unnecessary.

It should be noted though that simple_wml is 'simple' in that it is a stripped down, simplified version of WML. It itself is NOT 'simple' to use, and should never be considered for use in main Wesnoth code. It is very complicated to use, and should not be touched at all except by experienced C++ developers.

== The network layer ==

The Wesnoth network layer originally transmitted only config objects. One called send_data with a config object, and the network layer would serialize it and send it to the given socket. Unfortunately this is rather inefficient from a server's perspective, not least because it means that the config object will have to be serialized and compressed for each client. Additionally, of course, it ties one to config objects.

The network layer was thus given additional 'raw' send functions, which allow one to send a raw buffer. Wesnothd uses this to get the gzipped version of documents and send them. Additionally, a flag was added to the network layer to make it receive in 'raw' mode too, allowing one to get a vector<char> containing a buffer which would then be used to construct a simple_wml document.

=== Sharding the network layer ===

The network layer was also refactored to make it scale better. The network layer uses blocking socket operations to send and receive data. Of course, it is intractable for the server to block when communicating with a client, so these operations are performed in worker threads. When one sends data, one places the data in a queue and sends a signal to a worker thread which wakes up and processes the queue. A pool of worker threads operate on the queue. Similarly this pool of threads handles incoming requests, using select() to block until data is available.

This approach created performance problems with the queue that would have to be accessed from the main thread and from this pool of worker threads. A mutex would have to be locked, and many times threads would block on this mutex, all having to access the same queue.

This problem was alleviated by sharding the system: A #define NUM_SHARDS was introduced. The recommended value for this macro is 7 when compiling wesnothd. Instead of one queue and mutex, an array of NUM_SHARDS queues and mutexes is kept. Every socket is hashed into one of these shards based on its memory address. There are also NUM_SHARDS pools of worker threads available. When the main thread queues data, it only has to lock the mutex for the shard it is accessing, meaning worker threads on other shards are not blocked. Similarly for receiving data. This greatly reduces contention amongst threads.

WesnothdDesign

2008-03-17T06:48:04Z

Dave: /* Cool simple_wml optimizations */

= Wesnothd Design =

== Overview ==

This page documents the design of wesnothd, Wesnoth's multiplayer server. This document was written after I (Dave) re-designed wesnothd to try and make it more efficient.

Wesnothd is a network server written in C++. It shares some of Wesnoth's code, in particular the networking code. Wesnothd manages requests from Wesnoth, that are sent in WML. It manages a lobby of players who can chat with each other, create games, join games, observe games, and so forth. Wesnothd maintains a list of games, users, and so forth. Wesnothd largely operates by relaying messages to the appropriate clients. For instance, if a player in a game makes a move, wesnothd will relay this to all clients who are participating in the game. Wesnothd may also perform appropriate filtering and so forth, and allows administrators to administer a game by kicking or banning users and so forth.

== simple_wml ==

Wesnothd originally used the same WML module, the config object, and serialization code as Wesnoth. This allowed code reuse and easy interoperability. However, Wesnoth's WML module is designed for ease of use by coders, and supports rich functionality, parsing user-written WML. This approach proved to be inefficient for wesnothd. config objects store all name/value pairs in attributes and element names as std::string objects. This typically means a dynamically allocated buffer for each and every name and value and element name. This leads to slow parsing as well as high memory use.

Since wesnothd uses WML in a relatively limited way, a specialized WML parser and in-memory representation was developed, called simple_wml. Simple_wml can parse only a subset of WML: it assumes that all attribute names are surrounded by quotes, and that attributes are in lexicographical (alphabetical) order. This allows very quick parsing.

Additionally, the in-memory representation has some limitations. It cannot perform near the same number of operations as config objects can.

=== Documents vs nodes ===

A config object is both a WML document and a node within a document. Simple_wml is different: there is a document object and a node object. A document automatically has a root node, and a node may create child nodes. Nodes may not be transferred between documents (except by swapping documents; see below).

Nodes all track their parents, as well as the document that owns them. This approach allows for several important optimizations.

=== The string_span class ===

Simple_wml defines a string_span class. A string_span is a portion of a string: a pointer to a buffer, and the size of the buffer. A string_span is not seen as owning the string it points into. Rather, it is an immutable 'view' of a part of a string.

All attributes and names in simple_wml nodes are stored as string_spans. This often allows allocation to be minimized or avoided.

=== Ownership semantics ===

A document contains a vector with a list of all buffers it is considered to 'own'. These are buffers its nodes depend on (i.e. string_spans within the nodes refer to within these buffers). When the document is destroyed it will free these buffers.

A document may be constructed by a text buffer or a gzip compressed buffer. The caller may transfer control of the buffer to the document. If it does not, the document will make a copy of the buffer. If the buffer is compressed, the document will make an uncompressed version. The buffer will be added as an owned buffer.

The document will then parse the text buffer, creating nodes. All the nodes will initialize their string_spans for element and attribute values pointing into the text buffer being parsed.

This means that when a WML document is parsed, it will only allocate the node objects. All strings will simply point into the buffer for the document.

Of course, nodes within a WML document might be modified programmatically. Nodes have several methods for setting an attribute, which each have different ownership semantics for the buffers being set:

set_attr(const char* name, const char* value): this function will take two C-style strings, and refer to them with string_spans. The strings are NOT copied. Rather, it is the responsibility of the caller to ensure that these buffers will remain valid throughout the lifetime of the document. This is most often ensured by using data in static memory as input. For instance, you might call some_node.set_attr("has_object, "1"); Because you pass string literals in, you know the memory is guaranteed to be valid through the life of the program.

This method is very efficient, since no allocation takes place

set_attr_dup(const char* name, const char* value): this function will take two C-style strings. The name will be treated as in set_attr, but a copy will be made of the value. The buffer the copy is made in will be stored as an owned buffer of the document, and so will be destroyed when the document is destroyed.

A copy of the name is not made, since having a dynamically generated name is not common, and usually one can use a string literal.

set_attr_dup_name_and_value(const char* name, const char* value): This function works as above, but duplicates both the name and value.

set_child(const char* name): this function creates a new child node and returns a reference to it. The name will be treated as in set_attr(), with no copy being made; it should be in static memory.

It is also possible to duplicate a buffer and make it owned by the document manually. The document class contains a dup_string() method which duplicates a string buffer and stores it as owned by the document.

=== Cool simple_wml optimizations ===

Simple_wml allows for some very nice optimizations. When a document is constructed by parsing, every node contains a string_span referring to the portion of the buffer that it was parsed from. Every node also keeps track of whether it has been modified since parsing or not. When a node is modified, it walks up its parents and marks each one as 'dirty' -- i.e. modified.

When a simple_wml document is output, it will look and see if the root node is dirty. If the root node is not dirty, then the document has not been modified since parsing. We still have access to the buffer that the document was parsed from, so we can simply spit it back out, and do no work in emitting the document.

Additionally, each node contains the portion of the buffer it was parsed from. If the document was modified, then nodes that are dirty will output themselves, but nodes that are not dirty will simply output the portion of the buffer they were parsed from.

Also, when outputting, we generate a full, compact text document. The string_spans in the nodes will, after outputting themselves to the output buffer, be reassigned to point into the output buffer, instead of where they were pointing before. This means that after output is complete, all of our string_spans will be pointing into the output buffer. This means that all other buffers are no longer needed, and will be released by the document.

A simple_wml document can also be queried for its compressed (gzipped) form, ready for sending over the network. If it is parsed from a gzipped buffer, it will keep a reference to this. If the document is not dirty, it will return this gzipped buffer. If it does not have the buffer, or is dirty, then it will generate the text output, compress it, and also cache the gzipped version.

Documents support a compress operation which will store a gzipped buffer of the document, and delete the text buffer and all the nodes and any other buffers. The document will automatically re-construct the nodes if the root node is ever queried for in code. This is very useful if one wants to store a document and perhaps transmit it over the network but it's unlikely that further operations will be performend on the document.

Documents support a swap() operation that allows the contents of two documents to be swapped. This is relatively inexpensive since it simply twiddles pointers. It is very useful, for instance, to populate a long-held document containing level data for a game with the game's definition sent by a client.

This all implies that simple_wml is very efficient at being used to store WML portions sent by clients, and then re-transmit to other clients.

=== simple_wml vs regular WML ===

Performance tests show simple_wml to be MUCH faster than WML used in Wesnoth. Parsing a WML document is between 10 and 30 times faster with simple_wml. Of course, benefits of simple_wml include smart optimizations to try and avoid parsing and outputting at all when unnecessary.

It should be noted though that simple_wml is 'simple' in that it is a stripped down, simplified version of WML. It itself is NOT 'simple' to use, and should never be considered for use in main Wesnoth code. It is very complicated to use, and should not be touched at all except by experienced C++ developers.

== The network layer ==

The Wesnoth network layer originally transmitted only config objects. One called send_data with a config object, and the network layer would serialize it and send it to the given socket. Unfortunately this is rather inefficient from a server's perspective, not least because it means that the config object will have to be serialized and compressed for each client. Additionally, of course, it ties one to config objects.

The network layer was thus given additional 'raw' send functions, which allow one to send a raw buffer. Wesnothd uses this to get the gzipped version of documents and send them. Additionally, a flag was added to the network layer to make it receive in 'raw' mode too, allowing one to get a vector<char> containing a buffer which would then be used to construct a simple_wml document.

=== Sharding the network layer ===

The network layer was also refactored to make it scale better. The network layer uses blocking socket operations to send and receive data. Of course, it is intractable for the server to block when communicating with a client, so these operations are performed in worker threads. When one sends data, one places the data in a queue and sends a signal to a worker thread which wakes up and processes the queue. A pool of worker threads operate on the queue. Similarly this pool of threads handles incoming requests, using select() to block until data is available.

This approach created performance problems with the queue that would have to be accessed from the main thread and from this pool of worker threads. A mutex would have to be locked, and many times threads would block on this mutex, all having to access the same queue.

This problem was alleviated by sharding the system: A #define NUM_SHARDS was introduced. The recommended value for this macro is 7 when compiling wesnothd. Instead of one queue and mutex, an array of NUM_SHARDS queues and mutexes is kept. Every socket is hashed into one of these shards based on its memory address. There are also NUM_SHARDS pools of worker threads available. When the main thread queues data, it only has to lock the mutex for the shard it is accessing, meaning worker threads on other shards are not blocked. Similarly for receiving data. This greatly reduces contention amongst threads.

WesnothdDesign

2008-03-17T06:44:30Z

Dave: New page: = Wesnothd Design = == Overview == This page documents the design of wesnothd, Wesnoth's multiplayer server. This document was written after I (Dave) re-designed wesnothd to try and make...

= Wesnothd Design =

== Overview ==

This page documents the design of wesnothd, Wesnoth's multiplayer server. This document was written after I (Dave) re-designed wesnothd to try and make it more efficient.

Wesnothd is a network server written in C++. It shares some of Wesnoth's code, in particular the networking code. Wesnothd manages requests from Wesnoth, that are sent in WML. It manages a lobby of players who can chat with each other, create games, join games, observe games, and so forth. Wesnothd maintains a list of games, users, and so forth. Wesnothd largely operates by relaying messages to the appropriate clients. For instance, if a player in a game makes a move, wesnothd will relay this to all clients who are participating in the game. Wesnothd may also perform appropriate filtering and so forth, and allows administrators to administer a game by kicking or banning users and so forth.

== simple_wml ==

Wesnothd originally used the same WML module, the config object, and serialization code as Wesnoth. This allowed code reuse and easy interoperability. However, Wesnoth's WML module is designed for ease of use by coders, and supports rich functionality, parsing user-written WML. This approach proved to be inefficient for wesnothd. config objects store all name/value pairs in attributes and element names as std::string objects. This typically means a dynamically allocated buffer for each and every name and value and element name. This leads to slow parsing as well as high memory use.

Since wesnothd uses WML in a relatively limited way, a specialized WML parser and in-memory representation was developed, called simple_wml. Simple_wml can parse only a subset of WML: it assumes that all attribute names are surrounded by quotes, and that attributes are in lexicographical (alphabetical) order. This allows very quick parsing.

Additionally, the in-memory representation has some limitations. It cannot perform near the same number of operations as config objects can.

=== Documents vs nodes ===

A config object is both a WML document and a node within a document. Simple_wml is different: there is a document object and a node object. A document automatically has a root node, and a node may create child nodes. Nodes may not be transferred between documents (except by swapping documents; see below).

Nodes all track their parents, as well as the document that owns them. This approach allows for several important optimizations.

=== The string_span class ===

Simple_wml defines a string_span class. A string_span is a portion of a string: a pointer to a buffer, and the size of the buffer. A string_span is not seen as owning the string it points into. Rather, it is an immutable 'view' of a part of a string.

All attributes and names in simple_wml nodes are stored as string_spans. This often allows allocation to be minimized or avoided.

=== Ownership semantics ===

A document contains a vector with a list of all buffers it is considered to 'own'. These are buffers its nodes depend on (i.e. string_spans within the nodes refer to within these buffers). When the document is destroyed it will free these buffers.

A document may be constructed by a text buffer or a gzip compressed buffer. The caller may transfer control of the buffer to the document. If it does not, the document will make a copy of the buffer. If the buffer is compressed, the document will make an uncompressed version. The buffer will be added as an owned buffer.

The document will then parse the text buffer, creating nodes. All the nodes will initialize their string_spans for element and attribute values pointing into the text buffer being parsed.

This means that when a WML document is parsed, it will only allocate the node objects. All strings will simply point into the buffer for the document.

Of course, nodes within a WML document might be modified programmatically. Nodes have several methods for setting an attribute, which each have different ownership semantics for the buffers being set:

set_attr(const char* name, const char* value): this function will take two C-style strings, and refer to them with string_spans. The strings are NOT copied. Rather, it is the responsibility of the caller to ensure that these buffers will remain valid throughout the lifetime of the document. This is most often ensured by using data in static memory as input. For instance, you might call some_node.set_attr("has_object, "1"); Because you pass string literals in, you know the memory is guaranteed to be valid through the life of the program.

This method is very efficient, since no allocation takes place

set_attr_dup(const char* name, const char* value): this function will take two C-style strings. The name will be treated as in set_attr, but a copy will be made of the value. The buffer the copy is made in will be stored as an owned buffer of the document, and so will be destroyed when the document is destroyed.

A copy of the name is not made, since having a dynamically generated name is not common, and usually one can use a string literal.

set_attr_dup_name_and_value(const char* name, const char* value): This function works as above, but duplicates both the name and value.

set_child(const char* name): this function creates a new child node and returns a reference to it. The name will be treated as in set_attr(), with no copy being made; it should be in static memory.

It is also possible to duplicate a buffer and make it owned by the document manually. The document class contains a dup_string() method which duplicates a string buffer and stores it as owned by the document.

=== Cool simple_wml optimizations ===

Simple_wml allows for some very nice optimizations. When a document is constructed by parsing, every node contains a string_span referring to the portion of the buffer that it was parsed from. Every node also keeps track of whether it has been modified since parsing or not. When a node is modified, it walks up its parents and marks each one as 'dirty' -- i.e. modified.

When a simple_wml document is output, it will look and see if the root node is dirty. If the root node is not dirty, then the document has not been modified since parsing. We still have access to the buffer that the document was parsed from, so we can simply spit it back out, and do no work in emitting the document.

Additionally, each node contains the portion of the buffer it was parsed from. If the document was modified, then nodes that are dirty will output themselves, but nodes that are not dirty will simply output the portion of the buffer they were parsed from.

Also, when outputting, we generate a full, compact text document. The string_spans in the nodes will, after outputting themselves to the output buffer, be reassigned to point into the output buffer, instead of where they were pointing before. This means that after output is complete, all of our string_spans will be pointing into the output buffer. This means that all other buffers are no longer needed, and will be released by the document.

A simple_wml document can also be queried for its compressed (gzipped) form, ready for sending over the network. If it is parsed from a gzipped buffer, it will keep a reference to this. If the document is not dirty, it will return this gzipped buffer. If it does not have the buffer, or is dirty, then it will generate the text output, compress it, and also cache the gzipped version.

Documents support a compress operation which will store a gzipped buffer of the document, and delete the text buffer and all the nodes and any other buffers. The document will automatically re-construct the nodes if the root node is ever queried for in code. This is very useful if one wants to store a document and perhaps transmit it over the network but it's unlikely that further operations will be performend on the document.

This all implies that simple_wml is very efficient at being used to store WML portions sent by clients, and then re-transmit to other clients.

=== simple_wml vs regular WML ===

Performance tests show simple_wml to be MUCH faster than WML used in Wesnoth. Parsing a WML document is between 10 and 30 times faster with simple_wml. Of course, benefits of simple_wml include smart optimizations to try and avoid parsing and outputting at all when unnecessary.

It should be noted though that simple_wml is 'simple' in that it is a stripped down, simplified version of WML. It itself is NOT 'simple' to use, and should never be considered for use in main Wesnoth code. It is very complicated to use, and should not be touched at all except by experienced C++ developers.

== The network layer ==

The Wesnoth network layer originally transmitted only config objects. One called send_data with a config object, and the network layer would serialize it and send it to the given socket. Unfortunately this is rather inefficient from a server's perspective, not least because it means that the config object will have to be serialized and compressed for each client. Additionally, of course, it ties one to config objects.

The network layer was thus given additional 'raw' send functions, which allow one to send a raw buffer. Wesnothd uses this to get the gzipped version of documents and send them. Additionally, a flag was added to the network layer to make it receive in 'raw' mode too, allowing one to get a vector<char> containing a buffer which would then be used to construct a simple_wml document.

=== Sharding the network layer ===

The network layer was also refactored to make it scale better. The network layer uses blocking socket operations to send and receive data. Of course, it is intractable for the server to block when communicating with a client, so these operations are performed in worker threads. When one sends data, one places the data in a queue and sends a signal to a worker thread which wakes up and processes the queue. A pool of worker threads operate on the queue. Similarly this pool of threads handles incoming requests, using select() to block until data is available.

This approach created performance problems with the queue that would have to be accessed from the main thread and from this pool of worker threads. A mutex would have to be locked, and many times threads would block on this mutex, all having to access the same queue.

This problem was alleviated by sharding the system: A #define NUM_SHARDS was introduced. The recommended value for this macro is 7 when compiling wesnothd. Instead of one queue and mutex, an array of NUM_SHARDS queues and mutexes is kept. Every socket is hashed into one of these shards based on its memory address. There are also NUM_SHARDS pools of worker threads available. When the main thread queues data, it only has to lock the mutex for the shard it is accessing, meaning worker threads on other shards are not blocked. Similarly for receiving data. This greatly reduces contention amongst threads.

StartingPoints

2008-03-17T05:21:36Z

Dave: /* Developer information */

__NOTOC__

What would you like to learn about Wesnoth in this wiki? [[Play]] it, [[create]] with it, [[support]] for it, [[project]] resources about it, [[credits]] of it.

This is a page with starting points to exploring this wiki about The Battle for Wesnoth. In addition to the wiki, there's also a [http://www.wesnoth.org homepage], a [http://www.wesnoth.org/forum forum], and a [http://gna.org/projects/wesnoth/ Gna project page].

* [[Special:Categories|List of all page categories in this wiki]]
* [[Special:Allpages|List of all pages in this wiki]]

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinaries]] - precompiled for GNU/Linux, BeOS, PDAs, ...
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [[CompilingWesnoth]] - on Unix, Mac, Windows, GNU/Linux, PDAs, ...
* [[UsingSourceinstall]] - using GNU Source Installer to automate installation and upgrades from source (Unix-likes only)
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems
* [[WesnothOnLinuxPDAs]] - on the Qtopia/OPIE and thepdaXrom/Zaurus C series

== Playing the Game ([[Play]]) ==

==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineCampaigns]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online
* [[Replays]] - archive of replays new and old
* [[How to play...]] - learn more about various faction vs faction strategies

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [[ServerAdministration]] - commands that authenticated users can use to administer the server
* [http://zapicm.freeshell.org Units] - Units advancement trees and stats
** [http://zapicm.freeshell.org/dev Development version]
** [http://zapicm.freeshell.org/stable Stable version]
** [http://server.wesnoth.org/~wesnoth/trunk Trunk version]
* [[RaceDescriptions]] - Elves, Humans, Dwarves, Orcs, Drakes, Undead, Others
** [http://www.wesnoth.org/wiki/Category:Factions] - list all user made factions
* [[Wesnoth_Acronyms_and_Slang|Wesnoth Acronyms and Slang]] - common wesnothian acronyms and slang explained

== Tweaking the Game ([[Create]]) ==
==== Scenarios & Campaigns ====
* [[UserScenarios]] - user-written scenarios, campaigns and game modifications
* [[UMCSandbox]] - where you can do collaborative UMC development
* [[BuildingCampaigns]] - how to make your own single player campaigns
* [[MultiplayerCampaigns]] - how to make your own multiplayer campaigns
* [[BuildingScenarios]] - how to make your own scenarios
* [[BuildingUnits]] - how to make your own units
* [[UnitAnalysis]] - tool to analyze units

==== References ====
* [[ReferenceWML]] and [[AlphabeticalWML]] - all about Wesnoth Markup Language
* [[ReferencePythonAPI]] - upcoming Python interface for AI
==== Tools & Utilities ====
* [[ExternalUtilities]] - scripts to help create scenarios, campaigns, and graphics
* [[WesnothMapEditor]] - summary of controls
==== Art related ====
* [[Create_Art#Art_Tutorials|Art Tutorials]] - help in creating art
* [[GraphicLibrary]] - unit and terrain images posted on the forums
* [[Tiles_Status]] - terrain tiles: proposed and in progress.

== Improving the Game ==
* [[ReportingBugs]] - use Gna!
* [http://www.wesnoth.org/wiki/ReportingBugs#Guidelines_for_suggesting_features Guidelines for suggesting features] - To submit a feature request, use http://bugs.wesnoth.org
==== Developer information ====
* [[DeveloperResources]] - useful links
* [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothSVN]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[DeveloperGuide]] - for those who received SVN commit rights
* [http://wesnoth.slack.it/missing.cgi Missing unit animations and sounds] - what's available and what's missing
* [[WritingYourOwnAI]] - write a C++ plugin
* [[FormulaAI]] - Guide to the experimental formula AI branch
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[WesnothGL]] - Guide to programming the Wesnoth OpenGL branch
* [[WesnothdDesign]] - Guide to the design of wesnothd, the multiplayer server.

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - completely unknown stats...
* [[WesCamp]] - a project for translating user-made campaigns

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[WesnothHistory]] - the Ages of Wesnoth
* [[WesnothGeography]] - description of Wesnoth and surrounding lands
* [[WesnothFigures]] - notable figures of valorous and infamous deeds in Wesnoth
* [[WesnothReviews]] - third party reviews of Wesnoth
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel
* [[Donate]] or [http://cafepress.com/wesnoth buy Wesnoth merchandise].
* [[Trailer]] - the Wesnoth trailer

== Other ==
* [[UsefulLinks]]
* [http://wesnoth.slack.it/?WesnothPlayerMap Map of Wesnoth player locations] - add yourself to the map!
* [http://en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiHaiku]]

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki
* [[WikiMigration]] - we were looking for a replacement for our old wiki (and ended up using Mediawiki)
* [http://www.wesnoth.org/forum/viewtopic.php?t=19462 Obsolete] - help in updating the wiki for v1.4

[[Category:Wesnoth Wiki]]

EasyCoding

2008-03-09T18:00:41Z

Dave: /* WML related features */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== WML related features ==

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960])
=== Recall Event ===
WML event trigger for recalling (the current one triggers on both recalls and recruits) ([http://gna.org/bugs/index.php?3622 FR #3622]) (please read the comments of the report for a proper description of how this should work)
=== Enabling checking of damage dealt in WML ===
A WML variable should be set when triggering some combat-related events, allowing WML to know the amount of damage being dealt. ([http://gna.org/bugs/index.php?7673 FR #7673])
=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.
=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== GUI related features ==
=== Theme Changes ===
* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..), seek Sapient for more info and tips

== Miscellaneous ==
=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting status.variables, possibly terrain, WML value display)

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Committers]]
[[Category:Future]]

SummerOfCodeIdeas

2008-03-09T17:04:58Z

Dave: /* Describe your organization. */

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== I want to be one of your Google Summer of Code student, what should I do... ==

wow wow wow

Google hasn't announced the mentoring organisations yet and wesnoth might not be choosen at all.

the following paragraph is here to have something ready if we are choosen as a mentoring organisation

Here is a quick list of things to do to get you started
* Create an account on gna.org
* Create an account on the wesnoth forum
* Join the irc channel (#wesnoth-dev on irc.freenode.net) and introduce yourself. We will not give formal interviews, but we will clearly favor people we have learnt to know during the selection process
* Contact one of our SummerOfCode people (Ivanovic, Sirp, Boucman, Mordante) to have your forum nick marked as a Summer of code student
* Start a wiki page about your idea, add a link on this page
** fill the questionnaire on this page
** detail your idea as much as possible, look at other students pages, and please give milestones and studies you've done
* Though not mandatory, it is highly advised to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from

== Student proposals ==
''please add a link to the wiki page with your idea''
== List of Ideas for the Project (Suggestions from the wesnoth developers) ==

=== Writing an AI based on the formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth [[WesnothFormulaAIBranch]]

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately it is also one of the most neglected piece of code and a place where a lot of research and work could be done

==== General description ====

The aim of this project is to develop a new AI that would replace the original C++ AI. The main criterias we would want for this new AI are

* ''Plugability :'' It should be trivial for any content maker to change the behavior of the AI in specific case. The exact cases are still to be defined but should typically include
** hardwiring the first few turns of the AI
** changing the recruitment pattern
** completely controlling a given unit (scenario unit)
** taking control then giving back control of a given unit
* ''tunability :'' It should be easy for a scenario author to specify the general behaviour of the enemy on a given scenario (aggressiveness, intrepidity...)
* ''specific behaviours :'' there are some typical behaviours that are not smart to win the scenario but are needed, such as guarding a given unit, a given position, wandering aimlessly, attacking randomly, always fleeing. The AI should implement such behaviours, and allow easy addition of new behaviours

==== Required knowledge and talent ====

* ''A minimal knowledge of C++ is required, a good knowledge of C++ is desired :'' The formula AI framework is a work in progress and chances are high that some changes in the wesnoth code base will be needed. The wesnoth developer community is used to handle people that are familiar with coding but not C++, however the Formula AI framework uses advanced C++ features and a good knowledge of the language would avoid a major hurdle when plugging in new entries or functionalities for the AI
* ''Good social interaction with a large player community :'' A preliminary phase to coding any AI is to know the strategies and game pattern used by human players. This requires huge interaction with the player community. Our Gameplay Developers are open and can give some good starting points, but a big game experience and good interaction with the player community will greatly help in the study of the design

==== Milestones and deliverables ====

It is hard to give milestones at this point, but here are some ideas of what could be done

* ''AI design description, and basic function library :'' This first deliverable aims to conclude the '''study and analysis''' part of the project : becoming familiar with the formula language, study of multiplayer strategies and of the need of scenario writers with regard to AI. We would like to have a description of the code structure of the AI, some basis of the play strategies it would use and how external scenario writers could configure it for the particular behaviour they need
* ''Main AI delivery :'' This milestone's aim is to deliver a working AI implementing the strategies described in the first phase. It would not have to systematically beat the standard C++ AI at this point, but should be able to play the game correctly (recruit, early deployment on villages, grouping units to attack, holding its ground, protecting weak/important units). Moreover most plug-in entries should be available and a test-case for these entries should be provided.
* ''Fine tunning and behaviour library :'' The third phase would validate the actual strategy of the AI. The AI should consistently beat the default C++ AI, and do fairly well against an average human player. At that stage a library of scenario behaviours should also be delivered. The AI does not need to be as efficient with all scenario tweaking, but should act correctly with regard to the particular behaviour desired.

=== Extending the Multiplayer server ===

When the development team met at FOSDEM, we had our multiplayer community, though it is strong and healthy, had its growth restrained by the interface of the multiplayer lobby.

==== General Description ====
The general idea of this project would be
* To study the current lobby,
* To present some ideas of evolutions both in interface and functionalities of our multiplayer interface to allow it to scale to a much larger community
* To present some well constructed thought on our MP community and how that interface would develop it
* Of course to implement those changes :)

Some ideas that we had (but that are in no way mandatory)
* Having a simple way to register and authenticate nicknames, similar to what IRC offers. The point is not to have cryptographically safe logins, but to have something simple that gets the job done
* Having a simple room system? Again, inspired by IRC
* Having some way to find the type of games you are interested in.
** game type
** number of free slots/players
** any other criteria you might find interesting

Other ideas we are not convinced are good, but that are certainly worth studying (especially how the communities based around these concepts are different from ours)
* ranking players
* guilds
* official tournaments
* titles for players
* metaservers
* game matching when players are ranked (poker, bridge...)

The scalability of the project, both in term of number of players, and in term of the possibility for players and developers to extend the concept will be a valued criteria

Administration/moderation problems and techniques should also be studied

interaction with the Add-On server/forum might be an interesting field to expand to

==== Required knowledge and talent ====

* A fair amount of experience with C++ is required. Wesnoth uses some advanced C++ features and is heavily based on BOOST and STL. We can train you in some of the libraries used, but learning all of them would be a big hurdle.
* Experience with multiplayer games, in order to have a good idea of what multiplayer lobbies of other game look like, and (more importantly) a good idea of the social behaviours of multiple MP communities, how teams are formed in games and things like that

==== Milestones and deliverables ====

* A first milestone would be a presentation summarizing the different studies, and the proposed interface. preliminary informal stages would probably be desirable, to make sure the proposed idea is already a consensus within devs
** Study of other MP game-matching interfaces and functionalities
** Study of other MP communities
** Study of other MP moderation practices
** Study of the Wesnoth MP community, including needs, various opinons from different developers and players
* A second milestone would be the main code delivery. Code should be functional for it will be delivered in the next Wesnoth development release

=== Scenario/Campaign editor ===

Currently, in order to create campaign or multiplayer scenarios, it is necessary to manually edit WML files - XML-like configuration files. The goal of this project would be to create a graphical editor allowing the same.

==== General description ====

A scenario editor for Wesnoth supporting everything possible by Wesnoth's engine would be a huge project, so the scope of the actual project would of course be limited - what exactly should be implemented would be decided by initial discussion. Implementation details and choice of language/tools would also be up to the student to choose. The main ideas would be for the scenario editor to be:
* cross-platform (at least Linux, OSX, Windows)
* easy to use (someone who tries reasonably hard should be able to create a simple scenario/campaign with it, even if not knowing WML)
* powerful (there already is a map editor coming with Wesnoth - the scenario editor will provide more/different things)
* extensible (also after the SoC project, it should be easy to add additional features)

There exist at least two attempts at a scenario editor, an OSX-only one which shipped with early Wesnoth versions, and CampGen, an external tool written in WxPython. The student could look at them for ideas or even use one of them as base, but that should be discussed first. The below assumes a new application is developed from scratch (which likely will be much more motivating for the student than reviving an existing attempt). The actual things to be done would be:

* Decide on a cross-platform GUI which would be best suited (Qt4, Wx, GTK, Wesnoth's builtin GUI (in that case, could maybe integrate with the existing map editor, but would have serious other problems), or others...).
* Decide on a platform/language to use (C++, Python, or others...). Wesnoth is written in C++, so it's what most developers would prefer, but as long as it can be expected to work on Linux, OSX and Windows, this is completely open.
* GUI design. This is the main part of the project. The editor should make it easy to create scenarios, so the GUI must not be confusing/hard to use.
* Decide on base features. [[ReferenceWML]] lists everything currently supported by WML. Theoretically, the scenario editor could support everything, but for the timeframe of the SoC project, it will be necessary to decide on the most important features and implement those.
** WML-centric or not? Two opposite views for such an editor would be to either strictly follow WML, as extreme case have one dialog for each WML element. Or on the other hand make a scenario creation tool which completely hides WML and then simply can export to WML, translating features as necessary. The final design likely would be somewhere in between.
** Ability to read existing WML? The editor will export to WML, but need to decide if it also should be able to read it.
** Built-in map editor? Wesnoth comes with a map editor, but it can only be used to define the terrain. The scenario editor has to allow placing events and units and other things, so it will need a way to display maps as well. Would be worth investigating if the existing C++ map-drawing code of Wesnoth can be re-used.
** Ability to enter custom WML code? For advanced users this might be nice, if it can integrate well.
** Story screen editor for campaigns?
** How powerful should the events editor be? WML basically is a turing complete language, so must decide what should be supported and how to present to the user.
** Custom unit animations?
** Custom multi-hex terrains?
* Extensibility (leave the possibility to extend the application with plugins for some of the above things, either with a plugin architecture or by making the source code modular enough)
* WML-export. The second major part besides designing and implementing all the GUI will be exporting the result to WML, and depending on some design choices this could prove more or less hard to do.

==== Required knowledge and talent ====
* Knowledge of C++. Even in case the editor is not written in C++, it will be necessary to look at some parts of Wesnoth's source code (WML-parser, editor, ...) and understand them, possibly even integrate/re-use them.
* Ability/interest in GUI/application design. A not negligible part of the project likely will be spent designing various GUI dialogs.
* Prior use of level creation tools/modding tools. Knowing existing tools for other games will help a lot in the design phase, as many good ideas can be seen there. Not required though.
* Having played Wesnoth and knowing what scenarios look like would help. Someone who never played Wesnoth before would risk losing a lot of precious time playing the game instead of working :) But it's not required of course.
* Knowledge of WML. A candidate who already knows Wesnoth's WML could save the initial time studying it. (On the other hand, not knowing WML might mean less technical bias and might lead to an application which is easer to use for non-technical users.)
* Ability to interact with developers/users. Presenting GUI mockups and test versions and incorporating early user feedback likely will improve the end result a lot. The Wesnoth community is big enough that there should be quite some willing testers.

==== Milestones and deliverables ====
The initial design will decide on many later things, and likely a lot of talking to developers and users will be necessary. But some general milestones I'd expect:
* Create a base test application in the chosen language/platform. This will not do much yet, maybe load some WML and display it as text. Try to package it for Linux, OSX and Windows (there will be help from the Wesnoth community, so no need to have access to all of them), and see if it can be expected to work. If a standard GUI like C++/Qt4 is used, this will be rather trivial. Something like Python/Wx or C#/.NET might take more time.
* Add ability to edit some very simple, maybe only textual properties of a scenario, and export to WML. It should already have base features like Save/Load/Undo, copy/paste, multiple documents, and so on. Depending on the chosen GUI this may be easy or already require some work.
* Finish design. Should list the intended features and demonstrate how the GUI will work.
* Start implementation, a natural milestone would be to make it possible to create and export a very simple, but playable scenario.
* Add more of the features (which ones and in which order depends on the design above, a detailed roadmap will be part of it).

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

==== General description ====
Neither the server nor the client side of the addon server have
seen much improvement over the years; both are overdue for a reworking.
The client side GUI needs polishing. For the
server side we would like to allow better integration with
various tools (such as wmllint), which improve the quality of the addons.

===== Server side =====
The server code either needs to be updated or rewritten, the student is free to make this decision him or herself. The student may choose the language for the server, but because some of the code that needs to be integrated is Python we'll need to hear a specific justification for any other choice.

* The server only needs to run on Linux systems. Cross-platform portability would be nice but isn't required.
* At the moment there's a rudimentary integration with our translation project Wescamp. This needs to be improved. Upon uploading the new content needs to be send to Wescamp (via a svn commit). And the translations need to be fetched on a regular basis.
* We have various tools to check the WML code and also upgrade it to newer version. The addon server needs to be able to run those tools on the content.

===== Client side =====
The client side needs improvements, there are two main clients
the ingame version and a standalone version in Python.

* Upgrade the GUI. Mordante is working on a new GUI library which is intended to make it possible to make the wanted changes.
* Make it easier to see summary and status information on addons. At the moment a lot of new users download something and have no clue what kind of addon it is.
* Make it easier to see whether a newer version of the addon is on the server and update the addon.
* Make it easy to select which translations you want to download and also look for newer versions of the translations.

==== Required knowledge and talent ====
* Knowledge of C++, the game is written in C++ and modifications need to be made there.
* Knowledge of Python, various tools have been written in Python which need to be integrated with the new server.

==== Milestones and deliverables ====
* The first step is to determine what exactly needs to be done and determine in which language the server will be rewritten. This includes, but isn't limited to:
** Determine the exact feature set.
** Protocol changes needed.
** Methods to integrate with both the WML tools and Wescamp with the new server.
** Determine the GUI for the client side.
** Justify the choice of language.
* These points will need to be presented and discussed with the mentor(s).
* The next thing in to implement the feature set. The code needs to be fully functional and committed in trunk.

=== Map editor ===
The map editor in Wesnoth serves two goals, making it easy to create
a new map and helping the terrain artists to test their new terrains.

==== General description ====
The current editor hasn't been actively maintained for quite a while and the
quality of the code isn't up to par with the main game. The student
will either revive the current editor or start from scratch, the latter
will probably be easier. When rewriting from scratch the student can
pick the language of his/her liking as long as the result is crossplatform
(at least Linux/Windows/OS X).

(Note: Unlike the add-on server, there is no specific code-integration reason to prefer Python for the editor rewrite in advance. However. the project has been trying to reduce its dependence on other scripting languages in order to hold down overall maintenance complexity. Thus, the student should be prepared to justify the choice of any language that is not Python or C++.)

Some of the things the new/revived editor should be able to do:
* Include all features of the current editor.
* When rewritten, great care must be taken that the render engine works the same as the render engine in the main game. When rewritten in C++ it can simply use the game sources, otherwise the student needs to turn the main game C++ files into a library which can be called in the language the editor will be written in.
* The editor needs to be able to handle so called ''custom terrain'', these are terrains used in maps but not loaded by default.
* The editor needs to be able to reload the terrain graphics config files, this way terrain artist can test the changes to the config files without having to reload the editor.
* The current editor can generate random maps with help of a config file, which contains a generator definition. The editor can only use one generator hardcoded. This needs to be modified to be able to use every generator config the user has installed.
* Various ideas exist to help the artists to make it easier to tune their terrains and config files, this is a secondary goal. We think it will be too much work to do this in one summer.

==== Required knowledge and talent ====
* The current editor and the main game are written in C++ therefore knowledge of C++ is required. Even if the editor is rewritten in another language the render engine needs to be converted to a library.
* The student needs to be able to make a user friendly user interface.
* Depending on in which language and toolkit the editor is (re)written in the student will need to have skills in that language and toolkit. The current editor uses the SDL toolkit with our own widget toolkit.

==== Milestones and deliverables ====
* The first step is to make a priority list of features. This means the student has to interact with the community and determine what is most wanted.
* From this list the student needs create a sublist of items he/she will be able to do within one summer.
* This needs to be presented and discussed with the mentor(s).
* The next thing in to implement the feature set. The code needs to be fully functional and committed in trunk.

=== Make your own ideas ===
If you have your own idea the best thing is to join IRC wesnoth-dev at irc.freenode.net and discuss the idea with the developers there. If the developers think your idea is interesting and like the feature you can start to turn it into a full proposal. Once done discuss it again on IRC so the developers can accept your idea.

=== Other ideas to be fleshed out ===
* A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the cave generator) etc.

== Other info to provide for GSoC ==
==== Describe your organization. ====
The Battle for Wesnoth, or simply Wesnoth, is a free turn based strategy game with role playing elements designed in June 2003 by David White (Sirp). David currently works at Google.

The first stable release (1.0) was on October 2 2005, the latest stable release (1.4) was on March 8 2008.

* A turn-based strategy game
* On a hexagonal board
* Role playing game style elements
* Single player and multiplayer modes
* Runs on a variety of platforms
* Highly customizable and 'moddable'

What makes Wesnoth stand apart from the other open source games are the following aspects:

* A large developer and player community
** two servers (stable and developement) with a usual minimum load of more than a hundred players
** more than two thousands downloads a day
* A mature project, but with active development and many improvements
* High quality artwork: both graphics and music
* Very well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after five years of development, and a very solid, fun product has been created, there are still plenty of new developers, and the number of commits to SVN is still increasing

The general [http://www.wesnoth.org/wiki/WesnothPhilosophy Philosophy] of the game (both for gameplay and coding) puts an emphasis on simplicity. The core rules are meant to be learnt easily but provide interesting gameplay and diverse strategies.

On the other hand, Wesnoth scenarios provides a simple language to easily customize scenarios, which has lead to a huge modding community providing us with a wide amount of content.

* Advanced C++, with some use of Boost
* The Simple Directmedia Layer (SDL) libraries:
* SDL, SDL_net, SDL_ttf, SDL_image
* gettext for internationalization
* Python to allow scriptable AIs
* Otherwise, most of Wesnoth's technology is “home grown”:
** WML : the scripting language used to write scenarios
** FormulaAI : our AI developement language

* 2.1 million downloads via sourceforge.net, many more via various mirrors of Linux Distributions
* best rated game at the [http://www.happypenguin.org/list?sort=avg_rating linux game tome]
* game of the year 2007 at [http://www.linuxquestions.org/questions/2007-linuxquestions.org-members-choice-awards-79/open-source-game-of-the-year-610236/ linuxquestions.org]
* One of the top 20 rated projects on [http://freshmeat.net/stats/#rating Freshmeat] (currently 16th highest rating, and the highest rated game).

==== Why is your organization applying to participate in GSoC 2008? What do you hope to gain by participating?====

Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

If a student were dedicated to any of these uncovered areas, we believe that person could be brought up to speed relatively quickly and function as a peer of the existing developers.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that have lagged behind

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation.====
This is the first time the Wesnoth project has applied to Google SoC.

==== If your organization has not previously participated in GSoC, have you applied in the past? If so, for what year(s)?====

This is the first time the Wesnoth project has applied to Google SoC.

==== Who will your organization administrator be? Please include Google Account information.====
Nils Kneuper aka Ivanovic

crazy.ivanovic |ATTT| googlemail.com

==== What license(s) does your project use?====
Our project is entirely GPL.

All code is GPL.

All art is GPL, 99% was made for the project, everything else was taken from content that was checked to be GPL.

==== What is the URL for your ideas page?====
Our main summer of code page is located at http://www.wesnoth.org/wiki/SummerOfCodeIdeas

This page contains various coding ideas and the thought the development team has already given them.

It also contains a list of the developers that are the most active on IRC and their domains of interest.

==== What is the main development mailing list or forum for your organization?====
Most development work takes place on "wesnoth-dev |ATTT| gna.org". Beside this some work happens at http://www.wesnoth.org/forum/.

in particular, all art developement takes place on the forum.

==== What is the main IRC channel for your organization?====

All our IRC channels are on the ''freenode'' network

* ''#wesnoth-dev'' is the main development channel, where most discussion takes place
* ''#wesnoth'' is a generic channel for the community
* ''#wesnoth-mp'' is a separate channel for multiplayer games and balancing

==== Does your organization have an application template you would like to see students use? If so, please provide it now.====
We plan mainly to meet potential students through our IRC channel, but the following questions are wesnoth-specific and are worth pondering for any student, even if we don't need a formal answer

* Basics
** Just write a small introduction to yourself.
** State your preferred email address.
** If you have chosen a nick for IRC and Wesnoth forums, what is it?
** Why do you want to participate in summer of code?
** What are you studying, subject, level and school?

* Experience
** What programs/software have you worked on before?
** Have you developed software in a team environment before? (As opposed to hacking on something on your own)
** 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?
** What development model would you use (e.g. keywords: V-model, XP programming, agile programming, iterative; with the help of prototyping, formal specifications, tests, etc).
** Open Source
*** Are you already involved with any open source development project? If yes, please describe the project and the scope of your involvement.
** Gaming experience
*** Are you a gamer? If so...
*** What type of gamer are you?
*** What type of games?
*** What type of opponents do you prefer?
*** Are you more interested in story or gameplay?
*** 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.

* Communication skills
** Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
** Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
** Do you give constructive advice?
** Do you receive advice well?
** Are you good at sorting useful criticisms from useless ones?

* Project
** Did you select a project from our list? If that is the case, what project did you select?
** If you have invented your own project, please describe the project and the scope.
** Why did you choose this project?
** Include an estimated timeline for your work on the project
** Include as much technical detail about your implementation as you can
** What do you expect to gain from this project?
** What would make you stay in the Wesnoth community after the conclusion of SOC?

* Practical considerations
** Are you familiar with any of the following tools?
*** Subversion
*** C++
*** Python
** Which tools do you normally use for development? Why do you use them?
** What programming languages are you fluent in?
** What spoken languages are you fluent in?
** At what hours are you awake (please specify in UTC)
** Would you mind talking with your mentor on telephone / internet phone?

* Detailed answer (optional, but writing skill is a good predictor of ability to work on a programming team, so you will improve your chances by responding to this).
** Write a small essay (750-1000 words or more) explaining why you want to participate in a Wesnoth GSoC project. You can use the above questions as guides, but feel free to throw in more information if you feel it is relevant.
** What is your perception of 'open source'? Briefly explain what you think of the whole 'open source' concept, how you discovered open source, what you expect to gain/experience by participating in an open-source project. (Answer separately or as part of above mini-essay)
** What motivates or inspires you to write programs and develop software?

''''to be completed''''

==== Who will be your backup organization administrator? Please include Google Account information.====
David White (davewx7@gmail.com)

==== Who will your mentors be? Please include Google Account information.====

David White (davewx7@gmail.com)

Jeremy Rosen alias Boucman (boucman2|ATTT|gmail.com)

Mark de Wever aka Mordante (mordante.wesnoth|ATTT|gmail.com)

Jörg Hinrichs alias YogiHH (joerghh.hinrichs|ATTT|googlemail.com)

==== What criteria did you use to select these individuals as mentors? Please be as specific as possible.====

Our first criterion was that all the people had to be volunteers. According to other open source projects, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Dave is the project leader and one of the most knowledgeable in C++. He has also written the Formula AI code which we plan to develop via the SoC. He is well known in our community for formulating simple but effective explanations for complicated topics, and has good design intuition. The growth of Wesnoth demonstrates his capacity to get other developers to work together and keep them involved in a thriving community.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the [http://wiki.wesnoth.org/UnsortedContrib Art Contribution] section of the wiki (now automated) and the [http://wiki.wesnoth.org/ReferenceWML WML Reference Manual]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org and has created the new developer process we currently use.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base.

YogiHH has been with the project for more than two years. He did a major refactoring to the gameplay engine and worked quite a bit on the multiplayer code. He also has been a professional trainer for C/C++, Java and C# for many years. Right now he works in a project where he serves as a mentor for a junior developer.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of people who to contact for which regards. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

==== What is your plan for dealing with disappearing students?====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensible about criticism and our community is used to people being sensible to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, his mentor will be in charge of recontacting him to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to him, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors?====

All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We took the time to ask other former GSoC projects about the workload needed to be a mentor, and our mentors accepted the job knowing the amount of work it involved.

However, should it happen, we would continue to mentor as a developper community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program?====

Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two patch... you're in" In other word, anybody that is able to get two non-trivial patches applied is offered commit right.

We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our [[EasyCoding]] pages (these project are usually a couple of hours long and has been chosen to provide easy access to code)

Usually, patches go back and forth a couple of time, to make sure that all secondary things are in place (indenting, coding style, modified makefiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to maintain our project alive.

If the student is a little proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can be rough at time.

==== What will you do to ensure that your accepted students stick with the project after GSoC concludes?====

Since our community has a history of having developers easily and quickly join, we expect the student to be a full-fledged developer quite fast (probably a little after the end of the bonding period).

Thus there will be no "end of GSoC" transition. At the end of the Summer of code we expect the student to be responsible for the part he developed, and to continue taking care of it, like other developers are responsible for their part.

''''TO BE COMPLETED''''

== People to bug on IRC ==
Everybody feel free to edit/correct his entry!

=== boucman ===
As our "patch monkey" he accustomed to critiquing patches of every kind. Beside this, he knows many areas of the game due to working on applying patches. He is particularly used to answering question from new coders, and doesn't mind explaining trivial stuff. He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project.

=== Dave alias Sirp ===
Sirp started Wesnoth and is our lead developer. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

=== Elias Pscherning (elias) ===
He wrote the original version of campgen and as such will know a lot about what is needed to to make such an editor work correctly. The work on a scenario editor might be based upon campgen and as such his knowledge will be really helpful.

=== Eric S. Raymond (ESR) ===
ESR is our project toolsmith; he has written several tools that semi-automate various aspects of WML maintenance. While most of our developers/designers concentrate on either the C++ core or WML but not both, he has a balanced understanding of both levels and may be helpful in helping students develop a grasp of the overall architecture. Finally, he did the last overhaul of the Wesnoth UI and understands UI design principles; he is well-equipped to guide students working in that area.

=== Karol Nowak (grzywacz) ===
Last year he participated at GSoC as a student, so he will understand the situation of GSoC students. Beside this he is our top expert on embedded devices, and is actively working on the gp2x support.

=== Mordante ===
Many of the possible projects involve the code for which he is an area expert. Also, many of the possible projects currently listed on the ideas page require GUI parts to work. Given that Mordante wants to tackle a rewrite of large parts of this, he will be our expert there as well as already being our area expert for the terrain engine.

=== Nils Kneuper (Ivanovic) ===
He is doing nothing special, he just does some "administrative work" like packaging fresh tarballs when it is time for them and works on setting up any kind of deadlines and timetables related to releasing. He has administrative powers in most areas, no matter if website, forum or IRC. Beside this he uploads translation updates, tries to communicate with the translation teams when it is required and translates a little bit himself every now and then. But in general he is not a real expert in anything, just has a look at things that come up and redirects people to the correct contacts.

=== Noy ===
Noy is an oddity among developers; he's got no coding skills whatsoever and possesses a limited understanding of computers, which is illustrated by his difficulty operating a Mac. Instead, Noy makes his contribution in gameplay and multiplayer design, drawing upon his background in social sciences research, military strategy and playing games online, to understand the effects of development on the playing community behavior. Along with Soliton, Noy is a useful conduit to discuss any issues in this area; just don't ask him about revising the level of randomness in the game.

=== Noyga ===
Another versatile developer, on the C++ side he doesn't concentrate on a particular area, did some tweaks to improve translations in some languages (like enabling the female forms for names in various place) but know quite well the C++ side of units, abilities and WML. On the WML side he's an expert.

=== Soliton ===
He knows our MP server setup best. Beside this he has already done a lot of work on the MP server himself. So he probably has most knowledge about it and, being one of our MP-developers, might provide important help from the perspective of the MP player community and what is needed there.

=== YogiHH or Piotr Cychowski (cycholka) ===
Since they are the two developers who know most about building under Windows, they will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.

=== zookeeper or Mythological or Rhuvaen ===
As our leading WML experts those are to be contacted when it comes to anything related WML problems since they know this stuff best. They do maintain most of the campaigns and improve them whenever they have a good idea for changes.

[[Category:Future]]

SummerOfCodeIdeas

2008-03-09T16:46:58Z

Dave: /* Describe your organization. */

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== I want to be one of your Google Summer of Code student, what should I do... ==

wow wow wow

Google hasn't announced the mentoring organisations yet and wesnoth might not be choosen at all.

the following paragraph is here to have something ready if we are choosen as a mentoring organisation

Here is a quick list of things to do to get you started
* Create an account on gna.org
* Create an account on the wesnoth forum
* Join the irc channel (#wesnoth-dev on irc.freenode.net) and introduce yourself. We will not give formal interviews, but we will clearly favor people we have learnt to know during the selection process
* Contact one of our SummerOfCode people (Ivanovic, Sirp, Boucman, Mordante) to have your forum nick marked as a Summer of code student
* Start a wiki page about your idea, add a link on this page
** fill the questionnaire on this page
** detail your idea as much as possible, look at other students pages, and please give milestones and studies you've done
* Though not mandatory, it is highly advised to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from

== Student proposals ==
''please add a link to the wiki page with your idea''
== List of Ideas for the Project (Suggestions from the wesnoth developers) ==

=== Writing an AI based on the formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth [[WesnothFormulaAIBranch]]

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately it is also one of the most neglected piece of code and a place where a lot of research and work could be done

==== General description ====

The aim of this project is to develop a new AI that would replace the original C++ AI. The main criterias we would want for this new AI are

* ''Plugability :'' It should be trivial for any content maker to change the behavior of the AI in specific case. The exact cases are still to be defined but should typically include
** hardwiring the first few turns of the AI
** changing the recruitment pattern
** completely controlling a given unit (scenario unit)
** taking control then giving back control of a given unit
* ''tunability :'' It should be easy for a scenario author to specify the general behaviour of the enemy on a given scenario (aggressiveness, intrepidity...)
* ''specific behaviours :'' there are some typical behaviours that are not smart to win the scenario but are needed, such as guarding a given unit, a given position, wandering aimlessly, attacking randomly, always fleeing. The AI should implement such behaviours, and allow easy addition of new behaviours

==== Required knowledge and talent ====

* ''A minimal knowledge of C++ is required, a good knowledge of C++ is desired :'' The formula AI framework is a work in progress and chances are high that some changes in the wesnoth code base will be needed. The wesnoth developer community is used to handle people that are familiar with coding but not C++, however the Formula AI framework uses advanced C++ features and a good knowledge of the language would avoid a major hurdle when plugging in new entries or functionalities for the AI
* ''Good social interaction with a large player community :'' A preliminary phase to coding any AI is to know the strategies and game pattern used by human players. This requires huge interaction with the player community. Our Gameplay Developers are open and can give some good starting points, but a big game experience and good interaction with the player community will greatly help in the study of the design

==== Milestones and deliverables ====

It is hard to give milestones at this point, but here are some ideas of what could be done

* ''AI design description, and basic function library :'' This first deliverable aims to conclude the '''study and analysis''' part of the project : becoming familiar with the formula language, study of multiplayer strategies and of the need of scenario writers with regard to AI. We would like to have a description of the code structure of the AI, some basis of the play strategies it would use and how external scenario writers could configure it for the particular behaviour they need
* ''Main AI delivery :'' This milestone's aim is to deliver a working AI implementing the strategies described in the first phase. It would not have to systematically beat the standard C++ AI at this point, but should be able to play the game correctly (recruit, early deployment on villages, grouping units to attack, holding its ground, protecting weak/important units). Moreover most plug-in entries should be available and a test-case for these entries should be provided.
* ''Fine tunning and behaviour library :'' The third phase would validate the actual strategy of the AI. The AI should consistently beat the default C++ AI, and do fairly well against an average human player. At that stage a library of scenario behaviours should also be delivered. The AI does not need to be as efficient with all scenario tweaking, but should act correctly with regard to the particular behaviour desired.

=== Extending the Multiplayer server ===

When the development team met at FOSDEM, we had our multiplayer community, though it is strong and healthy, had its growth restrained by the interface of the multiplayer lobby.

==== General Description ====
The general idea of this project would be
* To study the current lobby,
* To present some ideas of evolutions both in interface and functionalities of our multiplayer interface to allow it to scale to a much larger community
* To present some well constructed thought on our MP community and how that interface would develop it
* Of course to implement those changes :)

Some ideas that we had (but that are in no way mandatory)
* Having a simple way to register and authenticate nicknames, similar to what IRC offers. The point is not to have cryptographically safe logins, but to have something simple that gets the job done
* Having a simple room system? Again, inspired by IRC
* Having some way to find the type of games you are interested in.
** game type
** number of free slots/players
** any other criteria you might find interesting

Other ideas we are not convinced are good, but that are certainly worth studying (especially how the communities based around these concepts are different from ours)
* ranking players
* guilds
* official tournaments
* titles for players
* metaservers
* game matching when players are ranked (poker, bridge...)

The scalability of the project, both in term of number of players, and in term of the possibility for players and developers to extend the concept will be a valued criteria

Administration/moderation problems and techniques should also be studied

interaction with the Add-On server/forum might be an interesting field to expand to

==== Required knowledge and talent ====

* A fair amount of experience with C++ is required. Wesnoth uses some advanced C++ features and is heavily based on BOOST and STL. We can train you in some of the libraries used, but learning all of them would be a big hurdle.
* Experience with multiplayer games, in order to have a good idea of what multiplayer lobbies of other game look like, and (more importantly) a good idea of the social behaviours of multiple MP communities, how teams are formed in games and things like that

==== Milestones and deliverables ====

* A first milestone would be a presentation summarizing the different studies, and the proposed interface. preliminary informal stages would probably be desirable, to make sure the proposed idea is already a consensus within devs
** Study of other MP game-matching interfaces and functionalities
** Study of other MP communities
** Study of other MP moderation practices
** Study of the Wesnoth MP community, including needs, various opinons from different developers and players
* A second milestone would be the main code delivery. Code should be functional for it will be delivered in the next Wesnoth development release

=== Scenario/Campaign editor ===

Currently, in order to create campaign or multiplayer scenarios, it is necessary to manually edit WML files - XML-like configuration files. The goal of this project would be to create a graphical editor allowing the same.

==== General description ====

A scenario editor for Wesnoth supporting everything possible by Wesnoth's engine would be a huge project, so the scope of the actual project would of course be limited - what exactly should be implemented would be decided by initial discussion. Implementation details and choice of language/tools would also be up to the student to choose. The main ideas would be for the scenario editor to be:
* cross-platform (at least Linux, OSX, Windows)
* easy to use (someone who tries reasonably hard should be able to create a simple scenario/campaign with it, even if not knowing WML)
* powerful (there already is a map editor coming with Wesnoth - the scenario editor will provide more/different things)
* extensible (also after the SoC project, it should be easy to add additional features)

There exist at least two attempts at a scenario editor, an OSX-only one which shipped with early Wesnoth versions, and CampGen, an external tool written in WxPython. The student could look at them for ideas or even use one of them as base, but that should be discussed first. The below assumes a new application is developed from scratch (which likely will be much more motivating for the student than reviving an existing attempt). The actual things to be done would be:

* Decide on a cross-platform GUI which would be best suited (Qt4, Wx, GTK, Wesnoth's builtin GUI (in that case, could maybe integrate with the existing map editor, but would have serious other problems), or others...).
* Decide on a platform/language to use (C++, Python, or others...). Wesnoth is written in C++, so it's what most developers would prefer, but as long as it can be expected to work on Linux, OSX and Windows, this is completely open.
* GUI design. This is the main part of the project. The editor should make it easy to create scenarios, so the GUI must not be confusing/hard to use.
* Decide on base features. [[ReferenceWML]] lists everything currently supported by WML. Theoretically, the scenario editor could support everything, but for the timeframe of the SoC project, it will be necessary to decide on the most important features and implement those.
** WML-centric or not? Two opposite views for such an editor would be to either strictly follow WML, as extreme case have one dialog for each WML element. Or on the other hand make a scenario creation tool which completely hides WML and then simply can export to WML, translating features as necessary. The final design likely would be somewhere in between.
** Ability to read existing WML? The editor will export to WML, but need to decide if it also should be able to read it.
** Built-in map editor? Wesnoth comes with a map editor, but it can only be used to define the terrain. The scenario editor has to allow placing events and units and other things, so it will need a way to display maps as well. Would be worth investigating if the existing C++ map-drawing code of Wesnoth can be re-used.
** Ability to enter custom WML code? For advanced users this might be nice, if it can integrate well.
** Story screen editor for campaigns?
** How powerful should the events editor be? WML basically is a turing complete language, so must decide what should be supported and how to present to the user.
** Custom unit animations?
** Custom multi-hex terrains?
* Extensibility (leave the possibility to extend the application with plugins for some of the above things, either with a plugin architecture or by making the source code modular enough)
* WML-export. The second major part besides designing and implementing all the GUI will be exporting the result to WML, and depending on some design choices this could prove more or less hard to do.

==== Required knowledge and talent ====
* Knowledge of C++. Even in case the editor is not written in C++, it will be necessary to look at some parts of Wesnoth's source code (WML-parser, editor, ...) and understand them, possibly even integrate/re-use them.
* Ability/interest in GUI/application design. A not negligible part of the project likely will be spent designing various GUI dialogs.
* Prior use of level creation tools/modding tools. Knowing existing tools for other games will help a lot in the design phase, as many good ideas can be seen there. Not required though.
* Having played Wesnoth and knowing what scenarios look like would help. Someone who never played Wesnoth before would risk losing a lot of precious time playing the game instead of working :) But it's not required of course.
* Knowledge of WML. A candidate who already knows Wesnoth's WML could save the initial time studying it. (On the other hand, not knowing WML might mean less technical bias and might lead to an application which is easer to use for non-technical users.)
* Ability to interact with developers/users. Presenting GUI mockups and test versions and incorporating early user feedback likely will improve the end result a lot. The Wesnoth community is big enough that there should be quite some willing testers.

==== Milestones and deliverables ====
The initial design will decide on many later things, and likely a lot of talking to developers and users will be necessary. But some general milestones I'd expect:
* Create a base test application in the chosen language/platform. This will not do much yet, maybe load some WML and display it as text. Try to package it for Linux, OSX and Windows (there will be help from the Wesnoth community, so no need to have access to all of them), and see if it can be expected to work. If a standard GUI like C++/Qt4 is used, this will be rather trivial. Something like Python/Wx or C#/.NET might take more time.
* Add ability to edit some very simple, maybe only textual properties of a scenario, and export to WML. It should already have base features like Save/Load/Undo, copy/paste, multiple documents, and so on. Depending on the chosen GUI this may be easy or already require some work.
* Finish design. Should list the intended features and demonstrate how the GUI will work.
* Start implementation, a natural milestone would be to make it possible to create and export a very simple, but playable scenario.
* Add more of the features (which ones and in which order depends on the design above, a detailed roadmap will be part of it).

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

==== General description ====
Neither the server nor the client side of the addon server have
seen much improvement over the years; both are overdue for a reworking.
The client side GUI needs polishing. For the
server side we would like to allow better integration with
various tools (such as wmllint), which improve the quality of the addons.

===== Server side =====
The server code either needs to be updated or rewritten, the student is free to make this decision him or herself. The student may choose the language for the server, but because some of the code that needs to be integrated is Python we'll need to hear a specific justification for any other choice.

* The server only needs to run on Linux systems. Cross-platform portability would be nice but isn't required.
* At the moment there's a rudimentary integration with our translation project Wescamp. This needs to be improved. Upon uploading the new content needs to be send to Wescamp (via a svn commit). And the translations need to be fetched on a regular basis.
* We have various tools to check the WML code and also upgrade it to newer version. The addon server needs to be able to run those tools on the content.

===== Client side =====
The client side needs improvements, there are two main clients
the ingame version and a standalone version in Python.

* Upgrade the GUI. Mordante is working on a new GUI library which is intended to make it possible to make the wanted changes.
* Make it easier to see summary and status information on addons. At the moment a lot of new users download something and have no clue what kind of addon it is.
* Make it easier to see whether a newer version of the addon is on the server and update the addon.
* Make it easy to select which translations you want to download and also look for newer versions of the translations.

==== Required knowledge and talent ====
* Knowledge of C++, the game is written in C++ and modifications need to be made there.
* Knowledge of Python, various tools have been written in Python which need to be integrated with the new server.

==== Milestones and deliverables ====
* The first step is to determine what exactly needs to be done and determine in which language the server will be rewritten. This includes, but isn't limited to:
** Determine the exact feature set.
** Protocol changes needed.
** Methods to integrate with both the WML tools and Wescamp with the new server.
** Determine the GUI for the client side.
** Justify the choice of language.
* These points will need to be presented and discussed with the mentor(s).
* The next thing in to implement the feature set. The code needs to be fully functional and committed in trunk.

=== Map editor ===
The map editor in Wesnoth serves two goals, making it easy to create
a new map and helping the terrain artists to test their new terrains.

==== General description ====
The current editor hasn't been actively maintained for quite a while and the
quality of the code isn't up to par with the main game. The student
will either revive the current editor or start from scratch, the latter
will probably be easier. When rewriting from scratch the student can
pick the language of his/her liking as long as the result is crossplatform
(at least Linux/Windows/OS X).

(Note: Unlike the add-on server, there is no specific code-integration reason to prefer Python for the editor rewrite in advance. However. the project has been trying to reduce its dependence on other scripting languages in order to hold down overall maintenance complexity. Thus, the student should be prepared to justify the choice of any language that is not Python or C++.)

Some of the things the new/revived editor should be able to do:
* Include all features of the current editor.
* When rewritten, great care must be taken that the render engine works the same as the render engine in the main game. When rewritten in C++ it can simply use the game sources, otherwise the student needs to turn the main game C++ files into a library which can be called in the language the editor will be written in.
* The editor needs to be able to handle so called ''custom terrain'', these are terrains used in maps but not loaded by default.
* The editor needs to be able to reload the terrain graphics config files, this way terrain artist can test the changes to the config files without having to reload the editor.
* The current editor can generate random maps with help of a config file, which contains a generator definition. The editor can only use one generator hardcoded. This needs to be modified to be able to use every generator config the user has installed.
* Various ideas exist to help the artists to make it easier to tune their terrains and config files, this is a secondary goal. We think it will be too much work to do this in one summer.

==== Required knowledge and talent ====
* The current editor and the main game are written in C++ therefore knowledge of C++ is required. Even if the editor is rewritten in another language the render engine needs to be converted to a library.
* The student needs to be able to make a user friendly user interface.
* Depending on in which language and toolkit the editor is (re)written in the student will need to have skills in that language and toolkit. The current editor uses the SDL toolkit with our own widget toolkit.

==== Milestones and deliverables ====
* The first step is to make a priority list of features. This means the student has to interact with the community and determine what is most wanted.
* From this list the student needs create a sublist of items he/she will be able to do within one summer.
* This needs to be presented and discussed with the mentor(s).
* The next thing in to implement the feature set. The code needs to be fully functional and committed in trunk.

=== Make your own ideas ===
If you have your own idea the best thing is to join IRC wesnoth-dev at irc.freenode.net and discuss the idea with the developers there. If the developers think your idea is interesting and like the feature you can start to turn it into a full proposal. Once done discuss it again on IRC so the developers can accept your idea.

=== Other ideas to be fleshed out ===
* A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the cave generator) etc.

== Other info to provide for GSoC ==
==== Describe your organization. ====
The Battle for Wesnoth, or simply Wesnoth, is a free turn based strategy game with role playing elements designed in June 2003 by David White (Sirp). David currently works at Google.

The first stable release (1.0) was on October 2 2005, the latest stable release (1.4) was on March 8 2008.

* A turn-based strategy game
* On a hexagonal board
* Role playing game style elements
* Single player and multiplayer modes
* Runs on a variety of platforms
* Highly customizable and 'moddable'

What makes Wesnoth stand apart from the other open source games are the following aspects:

* A large developer and player community
** two servers (stable and developement) with a usual minimum load of more than a hundred players
** more than two thousands downloads a day
* A mature project, but with active development and many improvements
* High quality artwork: both graphics and music
* Very well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after five years of development, and a very solid, fun product has been created, there are still plenty of new developers, and the number of commits to SVN is still increasing

The general [http://www.wesnoth.org/wiki/WesnothPhilosophy Philosophy] of the game (both for gameplay and coding) puts an emphasis on simplicity. The core rules are meant to be learnt easily but provide interesting gameplay and diverse strategies.

On the other hand, Wesnoth scenarios provides a simple language to easily customize scenarios, which has lead to a huge modding community providing us with a wide amount of content.

* Advanced C++, with some use of Boost
* The Simple Directmedia Layer (SDL) libraries:
* SDL, SDL_net, SDL_ttf, SDL_image
* gettext for internationalization
* Python to allow scriptable AIs
* Otherwise, most of Wesnoth's technology is “home grown”:
** WML : the scripting language used to write scenarios
** FormulaAI : our AI developement language

* 2.1 million downloads via sourceforge.net, many more via various mirrors of Linux Distributions
* best rated game at the [http://www.happypenguin.org/list?sort=avg_rating linux game tome]
* game of the year 2007 at [http://www.linuxquestions.org/questions/2007-linuxquestions.org-members-choice-awards-79/open-source-game-of-the-year-610236/ linuxquestions.org]

==== Why is your organization applying to participate in GSoC 2008? What do you hope to gain by participating?====

Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

If a student were dedicated to any of these uncovered areas, we believe that person could be brought up to speed relatively quickly and function as a peer of the existing developers.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that have lagged behind

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation.====
This is the first time the Wesnoth project has applied to Google SoC.

==== If your organization has not previously participated in GSoC, have you applied in the past? If so, for what year(s)?====

This is the first time the Wesnoth project has applied to Google SoC.

==== Who will your organization administrator be? Please include Google Account information.====
Nils Kneuper aka Ivanovic

crazy.ivanovic |ATTT| googlemail.com

==== What license(s) does your project use?====
Our project is entirely GPL.

All code is GPL.

All art is GPL, 99% was made for the project, everything else was taken from content that was checked to be GPL.

==== What is the URL for your ideas page?====
Our main summer of code page is located at http://www.wesnoth.org/wiki/SummerOfCodeIdeas

This page contains various coding ideas and the thought the development team has already given them.

It also contains a list of the developers that are the most active on IRC and their domains of interest.

==== What is the main development mailing list or forum for your organization?====
Most development work takes place on "wesnoth-dev |ATTT| gna.org". Beside this some work happens at http://www.wesnoth.org/forum/.

in particular, all art developement takes place on the forum.

==== What is the main IRC channel for your organization?====

All our IRC channels are on the ''freenode'' network

* ''#wesnoth-dev'' is the main development channel, where most discussion takes place
* ''#wesnoth'' is a generic channel for the community
* ''#wesnoth-mp'' is a separate channel for multiplayer games and balancing

==== Does your organization have an application template you would like to see students use? If so, please provide it now.====
We plan mainly to meet potential students through our IRC channel, but the following questions are wesnoth-specific and are worth pondering for any student, even if we don't need a formal answer

* Basics
** Just write a small introduction to yourself.
** State your preferred email address.
** If you have chosen a nick for IRC and Wesnoth forums, what is it?
** Why do you want to participate in summer of code?
** What are you studying, subject, level and school?

* Experience
** What programs/software have you worked on before?
** Have you developed software in a team environment before? (As opposed to hacking on something on your own)
** 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?
** What development model would you use (e.g. keywords: V-model, XP programming, agile programming, iterative; with the help of prototyping, formal specifications, tests, etc).
** Open Source
*** Are you already involved with any open source development project? If yes, please describe the project and the scope of your involvement.
** Gaming experience
*** Are you a gamer? If so...
*** What type of gamer are you?
*** What type of games?
*** What type of opponents do you prefer?
*** Are you more interested in story or gameplay?
*** 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.

* Communication skills
** Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
** Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
** Do you give constructive advice?
** Do you receive advice well?
** Are you good at sorting useful criticisms from useless ones?

* Project
** Did you select a project from our list? If that is the case, what project did you select?
** If you have invented your own project, please describe the project and the scope.
** Why did you choose this project?
** Include an estimated timeline for your work on the project
** Include as much technical detail about your implementation as you can
** What do you expect to gain from this project?
** What would make you stay in the Wesnoth community after the conclusion of SOC?

* Practical considerations
** Are you familiar with any of the following tools?
*** Subversion
*** C++
*** Python
** Which tools do you normally use for development? Why do you use them?
** What programming languages are you fluent in?
** What spoken languages are you fluent in?
** At what hours are you awake (please specify in UTC)
** Would you mind talking with your mentor on telephone / internet phone?

* Detailed answer (optional, but writing skill is a good predictor of ability to work on a programming team, so you will improve your chances by responding to this).
** Write a small essay (750-1000 words or more) explaining why you want to participate in a Wesnoth GSoC project. You can use the above questions as guides, but feel free to throw in more information if you feel it is relevant.
** What is your perception of 'open source'? Briefly explain what you think of the whole 'open source' concept, how you discovered open source, what you expect to gain/experience by participating in an open-source project. (Answer separately or as part of above mini-essay)
** What motivates or inspires you to write programs and develop software?

''''to be completed''''

==== Who will be your backup organization administrator? Please include Google Account information.====
David White (davewx7@gmail.com)

==== Who will your mentors be? Please include Google Account information.====

David White (davewx7@gmail.com)

Jeremy Rosen alias Boucman (boucman2|ATTT|gmail.com)

Mark de Wever aka Mordante (mordante.wesnoth|ATTT|gmail.com)

Jörg Hinrichs alias YogiHH (joerghh.hinrichs|ATTT|googlemail.com)

==== What criteria did you use to select these individuals as mentors? Please be as specific as possible.====

Our first criterion was that all the people had to be volunteers. According to other open source projects, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Dave is the project leader and one of the most knowledgeable in C++. He has also written the Formula AI code which we plan to develop via the SoC. He is well known in our community for formulating simple but effective explanations for complicated topics, and has good design intuition. The growth of Wesnoth demonstrates his capacity to get other developers to work together and keep them involved in a thriving community.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the [http://wiki.wesnoth.org/UnsortedContrib Art Contribution] section of the wiki (now automated) and the [http://wiki.wesnoth.org/ReferenceWML WML Reference Manual]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org and has created the new developer process we currently use.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base.

YogiHH has been with the project for more than two years. He did a major refactoring to the gameplay engine and worked quite a bit on the multiplayer code. He also has been a professional trainer for C/C++, Java and C# for many years. Right now he works in a project where he serves as a mentor for a junior developer.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of people who to contact for which regards. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

==== What is your plan for dealing with disappearing students?====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensible about criticism and our community is used to people being sensible to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, his mentor will be in charge of recontacting him to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to him, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors?====

All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We took the time to ask other former GSoC projects about the workload needed to be a mentor, and our mentors accepted the job knowing the amount of work it involved.

However, should it happen, we would continue to mentor as a developper community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program?====

Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two patch... you're in" In other word, anybody that is able to get two non-trivial patches applied is offered commit right.

We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our [[EasyCoding]] pages (these project are usually a couple of hours long and has been chosen to provide easy access to code)

Usually, patches go back and forth a couple of time, to make sure that all secondary things are in place (indenting, coding style, modified makefiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to maintain our project alive.

If the student is a little proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can be rough at time.

==== What will you do to ensure that your accepted students stick with the project after GSoC concludes?====

Since our community has a history of having developers easily and quickly join, we expect the student to be a full-fledged developer quite fast (probably a little after the end of the bonding period).

Thus there will be no "end of GSoC" transition. At the end of the Summer of code we expect the student to be responsible for the part he developed, and to continue taking care of it, like other developers are responsible for their part.

''''TO BE COMPLETED''''

== People to bug on IRC ==
Everybody feel free to edit/correct his entry!

=== boucman ===
As our "patch monkey" he accustomed to critiquing patches of every kind. Beside this, he knows many areas of the game due to working on applying patches. He is particularly used to answering question from new coders, and doesn't mind explaining trivial stuff. He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project.

=== Dave alias Sirp ===
Sirp started Wesnoth and is our lead developer. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

=== Elias Pscherning (elias) ===
He wrote the original version of campgen and as such will know a lot about what is needed to to make such an editor work correctly. The work on a scenario editor might be based upon campgen and as such his knowledge will be really helpful.

=== Eric S. Raymond (ESR) ===
ESR is our project toolsmith; he has written several tools that semi-automate various aspects of WML maintenance. While most of our developers/designers concentrate on either the C++ core or WML but not both, he has a balanced understanding of both levels and may be helpful in helping students develop a grasp of the overall architecture. Finally, he did the last overhaul of the Wesnoth UI and understands UI design principles; he is well-equipped to guide students working in that area.

=== Karol Nowak (grzywacz) ===
Last year he participated at GSoC as a student, so he will understand the situation of GSoC students. Beside this he is our top expert on embedded devices, and is actively working on the gp2x support.

=== Mordante ===
Many of the possible projects involve the code for which he is an area expert. Also, many of the possible projects currently listed on the ideas page require GUI parts to work. Given that Mordante wants to tackle a rewrite of large parts of this, he will be our expert there as well as already being our area expert for the terrain engine.

=== Nils Kneuper (Ivanovic) ===
He is doing nothing special, he just does some "administrative work" like packaging fresh tarballs when it is time for them and works on setting up any kind of deadlines and timetables related to releasing. He has administrative powers in most areas, no matter if website, forum or IRC. Beside this he uploads translation updates, tries to communicate with the translation teams when it is required and translates a little bit himself every now and then. But in general he is not a real expert in anything, just has a look at things that come up and redirects people to the correct contacts.

=== Noy ===
Noy is an oddity among developers; he's got no coding skills whatsoever and possesses a limited understanding of computers, which is illustrated by his difficulty operating a Mac. Instead, Noy makes his contribution in gameplay and multiplayer design, drawing upon his background in social sciences research, military strategy and playing games online, to understand the effects of development on the playing community behavior. Along with Soliton, Noy is a useful conduit to discuss any issues in this area; just don't ask him about revising the level of randomness in the game.

=== Noyga ===
Another versatile developer, on the C++ side he doesn't concentrate on a particular area, did some tweaks to improve translations in some languages (like enabling the female forms for names in various place) but know quite well the C++ side of units, abilities and WML. On the WML side he's an expert.

=== Soliton ===
He knows our MP server setup best. Beside this he has already done a lot of work on the MP server himself. So he probably has most knowledge about it and, being one of our MP-developers, might provide important help from the perspective of the MP player community and what is needed there.

=== YogiHH or Piotr Cychowski (cycholka) ===
Since they are the two developers who know most about building under Windows, they will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.

=== zookeeper or Mythological or Rhuvaen ===
As our leading WML experts those are to be contacted when it comes to anything related WML problems since they know this stuff best. They do maintain most of the campaigns and improve them whenever they have a good idea for changes.

[[Category:Future]]

SummerOfCodeIdeas

2008-03-01T18:28:47Z

Dave: /* Who will your mentors be? Please include Google Account information. */

== Ideas for Google Summer of Code projects ==

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== List of Ideas for the Project ==

=== Writing an AI based on the formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth ''link to formula AI page here''

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately it is also one of the most neglected piece of code and a place where a lot of research and work could be done

==== General description ====

The aim of this project is to develop a new AI that would replace the original C++ AI. The main criterias we would want for this new AI are

* ''Plugability :'' It should be trivial for any content maker to change the behavior of the AI in specific case. The exact cases are still to be defined but should typically include
** hardwiring the first few turns of the AI
** changing the recruitment pattern
** completely controlling a given unit (scenario unit)
** taking control then giving back control of a given unit
* ''tunability :'' It should be easy for a scenario author to specify the general behaviour of the enemy on a given scenario (aggressiveness, intrepidity...)
* ''specific behaviours :'' there are some typical behaviours that are not smart to win the scenario but are needed, such as guarding a given unit, a given position, wandering aimlessly, attacking randomly, always fleeing. The AI should implement such behaviours, and allow easy addition of new behaviours

==== Required knowledge and talent ====

* ''A minimal knowledge of C++ is required, a good knowledge of C++ is desired :'' The formula AI framework is a work in progress and chances are high that some changes in the wesnoth code base will be needed. The wesnoth developer community is used to handle people that are familiar with coding but not C++, however the Formula AI framework uses advanced C++ features and a good knowledge of the language would avoid a major hurdle when plugging in new entries or functionalities for the AI
* ''Good social interaction with a large player community :'' A preliminary phase to coding any AI is to know the strategies and game pattern used by human players. This requires huge interaction with the player community. Our Gameplay Developers are open and can give some good starting points, but a big game experience and good interaction with the player community will greatly help in the study of the design

==== Milestones and deliverables ====

It is hard to give milestones at this point, but here are some ideas of what could be done

* ''AI design description, and basic function library :'' This first deliverable aims to conclude the '''study and analysis''' part of the project : becoming familiar with the formula language, study of multiplayer strategies and of the need of scenario writers with regard to AI. We would like to have a description of the code structure of the AI, some basis of the play strategies it would use and how external scenario writers could configure it for the particular behaviour they need
* ''Main AI delivery :'' This milestone's aim is to deliver a working AI implementing the strategies described in the first phase. It would not have to systematically beat the standard C++ AI at this point, but should be able to play the game correctly (recruit, early deployment on villages, grouping units to attack, holding its ground, protecting weak/important units). Moreover most plug-in entries should be available and a test-case for these entries should be provided.
* ''Fine tunning and behaviour library :'' The third phase would validate the actual strategy of the AI. The AI should consistently beat the default C++ AI, and do fairly well against an average human player. At that stage a library of scenario behaviours should also be delivered. The AI does not need to be as efficient with all scenario tweaking, but should act correctly with regard to the particular behaviour desired.

=== Extending the Multiplayer server ===

When the development team met at FOSDEM, we had our multiplayer community, though it is strong and healthy, had its growth restrained by the interface of the multiplayer lobby.

==== General Description ====
The general idea of this project would be
* To study the current lobby,
* To present some ideas of evolutions both in interface and functionalities of our multiplayer interface to allow it to scale to a much larger community
* To present some well constructed thought on our MP community and how that interface would develop it
* Of course to implement those changes :)

Some ideas that we had (but that are in no way mandatory)
* Having a simple way to register and authenticate nicknames, similar to what IRC offers. The point is not to have cryptographically safe logins, but to have something simple that gets the job done
* Having a simple room system? again inspired on IRC
* Having some way to find the type of games you are interested in.
** game type
** number of free slots/players
** any other criteria you might find interesting

Other ideas we are not convinced are good, but that are certainly worth studying (especially how the communities based around these concepts are different from ours)
* ranking players
* guilds
* official tournaments
* titles for players
* metaservers

The scalability of the project, both in term of number of players, and in term of the possibility for players and developers to extend the concept will be a valued criteria

Administration/moderation problems and techniques should also be studied

interaction with the Add-On server/forum might be an interesting field to expand to

==== Required knowledge and talent ====

* A fair amount of experience on C++ is required. Wesnoth uses some advanced C++ features and is heavily based on BOOST and STL. We can train you in some of the libraries used, but learning all of them would be a big hurdle
* Various experience with multiplayer games, in order to have a good idea of what multiplayer lobbies of other game look like, and (more importantly) a good idea of the social behaviours of multiple MP communities, how teams are formed in games and things like that

==== Milestones and deliverables ====

* A first milestone would be a presentation summarizing the different studies, and the proposed interface. preliminary informal stages would probably be desirable, to make sure the proposed idea is already a consensus within devs
** Study of other MP game-matching interfaces and functionalities
** Study of other MP communities
** Study of other MP moderation practices
** Study of the Wesnoth MP community, including needs, various opinons from different developers and players
* A second milestone would be the main code delivery. Code should be functional for it will be delivered in the next Wesnoth development release

=== Scenario/Campaign editor ===

Currently, in order to create campaign or multiplayer scenarios, it is necessary to manually edit WML files - XML-like configuration files. The goal of this project would be to create a graphical editor allowing the same.

==== General description ====

A scenario editor for Wesnoth supporting everything possible by Wesnoth's engine would be a huge project, so the scope of the actual project would of course be limited - what exactly should be implemented would be decided by initial discussion. Implementation details and choice of language/tools would also be up to the student to choose. The main ideas would be for the scenario editor to be:
* cross-platform (at least Linux, OSX, Windows)
* easy to use (someone who tries reasonably hard should be able to create a simple scenario/campaign with it, even if not knowing WML)
* powerful (there already is a map editor coming with Wesnoth - the scenario editor will provide more/different things)
* extensible (also after the SoC project, it should be easy to add additional features)

There exist at least two attempts at a scenario editor, an OSX-only one which shipped with early Wesnoth versions, and CampGen, an external tool written in WxPython. The student could look at them for ideas or even use one of them as base, but that should be discussed first. The below assumes a new application is developed from scratch (which likely will be much more motivating for the student than reviving an existing attempt). The actual things to be done would be:

* Decide on a cross-platform GUI which would be best suited (Qt4, Wx, GTK, Wesnoth's builtin GUI (in that case, could maybe integrate with the existing map editor, but would have serious other problems), or others...).
* Decide on a platform/language to use (C++, Python, or others...). Wesnoth is written in C++, so it's what most developers would prefer, but as long as it can be expected to work on Linux, OSX and Windows, this is completely open.
* GUI design. This is the main part of the project. The editor should make it easy to create scenarios, so the GUI must not be confusing/hard to use.
* Decide on base features. [[ReferenceWML]] lists everything currently supported by WML. Theoretically, the scenario editor could support everything, but for the timeframe of the SoC project, it will be necessary to decide on the most important features and implement those.
** WML-centric or not? Two opposite views for such an editor would be to either strictly follow WML, as extreme case have one dialog for each WML element. Or on the other hand make a scenario creation tool which completely hides WML and then simply can export to WML, translating features as necessary. The final design likely would be somewhere in between.
** Ability to read existing WML? The editor will export to WML, but need to decide if it also should be able to read it.
** Built-in map editor? Wesnoth comes with a map editor, but it can only be used to define the terrain. The scenario editor has to allow placing events and units and other things, so it will need a way to display maps as well. Would be worth investigating if the existing C++ map-drawing code of Wesnoth can be re-used.
** Ability to enter custom WML code? For advanced users this might be nice, if it can integrate well.
** Story screen editor for campaigns?
** How powerful should the events editor be? WML basically is a turing complete language, so must decide what should be supported and how to present to the user.
** Custom unit animations?
** Custom multi-hex terrains?
* Extensibility (leave the possibility to extend the application with plugins for some of the above things, either with a plugin architecture or by making the source code modular enough)
* WML-export. The second major part besides designing and implementing all the GUI will be exporting the result to WML, and depending on some design choices this could prove more or less hard to do.

==== Required knowledge and talent ====
* Knowledge of C++. Even in case the editor is not written in C++, it will be necessary to look at some parts of Wesnoth's source code (WML-parser, editor, ...) and understand them, possibly even integrate/re-use them.
* Ability/interest in GUI/application design. A not negligible part of the project likely will be spent designing various GUI dialogs.
* Prior use of level creation tools/modding tools. Knowing existing tools for other games will help a lot in the design phase, as many good ideas can be seen there. Not required though.
* Having played Wesnoth and knowing what scenarios look like would help. Someone who never played Wesnoth before would risk losing a lot of precious time playing the game instead of working :) But it's not required of course.
* Knowledge of WML. A candidate who already knows Wesnoth's WML could save the initial time studying it. (On the other hand, not knowing WML might mean less technical bias and might lead to an application which is easer to use for non-technical users.)
* Ability to interact with developers/users. Presenting GUI mockups and test versions and incorporating early user feedback likely will improve the end result a lot. The Wesnoth community is big enough that there should be quite some willing testers.

==== Milestones and deliverables ====
The initial design will decide on many later things, and likely a lot of talking to developers and users will be necessary. But some general milestones I'd expect:
* Create a base test application in the chosen language/platform. This will not do much yet, maybe load some WML and display it as text. Try to package it for Linux, OSX and Windows (there will be help from the Wesnoth community, so no need to have access to all of them), and see if it can be expected to work. If a standard GUI like C++/Qt4 is used, this will be rather trivial. Something like Python/Wx or C#/.NET might take more time.
* Add ability to edit some very simple, maybe only textual properties of a scenario, and export to WML. It should already have base features like Save/Load/Undo, copy/paste, multiple documents, and so on. Depending on the chosen GUI this may be easy or already require some work.
* Finish design. Should list the intended features and demonstrate how the GUI will work.
* Start implementation, a natural milestone would be to make it possible to create and export a very simple, but playable scenario.
* Add more of the features (which ones and in which order depends on the design above, a detailed roadmap will be part of it).

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

==== General description ====
Both the server and client side of the addon server haven't
been improved over the years and can use quite some improvements.
The client side GUI needs quite some improvements. For the
server side it's wanted to allow better integration with
various tools, which improve the quality of the addons.

===== Server side =====
The server code either needs to be updated or rewritten, the
student is free to make this decision him or herself. The
student is free to choose the language for the server.

* The server only needs to run on Linux systems, crossplatform would be nice but isn't required.
* At the moment there's a rudimentary integration with our translation project Wescamp. This needs to be improved. Upon uploading the new content needs to be send to Wescamp (via a svn commit). And the translations need to be fetched on a regular basis.
* We have various tools to check the WML code and also upgrade it to newer version. The addon server needs to be able to run those tools on the content.

===== Client side =====
The client side needs improvements, there are two main clients
the ingame version and a standalone version in Python.

* Upgrade the GUI, Mordante is working on a new GUI library which is intended to make it possible to make the wanted changes.
* Make it easier to see what kind of addon it is, at the moment a lot of new users download something and have no clue what kind of addon it is.
* Make it easier to see whether a newer version of the addon is on the server and update the addon.
* Make it easy to select which translations you want to download and also look for newer versions of the translations.

==== Required knowledge and talent ====
* Knowledge of C++, the game is written in C++ and modifications need to be made there.
* Knowlegde of Python, various tools have been written in Python which need to be intergrated with the new server.

==== Milestones and deliverables ====
* The first step is to determine what exactly needs to be done and determine in which language the server will be rewritten. This includes, but isn't limited to:
** Determine the exact feature set.
** Protocol changes needed.
** Methods to integrate with both the WML tools and Wescamp with the new server.
** Determine the GUI for the client side.
* This needs to be presented and discussed with the mentor(s).
* The next thing in to implement the feature set. The code needs to be fully functional and committed in trunk.

=== Own ideas ===
If you have your own idea the best thing is to join
IRC wesnoth-dev at irc.freenode.net and discuss the
idea with the developers there. If the developers
think your idea is interesting and like the feature
you can start to turn it into a full proposal. Once
done discuss it again on IRC so the developers can
accept your idea.

=== Other ideas to be fleshed out ===
* Working on the GUI engine (needs to be defined more precisely)
* The editor can use quite a revamp
* A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the ave generator) etc.

== Other info to provide for GSoC ==
==== Describe your organization. ====

==== Why is your organization applying to participate in GSoC 2008? What do you hope to gain by participating?====

Most of our developers have interesting areas in which they work. Though they are efficient in their areas, there are areas that are interesting but have a high barrier of entry.

By having a student dedicated to any of these areas, we could quickly get someone up to date with that particular area, efficient, and responsible of this area.

Basically, by getting new people in and making them actively responsible for an area of code we hope to kickstart some areas of the project that have lagged behind

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation.====
This is the first time the Wesnoth projects applies to Google SoC

==== If your organization has not previously participated in GSoC, have you applied in the past? If so, for what year(s)?====

This is the first time the Wesnoth projects applies to Google SoC

==== Who will your organization administrator be? Please include Google Account information.====
Nils Kneuper aka Ivanovic

crazy.ivanovic |ATTT| googlemail.com

==== What license(s) does your project use?====
Our project is entirely GPL.

All code is GPL.

All art is GPL, 99% was made for the project, everything was taken from content that was checked to be GPL.

==== What is the URL for your ideas page?====
Our main summer of code pages is located at http://www.wesnoth.org/wiki/SummerOfCodeIdeas

This page contains various coding ideas and the thought the development team has already given them.

It also contains a list of the developers that are the most active on IRC and their domain of interest.

==== What is the main development mailing list or forum for your organization?====
Most development work takes place on "wesnoth-dev |ATTT| gna.org". Beside this some work happens at http://www.wesnoth.org/forum/.

in particular, all art developement takes place on the foum

==== What is the main IRC channel for your organization?====

All our IRC channels are on the ''freenode'' network

* ''#wesnoth-dev'' is the main development channel, where most discussion takes place
* ''#wesnoth'' is a generic channel for the community
* ''#wesnoth-mp'' is a separate channel for multiplayer games and balancing

==== Does your organization have an application template you would like to see students use? If so, please provide it now.====
We plan mainly to meet potential students through our IRC channel, but the following questions are wesnoth-specific and are worth pondering for any student, even if we don't need a formal answer

* What type of gamer are you? What type of games? What type of opponent? Are you more interested in story or gameplay ?
* Are you good at interacting with other players ? Our developer community is quite nice, but the player community can be a bit rough.
* Do you give constructive advices? Do you receive advice well? Are you good at sorting useful criticism from useless ones?

''''to be completed''''

==== Who will be your backup organization administrator? Please include Google Account information.====

Jeremy Rosen alias Boucman

boucman2|ATTT|gmail.com

==== Who will your mentors be? Please include Google Account information.====

David White (davewx7@gmail.com)

==== What criteria did you use to select these individuals as mentors? Please be as specific as possible.====

==== What is your plan for dealing with disappearing students?====

==== What is your plan for dealing with disappearing mentors?====

==== What steps will you take to encourage students to interact with your project's community before, during and after the program?====

Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two patch... you're in" In other word, anybody that is able to get two non-trivial patches applied is offered commit right.

We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our [[EasyCoding]] pages (these project are usually a couple of hours long and has been chosen to provide easy access to code)

Usually, patches go back and forth a couple of time, to make sure that all secondary things are in place (indenting, coding style, modified makefiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to maintain our project alive.

If the student is a little proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

We also plan to give a special forum title to any students. This will allow all forum members to tell them appart from normal users and give them read/write access to the developper only forums.

This will also allow usto quickly spot any problem they might have interacting with the player community. We have a very mature developper community, but our player community is made of all sort of people of all age and education, and it can be rough at time.

==== What will you do to ensure that your accepted students stick with the project after GSoC concludes?====

=== People to bug on IRC, possible mentors ===
Everybody feel free to edit/correct his entry!

==== Dave alias Sirp ====

Sirp started Wesnoth and is our lead developper. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

==== Mordante ====
Many of the possible projects do at least partly go into the area of code where he knows most of. Plus many of the possible projects currently listed on the ideas page do require GUI parts to work, too. So if Mordante wants to tackle a rewrite of large parts of this, he will be our expert there as well as he already is our expert for the terrain engine (cf. editor / scenario editor works).

==== Elias Pscherning (elias) ====
He has written the original version of campgen and as such will know a lot about what is needed to to make such an editor work correctly. The work on a scenario editor might be based upon campgen and as such make his knowledge really helpful.

==== Karol Nowak (grzywacz) ====
Last year he was participating at GSoC as a student, so he knows at least this side of the medal. Beside this he is our top expert regarding embedded devices support since he is actively working on the gp2x support.

==== boucman ====
As our "patch monkey" he has valuable knowledge in comments and critics for patches of every kind. Beside this he knows many areas of the game due to working on applying patches. He is particularly used to answer question from new coders, and doesn't mind explaining trivial stuff.

He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project

==== Soliton ====
He does know our mp server setup best. Beside this he already has done a lot of work on the mp server himself, too. So he probably has most knowledge about it and due to being one of our mp-developers might provide important help from the perspective of mp-community and what is needed there.

==== zookeeper or Mythological or Rhuvaen ====
As our leading WML expert it would be good to have him in the list when it comes to WML specific problems. That is for work on the scenario editor he probably knows best what should be implemented in it and what is a usable way for things.

==== YogiHH or Piotr Cychowski (cycholka) ====
Since they are the two developers who know most about building under Windows, they will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.

WesnothPhilosophy

2008-02-29T23:07:04Z

Dave: /* Wesnoth Philosophy II: Where Next? */

{{Needs update}}
== The History of, and Philosophy behind Wesnoth ==

The 18th of December [2003] will mark six months since the first version of Battle for Wesnoth, version 0.1, was released.

At this time, I feel it is appropriate to respond to something Bazarov said in another thread:

<blockquote>am having a little difficulty understanding the core values of the game in the eyes of the creators. I think having an established, ordered list of these would help a lot in my attempts to help. A white paper of sorts. I don't think this should be done by voting, either; a clear, concise vision would be nice. Where does originality factor in? I, too, felt that the game's focus was on the units rather than the strategy, that the building of my colourful army was more important than the logic of any scenario.</blockquote>

We talk about the 'KISS [1] principle' here a lot, and I think that that is the most core
design principle used in Wesnoth. It was the key principle that enabled Wesnoth
to get off the ground, and it is the principle that has kept it alive since.

First of all, the concept of 'KISS' is a software development principle.
Not a game-design principle. The idea of game rules being simple is not
necessarily a bad one, and can be linked to KISS in that game rules
that are simple to implement are often ones that most players would
consider 'simple'. However simple game rules are not directly related
to KISS, as many people on the forum mistakenly seem to have thought.

When I was a teenager, I attempted to write games several times.
Some of them were playable, even impressive - especially considering
my resources and skill - but none of them were professional, and polished.
When I showed them to people, they would be impressed, and say
"this looks good", but I knew that none of them would actually want to take
the game home and play it for themselves.

My programming skills back then left alot of room for improvement.
I had a basic, self-taught knowledge of C and C++.
Then I went to college, and after that got a job programming,
where my skills improved immensely.

In some of my spare time, I decided to try writing a game again.
What kind of game? Well, I was confident of my skills,
so I would write a complex game, using all the latest programming tools.

I wanted to write a Civilization-like game, but with some major rule changes,
and a better AI. I had thought up sophisticated systems for everything.
The result? It failed before it even got started, collapsing in a mountain of
complexity.

I gave up on writing a game for a long time after that.
I was busy with other things anyhow. But then one day, I played
a game that I had played when I was much younger, a Genesis game:
Master of Monsters. It was fun, lots of fun, yet it was simple.
Simple enough that I was confident I could program a game like it easily enough.

I had analyzed that most Free games fall into one of two categories:
they are either boringly trivial, or they are insanely complex,
and never really get off the ground. I decided I would claim the middle ground:
make it simple enough to write, but substantial enough to be lots of fun.
It wouldn't be as ambitious as some things I wanted to write, but at
least it would work.

But, I don't see the point of writing a Free game which is simply
a copy of a commercial game. My aim would be to write
something new, something better, something which borrows the best ideas
from a number of other games, and which adds new ideas of its own.

The idea of KISS is that the feature must be easy enough to program
that before the programmer starts working on it, they have a very clear
and strong understanding of how they're going to make it work.
Not a 'yes I can do this but it is kinda complicated'.
Rather they should be thinking 'this is so stupid and simple that it's
really really easy for me to do'. So I decided on a simple rule for the
game: a feature would be added only if I knew immediately how to implement it.
I wouldn't make vague promises to myself about features that would be later added,
but which I had no idea how to do.

I started with a few basic units, and two races: Orcs and Elves.
Elves had horsemen, which could advance to knights, archers which
could advance to rangers, and fighters which could advance to heroes.

I considered different systems of advancement. Even considering
something which keeps track of the activity the unit undergoes,
and advances it in that area, but I rejected such a system for
something simple, something similiar to Master
of Monsters with the added choice of letting the player
choose what their unit advances into at some points.

The focus would be around building your own army, and watching
it grow as its members became more experienced.
You would only have basic control over the advancement of
a particular member of the army, but you would decide what units go
into the army.

I also fleshed out a very basic interface. There would be only a few commands:
to move a unit, and to attack with that unit, as well as to recruit and
recall units. I added in unit skills, which was something Master of Monsters
didn't have, but I made the skills occur implicitly -- healing would be
dispensed to all units around a specific unit for instance.

Obviously, Wesnoth is a fantasy game, so it contains some implication of
spells/magic, however I have always disliked games that got deep
into sophisticated systems of spells.

In Wesnoth, wars would be decided with sword and bow.
Mages would be involved too, of course, but warfare was to be
about guiding troops around strategically, not about which spell
to cast and where. So, from the beginning I decided
that all spells would be implicit, or simply a type of attack.

This was a big divergence from Master of Monsters where
one spell could be cast every turn by each master at any place
on the battlefield. That was, in my opinion, one of the game's
worst features - if your enemy had advanced a unit on
the other side of the map, you could try to kill him with a spell.

I also made the combat very simple. An example of this is the
way in which the chance to hit is calculated. I'm
wondering how many people know how the chance to hit is calculated
in Wesnoth? I thought it was alot more complex in
Master of Monsters until I studied how they did it.

What I suspect most people would immediately consider for a
chance-to-hit system would be a formula that relies on the
attacker's skill with the weapon, and the defender's defensiveness,
as well as the terrain the defender is in.

The way Wesnoth does it is in fact so insanely simple that
I suspect many people who did not know how it is done will
think 'what a naive, silly system!' when they read the following:

<blockquote>The chance to hit is taken entirely from the defender's defensive rating in the terrain it is in.</blockquote>

So, there is always 30% chance to hit Elves in forest,
and 60% chance to hit them in grassland. The attacker's skill doesn't come
into the equation.

I decided it would add interesting strategy, though, if just
a very few weapons had a special attribute that would
guarantee them a certain chance to hit. I decided that was
an appropriate thing for magic, to differentiate it: so, I
decided that magic attacks would always have 70% chance to hit.

For all my efforts though, and for all the people who say that
graphics are of little importance or unimportant, I don't
think that Wesnoth would have gotten anywhere if fmunoz hadn't
seen it, and drawn some very good graphics for it. The
graphics I had drawn were pathetic, but he drew some nice ones,
and added the undead and later humans to the game, as
well as doing some scenarios, and adding some very good ideas to the game.

I think it's important for us to remember the KISS principle
as development continues. Remember: Wesnoth has not reached
1.0 yet. It's not a finished work. It could still fail.
Let's make it easy for it to succeed by keeping everything simple.

Oh and how did I come up with the name 'Wesnoth'?
It was late at night, and I wanted to release version 0.1.
I muttered syllables to myself, until I came up with a pair
that sounded halfway reasonable: 'Wesnoth'.

David

[1] Keep It Simple, Stupid

== More on the KISS principle ==

The reason behind the KISS principle is fairly straightforward:
often programmers will be confronted with someone -
perhaps a user, perhaps a designer, perhaps themselves -
who wants them to implement something to work in a certain way.
Oftentimes the programmer can only just work their head around
all the requirements, and when they start implementing the feature,
they don't have a clear idea of how the entire feature
is to be implemented, because it's so complicated.

Such a situation inevitably leads to low-quality and very buggy software.

KISS intentionally has the 'stupid' part, because often
'architecture astronauts' as they're known come up with 'super
elegant generic designs' that to them are simple, and most
importantly, elegant. Elegance is nice, but in a real-world
situation, it doesn't defeat KISS. Without the 'stupid' part
in there, some people would claim that elegance and
simplicity are strongly related, and so their 'elegant'
design should be implemented.

But no, it doesn't matter how elegant it is. If the coder can't
understand exactly how to do it, it's not KISS. A less
elegant design, one that is simple and stupid, should be used instead.

So that's it I guess: if the implementer finds it very very easy
to do, then it's KISS. If they don't, it's not.

This can be related back to game rules somewhat. One of the aims
of Wesnoth was to make a game with a pretty good AI.
One of the things I noticed about other games, was that they added
in alot of game rules that their users wanted, which
were very very difficult for the AIs of those games to use or understand.

So, I decided I'd make a game where the rules were detailed
enough to be fun, but structured in a way that the AI can work with them.

I think that's the best definition of KISS for game rules that
we will find: if it's very easy to implement, including
making the AI use the rules effectively, then it's KISS.

This makes most but not all of our current game rules KISS.
In particular, special abilities involving auras
(leadership, healing, illumination) are not currently used at all
effectively by the AI. It might not be so complicated
for the AI to be able to use them though.

Things like skirmish are very KISS, since the AI immediately
understands how to use it effectively.

You'll note that originally, when Wesnoth consisted of
no multiplayer, and no campaigns other than Heir to the Throne,
it was structured so the AI would only control units that it can
use effectively: it didn't have access to any aura
effects, while it did have access to things like poison.

This is the cornerstone of KISS: what is laughably easy for
a programmer to do is going to result in high quality,
bug-free software. What is 'simple' for users, or 'elegant'
for designers, but not easy for a programmer is not going
to result in high quality software.

David

== Wesnoth Philosophy II: Where Next? ==

We had a section in here on where to take Wesnoth next, but it was written before 1.0 was released. That would make it rather out of date.

Eric Raymond has pressured me to update this section. Interestingly, much of the above was based on some of Eric Raymond's writings.

So, we are about to release Wesnoth 1.4. 1.4 will be a very solid, stable release, with an impressive list of features. Some people claimed that Wesnoth wasn't really ready for a 1.0 label back when we released 1.0. Any concerns that Wesnoth is not a stable, mature game should have been removed by 1.2 though, and certainly should be crushed by 1.4. The team has done an excellent job of building a very impressive product.

Where to now? Onward and upward, of course! We already have a great game, and around that great game has developed a great community. Using the resources we now have available, we can continue to improve the game to be better and better. To make it more fun, faster, run on more platforms, more reliable, and support a wider variety of game elements.

Of all suggestions to improve -- or perhaps I should say change -- Wesnoth, one of the most common, and certainly the most controversial, is to alter the gameplay in some way. To add a new gameplay feature, to add new unit special abilities, to alter unit stats, and so on and so forth. Are we planning to continue to make gameplay changes, and of what nature? Should we radically alter the game?

We have a great game, that people enjoy. We don't plan to radically alter the core game mechanics. We will continue to tweak things of course -- and our gameplay balance developers have done an excellent job of balancing things out, and will continue to do so. The core game mechanics will remain the same. What we might do, however, is add a wider variety of feature support to the engine, to support more different user made campaigns and scenarios.

A key part of Wesnoth's success is in keeping an open mind. No single developer, least of all me, has been able to consistently and accurately predict what is fun and what isn't. Instead, by developing a flexible platform that allows people to develop scenarios and campaigns on, users can make content which proves to be fun, or not. Our community has done an excellent job of creating fun content that I never imagined possible.

We want to continue doing this. We want to make our engine more and more flexible, little by little. We want to take 'fringe elements' -- dramatically different gameplay styles that were only supportable by bizarre and convoluted WML -- and make the engine support them better.

We have many plans for a variety of features to allow this. A better WML engine. A more flexible AI engine that will allow much greater customization.

However, the core Wesnoth team does not intend to migrate Wesnoth to a fundamentally different play stle. But, that said, I think it would be a great idea for *someone* to. We have an excellent set of resources: great art, a good code base, and so forth. These resources could be re-used to make a 'civilization-style' hex game. Or a 'tactics' game (Wesnoth is already somewhat of a tactics game, but one could take this in different directions). Or more of a 'wargame'. For someone to do this would be excellent. If another great FLOSS game could be created with Wesnoth's resources, that would be great for the FLOSS gaming community. I, personally, would love to play such a game. :)

Something else we want to address going forward is Wesnoth's performance. Wesnoth was originally created using an approach that was easy to develop with, but placed performance, in terms of time and space, as a secondary concern. It is still easily runnable on most desktop machines, but it doesn't run well on smaller devices. We have several developers who are highly committed to making Wesnoth run well on small devices. We plan to work hard on this, and make this happen.

Finally, I think the best thing about Wesnoth is its community. I feel we should continue to foster and grow the community. We have recently had a "Wesnoth Conference" at FOSDEM, which ten Wesnoth developers and contributors attended. It would be excellent if we could organize such a thing again, perhaps on a larger scale.

That said, I personally feel that attempting to raise money to fund such a thing is entirely within the spirit of the FLOSS community. We could, for instance, consider using (unintrusive) ads on our website to raise money, and then organize a conference, funding it with the money (including paying subsidies to anyone wanting to come, to help pay for their expenses).

I must admit, that even after Wesnoth got 'off the ground', I was at times concerned about its chances of reaching a credible 1.0. Later I was concerned about its direction thereafter, especially with me becoming less involved with the project. I have been incredibly impressed by the development team and the community which has done an excellent job in developing Wesnoth. I am now very confident in Wesnoth's future.

== See Also ==
* [[FrequentlyProposedIdeas]]
* [http://www.wesnoth.org/forum/viewtopic.php?t=441 The History of, and Philosophy behind Wesnoth]
* [http://www.wesnoth.org/forum/viewtopic.php?t=2190 Wesnoth Philosophy II: Where Next?]

CodingStandards

2008-02-24T16:16:21Z

Dave: /* Naming */

Wesnoth uses modern/advanced C++ that is portable to Visual C++ 6 and GNU G++ 3.0+

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil Evil Things To Avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class 'explicit'.

Do not use operator T() where T is a type to allow an implicit conversion to a different type.

Example:

t_string(const std::string&);

This is very evil! It can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly.

=== Do not use non-private data members of classes ===

It's okay to have a struct with all-public members, if that's what you want.

However, once something is a class, with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

== Naming ==

=== End Non-Public Members of Classes with an Underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a
class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use References when a value may not be NULL ===

If a value passed to a function can never be NULL, use a reference instead of a pointer. I.e.

void myfunction(Object& obj);

rather than

void myfunction(Object* obj);

This more clearly shows the user of the function that obj may never be NULL,
without them having to consult documentation or the implementation of the function.

=== Use Const ===

The 'const' feature of C++ allows interfaces to more clearly specify how they treat objects.
Always use const when you are not going to modify an object.

I.e.

void myfunction(const Object& obj);

demonstrates to the caller of myfunction() that obj will not be modified.
If myfunction may modify obj, then use

void myfunction(Object& obj);

likewise, if a variable is not changed after initialization, make it const.

=== Write Exception-Safe Code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly.
That is, you should be able to assume that an exception is thrown almost anywhere
from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like,

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

is bad, because the code may throw an exception, and 'image' will never be freed.
Instead, use wrapper objects which free the object in their destructor.

For SDL_Surface objects, use the <tt>surface</tt> class.
So you could rewrite the above code,

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using new[] or malloc(),
use language-provided containers, such as vector.

=== Do not use sprintf ===

Sprintf does not check whether or not it is writing past the end of the space allocated.
This is a security problem if someone other than the person running the game
can cause sprintf to write very long strings.
In Wesnoth this untrusted data could come potentially from other players
in a multiplayer game or from downloaded campaigns.
Instead you should use snprintf with the second argument being sizeof of the buffer
that will hold the result.

== Standard C++ to avoid ==

=== Respect for loop scoping of different platforms ===

In the code,

for(int i = 0; i != 100; ++i) {...}

the variable 'i' is scoped within the for loop according to ISO/ANSI C++ and GNU G++.
However it is scoped within the surrounding scope according to Visual C++ 6.

This means that the code,

for(int i = 0; i != 100; ++i) {}
for(int i = 0; i != 100; ++i) {}

is illegal on VC++6, because i is defined twice,
although it is legal according to the standard, and GNU G++.

On VC++6, the legal way to write it would be,

for(int i = 0; i != 100; ++i) {}
for(i = 0; i != 100; ++i) {}

But this is illegal according to the standard, because 'i' is not defined in the second loop.
The correct way to write this code to conform to the standard and work on all platforms
is to simply abandon declaring variables in the initialization statement of a for loop
when the variable must be reused in the same scope,

int i;
for(i = 0; i != 100; ++i) {}
for(i = 0; i != 100; ++i) {}

=== Do not use wstring ===

The standard C++ wstring class, defined as a basic_string< wchar_t >,
does not exist in some platforms supported by Wesnoth.
Use wide_string, defined in language.hpp, instead.
wide_string is actually defined as a vector< wchar_t >

== C legacy to be avoided ==

=== Use the function templates minimum and maximum ===

Standard C++ offers the function templates min and max to find the minimum and maximum
of two values on which operator
<
is defined.
Unfortunately, many hoops must be leapt through to get this working on VC++.
So, we do not use standard min and max.
Instead, we use minimum and maximum, defined in utils.hpp.

Usage is fairly natural:

int i = minimum(x,y);

Note that in the above example, if x is an unsigned integer, and y is a signed integer,
VC++ will have problems.
You must explicitly specify the version of minimum being called in such cases:

int i = minimum<int>(x,y);

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly.
Use util::array defined in array.hpp.
It is a wrapper for an array which has a C++ container-style interface.
If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler generated combination of static_cast, reinterpret_cast, and const_cast).

Good programming style is to use the least powerful tool available that does what you want.
For example,

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-builtin types.

Note: there may be some obscure cases where a C-style cast is desirable,
such as converting a pointer to an integer type of unspecified size.

== Documentation ==

=== Document "config" preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container known as the "config",
which contains heirarchical string data (such as WML contents or game settings).
The tagged "children" of the config and their string "attributes" are arranged
in an ordered and mapped format internally using STL.

Because config data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. You should document all public functions that take/return a config, specifying config content expectations (and updating any related entries in the [[ReferenceWML]] wiki pages).
In particular, if your function requires a config parameter, specify where/how the config should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===
See [[Doxygen]] for tips on how to comment the code,
so that doxygen can nicely document it.

== See also ==
* [[HackingWesnoth]]

[[Category:Committers]]

StartingPoints

2008-01-28T01:00:53Z

Dave: /* Developer information */

__NOTOC__

What would you like to learn about Wesnoth in this wiki? [[Play]] it, [[create]] with it, [[support]] for it, [[project]] resources about it, [[credits]] of it.

This is a page with starting points to exploring this wiki about The Battle for Wesnoth. In addition to the wiki, there's also a [http://www.wesnoth.org homepage], a [http://www.wesnoth.org/forum forum], and a [http://gna.org/projects/wesnoth/ Gna project page].

* [[Special:Categories|List of all page categories in this wiki]]
* [[Special:Allpages|List of all pages in this wiki]]

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinaries]] - precompiled for GNU/Linux, BeOS, PDAs, ...
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [[CompilingWesnoth]] - on Unix, Mac, Windows, GNU/Linux, PDAs, ...
* [[UsingSourceinstall]] - using GNU Source Installer to automate installation and upgrades from source (Unix-likes only)
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems
* [[WesnothOnLinuxPDAs]] - on the Qtopia/OPIE and thepdaXrom/Zaurus C series

== Playing the Game ([[Play]]) ==

==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineScenarios]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online
* [[Replays]] - archive of replays new and old

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [[ServerAdministration]] - commands that authenticated users can use to administer the server
* [http://zapicm.freeshell.org Units] - Units advancement trees and stats
** [http://zapicm.freeshell.org/dev Development version]
** [http://zapicm.freeshell.org/stable Stable version]
** [http://server.wesnoth.org/~wesnoth/trunk Trunk version]
* [[RaceDescriptions]] - Elves, Humans, Dwarves, Orcs, Drakes, Undead, Others
** [[Complete_Faction_List_%28unfinished%29]] - list all user made factions
* [[WesnothAcronyms|Wesnoth Acronyms (by category)]] - common wesnothian acronyms explained
* [[WesnothAcronyms(alphabetic)|Wesnoth Acronyms (alphabetic)]] - common wesnothian acronyms explained

== Tweaking the Game ([[Create]]) ==
==== Scenarios & Campaigns ====
* [[UserScenarios]] - user-written scenarios, campaigns and game modifications
* [[BuildingCampaigns]] - how to make your own single player campaigns
* [[MultiplayerCampaigns]] - how to make your own multiplayer campaigns
* [[BuildingScenarios]] - how to make your own scenarios
* [[BuildingUnits]] - how to make your own units
* [[UnitAnalysis]] - tool to analyze units
==== References ====
* [[ReferenceWML]] and [[AlphabeticalWML]] - all about Wesnoth Markup Language
* [[ReferencePythonAPI]] - upcoming Python interface for AI
==== Tools & Utilities ====
* [[ExternalUtilities]] - scripts to help create scenarios, campaigns, and graphics
* [[WesnothMapEditor]] - summary of controls
==== Art related ====
* [[Create_Art#Art_Tutorials|Art Tutorials]] - help in creating art
* [[GraphicLibrary]] - unit and terrain images posted on the forums
* [[Tiles_Status]] - terrain tiles: proposed and in progress.

== Improving the Game ==
* [[ReportingBugs]] - use Gna!
* [http://www.wesnoth.org/wiki/ReportingBugs#Guidelines_for_suggesting_features Guidelines for suggesting features] - To submit a feature request, use http://bugs.wesnoth.org
==== Developer information ====
* [[DeveloperResources]] - useful links
* [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothSVN]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[DeveloperGuide]] - for those who received SVN commit rights
* [[UnitDescriptionRewriting]] - coordinating the revision
* [http://wesnoth.slack.it/missing.cgi Missing unit animations and sounds] - what's available and what's missing
* [[WritingYourOwnAI]] - write a C++ plugin
* [[WesnothFormulaAIBranch]] - Guide to the experimental formula AI branch
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* [[WesnothPreferences]]
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[WesnothGL]] - Guide to programming the Wesnoth OpenGL branch

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - completely unknown stats...
* [[WesCamp]] - a project for translating user-made campaigns

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[WesnothHistory]] - the Ages of Wesnoth
* [[WesnothGeography]] - description of Wesnoth and surrounding lands
* [[WesnothFigures]] - notable figures of valorous and infamous deeds in Wesnoth
* [[WesnothReviews]] - third party reviews of Wesnoth
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel
* [[Donate]] or [http://cafepress.com/wesnoth buy Wesnoth merchandise].
* [[Trailer]] - the Wesnoth trailer

== Other ==
* [[UsefulLinks]]
* [[WesnothLSM]] - presentation at LSM
* [http://wesnoth.slack.it/?WesnothPlayerMap Map of Wesnoth player locations] - add yourself to the map!
* [http://en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiHaiku]]

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki
* [[WikiMigration]] - we were looking for a replacement for our old wiki (and ended up using Mediawiki)
* [http://www.wesnoth.org/forum/viewtopic.php?t=19462 Obsolete] - help in updating the wiki for v1.4

Fosdem2008

2007-12-23T20:19:38Z

Dave:

== General information ==
* Fosdem - http://fosdem.org/2008/
* Dave's talk (not scheduled yet) - http://fosdem.org/2008/schedule/events/240

== Schedule/Plans ==

{| border="1" width="100%"
|-
!
! Arrival
! Departure
! Accomodation
|-
| ettin
| 22, 9:15 (BRU)
| 24, 15:25 (BRU)
| Bruegel YH or CHAB
|-
| Ivanovic
| 22, lunchtime
| 25, lunchtime
| CHAB or *whatever*
|-
| David & Lisa
| 18, morning
| 25, morning
| Novotel Grand Place
|}

2005-09-27T22:37:59Z

Dave: /* Compiling */

__NOTOC__
Battle for Wesnoth is a turn-based fantasy strategy game.

Defeat all enemy leaders using a well-chosen cadre of troops,
taking care to manage your resources of gold and villages.
All units have their own strengths and weaknesses; to win,
deploy your forces to their best advantage while
denying your foes the chance to do the same. As units gain
experience, they acquire new abilities and become more
powerful. Play in your own language and test your skill
against a smart computer opponent, or join Wesnoth's large
community of on-line players.
Create your own custom units, scenarios or campaigns,
and share them with others.

Battle for Wesnoth is released under the
[http://www.gnu.org/licenses/licenses.html#GPL GPL].
Prebuilt packages are available for most operating systems,
including Windows, Mac OS X, and GNU/Linux, or you can build
your own from source code.

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinaries]] - precompiled for GNU/Linux, BeOS, PDAs, ...
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [[CompilingWesnoth]] - on Unix, Mac, Windows, GNU/Linux, PDAs, ...
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems
* [[WesnothOnLinuxPDAs]] - on the Qtopia/OPIE and thepdaXrom/Zaurus C series

== Playing the Game ==
==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineScenarios]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [http://wesnoth.slack.it/units.cgi Units] - Units stats and advance trees
** [http://wesnoth.slack.it/units.cgi?page=frames Wesnoth Unit List]
** ([http://wesnoth.slack.it/units.cgi?page=list without frames])
** [http://wesnoth.slack.it/units.cgi Experience Tree]
** [http://wesnoth.slack.it/units.cgi?factions Factions]
** [http://wesnoth.slack.it/units.cgi?movetypes Movement, defense and resistance tables]
* [[RaceDescriptions]] - Elves, Humans, Dwarves, Orcs, Drakes, Undead, Others
* [[GraphicLibrary]] - unit and terrain images posted on the forums
* [[WesnothAcronyms|Wesnoth Acronyms (by category)]] - common wesnothian acronyms explained
* [[WesnothAcronyms(alphabetic)|WesnothAcronyms (alphabetic)]] - common wesnothian acronyms explained

== Tweaking the Game ==
* [[UserScenarios]] - user-written scenarios, campaigns and game modifications
* [[ReferenceWML]] - all about Wesnoth Markup Language
* [[BuildingCampaigns]] - how to make your own campaigns
* [[BuildingScenarios]] - how to make your own scenarios
* [[WesnothMapEditor]] - summary of controls
* [[CastleTutorial]] - how to create tileable castles and other castle-like tilesets
* [[ExternalUtilities]] - scripts to help create scenarios, campaigns, and graphics

== Improving the Game ==
* [[ReportingBugs]] - use Savannah
==== Developer information ====
* [[DeveloperResources]] - useful links
* [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothCVS]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[UnitDescriptionRewriting]] - coordinating the revision
* [http://wesnoth.slack.it/missing.cgi Missing unit animations and sounds] - what's available and what's missing
* [[WritingYourOwnAI]] - write a C++ plugin
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* [[WesnothPreferences]]

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - 11 complete, 2 almost complete, 7 more than halfway, 10 partial
* [[WesCamp]] - a project for translating user-made campaigns

==== Ideas ====
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
* [[NewUnits]] - units that exist only in theory
* [[NewTerrains]] - tile status
* To submit a feature request, use http://bugs.wesnoth.org

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[WesnothHistory]] - the Ages of Wesnoth
* [[WesnothGeography]] - description of Wesnoth and surrounding lands
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel

== Other ==
* [[UsefulLinks]]
* [[WesnothLSM]] - presentation at LSM
* [http://wesnoth.slack.it/?WesnothPlayerMap Wesnoth player's map] - add yourself to the map!
* [http://en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiMigration]] - we are looking for a replacement

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki

HackingWesnoth

2005-09-04T22:18:57Z

Dave: /* C++ Quiz */

= Overview =

This page is designed to be a guide for aspiring Wesnoth programmers on what they need to do to be able to productively contribute to the Wesnoth code base.

Wesnoth is written in C++, a large and complicated language. There are many C++ programmers, but they tend to have widely varying levels of skills and styles. This page is designed to be a guide as to the skillset needed to contribute to Wesnoth.

= C++ Quiz =

Below is a short C++ quiz that assesses your skills in areas of C++ that are used alot in Wesnoth. If you know all the answers to the questions, you are probably ready to start working on the Wesnoth code base. If you know most of the answers to the questions, you can probably work on the Wesnoth code base with some oversight from the senior developers.

(1) What is a virtual destructor? Why is it needed?

(2) What does the standard class template auto_ptr do? What is its purpose?

(3) What is a vector, and why would you use it?

(4) What is a map, and why would you use it?

(5) What are the differences between a reference and a pointer? When should each be used?

(6) What is an iterator, and when is it used?

(7) What are the memory areas in a C++ program, and what is the purpose of each?

(8) What is a copy constructor, and what is an assignment operator? When must you define them in a class?

= Wesnoth Coding Style =

== Guideline 1: Don't prematurely optimize ==

When I was a new and inexperienced coder, I read the following rather famous saying: "Premature optimization is the root of all evil." -- Donald Knuth.

While I wouldn't then -- and would be hesitant to now -- dispute the opinion of Donald Knuth on any programming topic, this absolute statement confused me. Premature optimization certainly doesn't sound like a wise thing to do, but it sounds somewhat obscure to be the root of all problems in programming. Had Knuth written this phrase after spending too long correcting problems caused by a programmer who was hell-bent on optimization at every turn?

Now I realize that Knuth was correct. Time and time again programming problems spring from developers making their code too complicated because they are trying to optimize unnecessarily.

By the [http://en.wikipedia.org/wiki/Pareto_principle Pareto Principle] we know that a minority of the code will occupy a majority of the running time. That is, perhaps 90% of the running time of the program will be spend executing just 5% of the code. It is thus generally unnecessary to apply many optimizations at all to most of the program. One can just write the code in a way that is the most readable and maintainable and forget about optimization altogether most of the time.

Remember also, C++ compilers are good, and smart, and they can execute code fast. Most code will run fast enough, unless you go out of your way to make it run slowly.

So, the first rule of Wesnoth programming is that unless you have a very good reason to think you need to optimize, do whatever is simplest and most maintainable.

Many programmers seem to have an obsession with using the control C++ gives them to do all sorts of crazy things. Like make their own memory management routines, or write their own containers, and so forth. Simply, don't. It's possible to write good C++ code very fast using the standard components supplied as part of the language.

This leads us to our next topic...

== Guideline 2: Know the Standard containers and use them ==

One of the best things about C++ is that the standard supplies some great containers. Always prefer to use them first to store data. That is,

- prefer to use std::vector to store dynamic arrays
- prefer to use std::string to store strings (we also provide t_string for a translatable string -- it's based on std::basic_string, which std::string is also based on)
- prefer to use std::map to store key/value pairs
- prefer to use std::set to store sets of items (roughly equivalent to the mathematical concept of a set).

There are other C++ containers, and you should know about all of them. A good source of documentation on the portion of the C++ standard library known as the Standard Template Library (STL) which contains the standard containers can be found [http://www.sgi.com/tech/stl/ here].

By using the standard containers, you should almost never have to manually allocate and delete memory yourself by hand. The containers will automatically allocate and deallocate memory for you. This leads us to our next guideline...

== Guideline 3: Use the resource acquisition is initialization (RAII) idiom ==

In C, you might write some code like this:

<nowiki>
void myfunction()
{
char* mystring = (char*)malloc(n);
/*some code, which manipulates mystring*/
...
free(mystring);
}
</nowiki>

This code works, but is error prone. What if the code in the middle exited using a return statement, or a longjmp statement, or in C++, threw an exception? The memory allocated would never be cleaned up, and we would have a memory leak.

Sure, you're a good programmer, and you probably make sure you're very careful about freeing the string. But what about when this function grows to be 100 lines long (and functions have a way of doing that), and then another programmer who isn't that familiar with the function is trying to fix a critical bug as quickly as they can, that requires adding an early return statement to this function? What about when someone is trying to read the code to scan for memory leaks? Once they see the malloc at the top, they will have to carefully read the entire function, to make sure it's all okay.

Now if we had this C++ version instead,

<nowiki>
void myfunction()
{
std::string mystring(n,'x');
/*some code, which manipulates mystring*/
} //mystring is destroyed and memory automatically released
</nowiki>

None of these problems can possibly happen. mystring will ''always'' be released at the end of the function.

So, this just re-iterates how important C++ containers are, right? Well, yes, but it also shows us that we should always avoid code written like this:

<nowiki>
void myfunction()
{
...allocate resources...
...use resources
...release resources...
}
</nowiki>

If you have code like this, you should put the resources in a class that will manage them and release them at the end of the function. If there is no class like that, then you should write one. This goes for all resources: memory, files, threads, and so forth.

It might sound like a silly mistake that we're protecting against here, one that an experienced programmer wouldn't make. However, almost all programming bugs are due to 'silly mistakes'. This leads us to our next item...

== Guideline 4: Lean on the compiler as heavily as you can ==

Humans make mistakes. Even very stupid mistakes. Computers are as dumb as toast, but they are at least very very consistent.

For Wesnoth, we try to write code that will make the compiler guard against mistakes as much as possible. The use of RAII as described above is one example of this: writing the code so the compiler and language rules will guarantee it's correct.

There are some more ways to do this. One big way is to make all code const correct. That is, always define something as 'const' when it shouldn't change its value. If you have a pointer that is meant to be read only, define it as a const pointer. Then if the code is later changed so that your pointer changes the value, the compiler will produce an error.

Another way is to avoid implicit conversions between objects, and always use the C++-style casts.

HackingWesnoth

2005-09-04T22:18:25Z

Dave:

= Overview =

This page is designed to be a guide for aspiring Wesnoth programmers on what they need to do to be able to productively contribute to the Wesnoth code base.

Wesnoth is written in C++, a large and complicated language. There are many C++ programmers, but they tend to have widely varying levels of skills and styles. This page is designed to be a guide as to the skillset needed to contribute to Wesnoth.

= C++ Quiz =

Below is a short C++ quiz that assesses your skills in areas of C++ that are used alot in Wesnoth. If you know all the answers to the questions, you are probably ready to start working on the Wesnoth code base. If you know most of the answers to the questions, you can probably work on the Wesnoth code base with some oversight from the senior developers.

(1) What is a virtual destructor? Why is it needed?
(2) What does the standard class template auto_ptr do? What is its purpose?
(3) What is a vector, and why would you use it?
(4) What is a map, and why would you use it?
(5) What are the differences between a reference and a pointer? When should each be used?
(6) What is an iterator, and when is it used?
(7) What are the memory areas in a C++ program, and what is the purpose of each?
(8) What is a copy constructor, and what is an assignment operator? When must you define them in a class?

= Wesnoth Coding Style =

== Guideline 1: Don't prematurely optimize ==

When I was a new and inexperienced coder, I read the following rather famous saying: "Premature optimization is the root of all evil." -- Donald Knuth.

While I wouldn't then -- and would be hesitant to now -- dispute the opinion of Donald Knuth on any programming topic, this absolute statement confused me. Premature optimization certainly doesn't sound like a wise thing to do, but it sounds somewhat obscure to be the root of all problems in programming. Had Knuth written this phrase after spending too long correcting problems caused by a programmer who was hell-bent on optimization at every turn?

Now I realize that Knuth was correct. Time and time again programming problems spring from developers making their code too complicated because they are trying to optimize unnecessarily.

By the [http://en.wikipedia.org/wiki/Pareto_principle Pareto Principle] we know that a minority of the code will occupy a majority of the running time. That is, perhaps 90% of the running time of the program will be spend executing just 5% of the code. It is thus generally unnecessary to apply many optimizations at all to most of the program. One can just write the code in a way that is the most readable and maintainable and forget about optimization altogether most of the time.

Remember also, C++ compilers are good, and smart, and they can execute code fast. Most code will run fast enough, unless you go out of your way to make it run slowly.

So, the first rule of Wesnoth programming is that unless you have a very good reason to think you need to optimize, do whatever is simplest and most maintainable.

Many programmers seem to have an obsession with using the control C++ gives them to do all sorts of crazy things. Like make their own memory management routines, or write their own containers, and so forth. Simply, don't. It's possible to write good C++ code very fast using the standard components supplied as part of the language.

This leads us to our next topic...

== Guideline 2: Know the Standard containers and use them ==

One of the best things about C++ is that the standard supplies some great containers. Always prefer to use them first to store data. That is,

- prefer to use std::vector to store dynamic arrays
- prefer to use std::string to store strings (we also provide t_string for a translatable string -- it's based on std::basic_string, which std::string is also based on)
- prefer to use std::map to store key/value pairs
- prefer to use std::set to store sets of items (roughly equivalent to the mathematical concept of a set).

There are other C++ containers, and you should know about all of them. A good source of documentation on the portion of the C++ standard library known as the Standard Template Library (STL) which contains the standard containers can be found [http://www.sgi.com/tech/stl/ here].

By using the standard containers, you should almost never have to manually allocate and delete memory yourself by hand. The containers will automatically allocate and deallocate memory for you. This leads us to our next guideline...

== Guideline 3: Use the resource acquisition is initialization (RAII) idiom ==

In C, you might write some code like this:

<nowiki>
void myfunction()
{
char* mystring = (char*)malloc(n);
/*some code, which manipulates mystring*/
...
free(mystring);
}
</nowiki>

This code works, but is error prone. What if the code in the middle exited using a return statement, or a longjmp statement, or in C++, threw an exception? The memory allocated would never be cleaned up, and we would have a memory leak.

Sure, you're a good programmer, and you probably make sure you're very careful about freeing the string. But what about when this function grows to be 100 lines long (and functions have a way of doing that), and then another programmer who isn't that familiar with the function is trying to fix a critical bug as quickly as they can, that requires adding an early return statement to this function? What about when someone is trying to read the code to scan for memory leaks? Once they see the malloc at the top, they will have to carefully read the entire function, to make sure it's all okay.

Now if we had this C++ version instead,

<nowiki>
void myfunction()
{
std::string mystring(n,'x');
/*some code, which manipulates mystring*/
} //mystring is destroyed and memory automatically released
</nowiki>

None of these problems can possibly happen. mystring will ''always'' be released at the end of the function.

So, this just re-iterates how important C++ containers are, right? Well, yes, but it also shows us that we should always avoid code written like this:

<nowiki>
void myfunction()
{
...allocate resources...
...use resources
...release resources...
}
</nowiki>

If you have code like this, you should put the resources in a class that will manage them and release them at the end of the function. If there is no class like that, then you should write one. This goes for all resources: memory, files, threads, and so forth.

It might sound like a silly mistake that we're protecting against here, one that an experienced programmer wouldn't make. However, almost all programming bugs are due to 'silly mistakes'. This leads us to our next item...

== Guideline 4: Lean on the compiler as heavily as you can ==

Humans make mistakes. Even very stupid mistakes. Computers are as dumb as toast, but they are at least very very consistent.

For Wesnoth, we try to write code that will make the compiler guard against mistakes as much as possible. The use of RAII as described above is one example of this: writing the code so the compiler and language rules will guarantee it's correct.

There are some more ways to do this. One big way is to make all code const correct. That is, always define something as 'const' when it shouldn't change its value. If you have a pointer that is meant to be read only, define it as a const pointer. Then if the code is later changed so that your pointer changes the value, the compiler will produce an error.

Another way is to avoid implicit conversions between objects, and always use the C++-style casts.