The Battle for Wesnoth Wiki - User contributions [en]

CodingStandards

2007-07-04T03:35:00Z

TuukkaH: add Category:Programmers Category:Committers

Wesnoth uses modern/advanced C++ that is portable to Visual C++ 6 and GNU G++ 3.0+

== Formatting ==

Indent with a tab character (width 4 characters), but align with spaces so tab width can change.

You may use long lines. (Could we change this to max 80 columns per line? --TuukkaH)

=== How to on Emacs? ===

M-x set-variable tab-width 4
M-x set-variable c-basic-offset 4

How to set alignment to use spaces?

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

== See also ==

* [[HackingWesnoth]]

[[Category:Programmers]]
[[Category:Committers]]

Project

2007-07-04T03:33:59Z

TuukkaH: add Category:Programmers Category:Committers

The Battle for Wesnoth is a [http://gna.org/projects/wesnoth/ Gna! project]. See also the [http://freshmeat.net/projects/wesnoth/ project] and [http://freshmeat.net/project-stats/view/38720/ stats] at [http://www.freshmeat.net/ freshmeat].

There are also Wesnoth pages in other languages:
French ([http://tournoiswesnoth.frbb.net/ 1], [http://wesnothfr.ww7.be/ 2]),
[http://wesnoth.fw.hu/ Hungarian],
[http://wikiwiki.jp/wesnoth/ Japanese],
[http://www.wesnoth.pl/ Polish],
[http://perso.wanadoo.es/wesnoth/ Spanish].

== Artists ==
Graphic artists and musicians usually meet on the [http://www.wesnoth.org/forum/ forum].
* [http://www.wesnoth.org/forum/viewforum.php?f=9 Artwork development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=14 Music development forum]

== Developers ==
Coders can help fixing [http://bugs.wesnoth.org bugs], adding new features...
* [[CodingStandards]]
* [[Roadmap]]
* [http://devdocs.wesnoth.org/ Documentation] - generated and uploaded two times every day (05:05 and 17:05 GMT+2).
* [[WesnothSVN]]
* [[DeveloperGuide]]

== Translators ==
* [[WesnothTranslations]]
* [http://gettext.wesnoth.org Statistics]
* [[WesCamp|Translating User made Campaigns (featuring wescamp-i18n)]]

[[Category:Programmers]]
[[Category:Committers]]

HackingWesnoth

2007-07-04T03:31:58Z

TuukkaH: add Category:Programmers Category:Committers

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. There are good C++ guides for both knowledgeable programmers (such as [http://www.icce.rug.nl/documents/cplusplus/ The C++ Annotations]) and beginners (such as [http://www.cplusplus.com/doc/tutorial/introduction.html C++ Language Tutorial]).

# What is a virtual destructor? Why is it needed?
# What does the standard class template auto_ptr do? What is its purpose?
# What is a vector, and why would you use it?
# What is a map, and why would you use it?
# What are the differences between a reference and a pointer? When should each be used?
# What is an iterator, and when is it used?
# What are the memory areas in a C++ program, and what is the purpose of each?
# 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 ===

<blockquote>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.</blockquote>

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:

<pre>
void myfunction()
{
char* mystring = (char*)malloc(n);
/*some code, which manipulates mystring*/
...
free(mystring);
}
</pre>

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,

<pre>
void myfunction()
{
std::string mystring(n,'x');
/*some code, which manipulates mystring*/
} //mystring is destroyed and memory automatically released
</pre>

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:

<pre>
void myfunction()
{
...allocate resources...
...use resources
...release resources...
}
</pre>

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.

== See also ==
* [[CodingStandards]]
* [http://www.wesnoth.org/forum/viewtopic.php?t=9979 Patch guidelines]
* [http://www.wesnoth.org/forum/viewtopic.php?t=13878 Lack of code documentation]

[[Category:Programmers]]
[[Category:Committers]]

DeveloperGuide

2007-07-04T03:29:39Z

TuukkaH: add Category:Committers

* setting up developer SVN access: https://gna.org/svn/?group=wesnoth
* Keep the commit easy to revert if need be
* no huge commit (hard to review), so when possible maybe split it in working part with info about where you are going
* be on #wesnoth-dev IRC channel and coordinate with other developers
* code should compile and work after commit
* Don't mess with the art or music without approval from one of the art and music people.
* clear commit message (can be several lines)
* mention "bug #1234" in the commit message for automatic cc to that gna bug number
* don't forget changelog
* change status of fixed bugs to "Fixed" when committed
* change status of fixed bugs to "Closed" when released (as stable or devel version)
** if the bug is svn only (something that was existing as bug in svn but in no release) you can directly close the bug after fixing it
* register to commit mailing list: https://mail.gna.org/listinfo/wesnoth-commits
** or get the list moderator to approve commit messages from you otherwise
* don't forget http://www.wesnoth.org/wiki/EasyCoding if you're ever out of ideas :)

* threading model: SDL threads via src/thread.hpp
** synchronization model
*** avoid multi-threading code as much as possible
*** if you don't see threading code you probably don't need to learn about it

== See also ==
* [[Project#Developers]]

[[Category:Committers]]

HackingWesnoth

2007-07-04T03:15:28Z

TuukkaH: /* See also */ add links to forum about patches and comments

DeveloperGuide

2007-07-04T02:49:58Z

TuukkaH: allacrost link didn't belong here

StartingPoints

2007-07-04T02:48:04Z

TuukkaH: /* Developer information */ link new DeveloperGuide

__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, ...
* [[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

==== 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://zapicm.freeshell.org/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
* To submit a feature request, use http://bugs.wesnoth.org
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
==== 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
* [[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)

DeveloperGuide

2007-07-04T02:43:35Z

TuukkaH: fix syntax

* setting up developer SVN access: https://gna.org/svn/?group=wesnoth
* Keep the commit easy to revert if need be
* no huge commit (hard to review), so when possible maybe split it in working part with info about where you are going
* be on #wesnoth-dev IRC channel and coordinate with other developers
* code should compile and work after commit
* Don't mess with the art or music without approval from one of the art and music people.
* clear commit message (can be several lines)
* mention "bug #1234" in the commit message for automatic cc to that gna bug number
* don't forget changelog
* change status of fixed bugs to "Fixed" when committed
* change status of fixed bugs to "Closed" when released (as stable or devel version)
** if the bug is svn only (something that was existing as bug in svn but in no release) you can directly close the bug after fixing it
* register to commit mailing list: https://mail.gna.org/listinfo/wesnoth-commits
** or get the list moderator to approve commit messages from you otherwise
http://www.allacrost.org
* don't forget http://www.wesnoth.org/wiki/EasyCoding if you're ever out of ideas :)

* threading model: SDL threads via src/thread.hpp
** synchronization model
*** avoid multi-threading code as much as possible
*** if you don't see threading code you probably don't need to learn about it

== See also ==
* [[Project#Developers]]

DeveloperGuide

2007-07-04T02:42:07Z

TuukkaH: gathered hints from irc discussions

* setting up developer SVN access: https://gna.org/svn/?group=wesnoth
* Keep the commit easy to revert if need be
* no huge commit (hard to review), so when possible maybe split it in working part with info about where you are going
* be on #wesnoth-dev IRC channel and coordinate with other developers
* code should compile and work after commit
* Don't mess with the art or music without approval from one of the art and music people.
* clear commit message (can be several lines)
* mention "bug #1234" in the commit message for automatic cc to that gna bug number
* don't forget changelog
* change status of fixed bugs to "Fixed" when committed
* change status of fixed bugs to "Closed" when released (as stable or devel version)
* if the bug is svn only (something that was existing as bug in svn but in no release) you can directly close the bug after fixing it
* register to commit mailing list: https://mail.gna.org/listinfo/wesnoth-commits
* or get the list moderator to approve commit messages from you otherwise
http://www.allacrost.org
* don't forget http://www.wesnoth.org/wiki/EasyCoding if you're ever out of ideas :)

* threading model: SDL threads via src/thread.hpp
* synchronization model
* avoid multi-threading code as much as possible
* if you don't see threading code you probably don't need to learn about it

== See also ==
* [[Project#Developers]]

Project

2007-07-04T02:40:37Z

TuukkaH: /* Developers */ link new DeveloperGuide

StartingPoints

2007-07-04T01:57:32Z

TuukkaH: rewrite the intro now that this is StartingPoints

__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, ...
* [[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

==== 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://zapicm.freeshell.org/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
* To submit a feature request, use http://bugs.wesnoth.org
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
==== 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
* [[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]]
* [[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)

StartingPoints

2007-07-04T01:40:55Z

TuukkaH: link Special:Categories and Special:Allpages

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

* [[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, ...
* [[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

==== 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://zapicm.freeshell.org/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
* To submit a feature request, use http://bugs.wesnoth.org
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
==== 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
* [[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]]
* [[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)

CodingStandards

2007-07-04T01:04:53Z

TuukkaH: group under sections, add Formatting and See also

HackingWesnoth

2007-07-03T22:07:25Z

TuukkaH: /* C++ Quiz */ add links to tutorials

FAQ

2005-12-13T20:56:38Z

TuukkaH: /* Multiplayer */

=Frequently Asked Questions=

== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a fantasy turn-based strategy game.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute.

===How to get informed about new releases?===
Subscribe to new releases at [http://freshmeat.net/subscribe/38720/?url=%2Fprojects%2Fwesnoth%2F Freshmeat].

===A new version is out, but where is the download for [Windows, Mac OS, etc.]?===
The downloads are NOT part of the official project. The BFW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times) Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are always notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why does Wesnoth not have my favorite feature?===
Because we are building this game for ourselves and for our preferences, not for you. If you like the game as we like it - that is good. If you hate the game - that is also fine.
So what is the point of asking for ideas? Because the developers are just common people, although we come up with many ideas, our players certainly do as well, and often ones we don't think of ourselves. If a player comes up with an idea we like - we might implement it. Not because you asked for it - we do it because we like the feature.
At the moment there will be no features added because of the feature freeze in preparation for the release of v1.0. But after the release, there will be many new things again.
You are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL], to build the game that you like. Don't expect us to build that game for you. Building this game is our hobby, not our profession - you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project Project]
* share your point of view at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [irc://irc.wesnoth.org/wesnoth IRC]
* report bugs you find at [[ReportingBugs]]
* update the wiki
* play against us via the Multiplayer menu
* vote for Wesnoth at your favorite gaming web site
* Spread the word!

=== What are the system requirements? ===

We are not completely certain, but an x86 running at 600MHz with 128MB RAM should be adequate. Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat animations via the "Show Combat" option on the Advanced tab. You can try turning off halos and combat results, but this might make gameplay more difficult.

=== Post more questions here ===

Is there an FTP YaST repository?

You would have better luck with this on the forum. It isn't a very frequent question, and those with the answer would be more likely to be there rather than here.

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]], which is also distributed as a PDF file. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it gains 100 experience it gains 3 hitpoints. It does not heal when this happens. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advanced units that have reached their maximum level.

If the unit in question is the Necrophage, this is not a bug. The Necrophage eats the corpses of the dead, allowing it to periodically completely heal. Leveling into itself is how this is carried out.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZOC). IF an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZOC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZOCs.

=== How can I see where an enemy unit can move next turn? ===

During you turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing negative random events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. Wesnoth has been deliberately designed so that the streaks of "bad" and "good" luck are part of the gameplay.

Note that saving your game right before a combat, and restoring and trying again, will often generate the same result. This is expected, because the random number generator is "seeded".

Since Wesnoth is GPLed, it is possible that, after the 1.0 release, a new development team will "fork" the source and produce a version more like Heroes of Might & Magic, with no randomness. Until then, don't charge with your horsemen against rock trolls at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

=== Post more questions here ===

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineScenarios]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== Are there any tools to help me create maps and scenarios? ===
Yes, there is a tool called wesnoth_editor. It is a normal map-editor that should be a good help for creating the plain maps. For creating the scenarios there already is a scenario-editor included in the mac build. But this editor is rather outdated and it exists only for MacOS X. At the moment some community members are working on creating a nice and working scenario editor. You can have a look at the [http://www.wesnoth.org/forum/viewtopic.php?t=6925 forum post] about this tool. You will also find more info at [[CampGen]].

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns...". This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns. If you are behind a firewall you may not be able to connect the the campaign server; in this case try contacting the author of the campaign via the forums to see if there is another way you can get the campaign.

=== I already created a campaign and published it on the campaign server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a multiplayer scenario file. There are more details on the [[BuildingMaps|maps]] page.

=== Post more questions here ===

== Multiplayer ==

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the irc channel dedicated to mp: #wesnoth-mp at irc.freenode.net.
You can also join #wesnoth at irc.freenode.net.

===How can I make my computer into a dedicated Wesnoth server?===

===Which versions of Wesnoth can play together?===

== Translations ==

===I selected an asian translation and am not able to see the letters correctly. What happend?===

Since the size of the necessary fonts is too large, you'll need to download them separately (if you don't already have them). After that, simply copy the font to the '''fonts/''' directory in your wesnoth installation.
* Chinese font: [ftp://cle.linux.org.tw/pub/fonts/ttf/unicode/Arphic/gkai00mp.ttf gkai00mp.ttf]
* Japanese font: [http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/sqs-xml/sqs-font/sazanami-gothic.ttf sazanami-gothic.ttf]

If you got futher questions have a look at [[WesnothAsianLanguages|this]] page.

=== Post more questions here ===