The Battle for Wesnoth Wiki - User contributions [en]

PblWML

2010-08-29T14:06:07Z

Nlmdejonge: /* type */ A _lot_ of people use scenario_mp when their add-on contains multiple scenarios.

{{WML Tags}}

To upload an add-on you have made, you need a .pbl file.

This is a file with name '''data/add-ons/''addon-name''.pbl'''. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]

When you upload a add-on, the file '''data/add-ons/''addon-name''.cfg'''
and the directory '''data/add-ons/''addon-name''/''' will be published. Alternatively, '''data/add-ons/''addon-name''.cfg''' can be replaced with '''data/add-ons/''addon-name''/_main.cfg.cfg'''. Your add-on must be based entirely on these paths.

Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.

== What goes into a .pbl file? ==

'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''

The following keys are recognized for .pbl files:

=== icon ===
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and not a custom one. A custom file will work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.

: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctionWML]] to recolor it.

=== title ===
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.

=== version ===
: Displayed to the right of the title, it is just text. However, starting with Wesnoth 1.6, the ''required'' format is x.y.z where x, y and z are numbers and a value for x greater than 0 implies the add-on is complete feature-wise. Trailing non-numeric elements are allowed, but nothing should appear ''before'' the numbers. This is necessary for the ''Update add-ons'' button to work correctly. ([[#Version Key Examples|See Examples]])

=== author ===
: Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to all of their names.

=== passphrase ===
: Not displayed, it prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.

=== description ===
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.

=== dependencies ===
: An optional list of dependencies, which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])

=== translate ===
: If set to '''true''', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)

: You should make sure your add-on complies with some very specific [[WesCamp#How_to_contribute_to_this_Project|conventions]] required to ease the process for translators.

=== type ===
: Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:

:* ''campaign'': single player campaign.
:* ''scenario'': single player scenario.
:* ''era'': multiplayer era.
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.
:* ''map_pack'': multiplayer map-pack.
:* ''campaign_mp'': multiplayer campaign.
:* ''scenario_mp'': multiplayer scenario. (See the note below.)
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
:* ''other'': The type to use when no other type fits.

'''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.

=== email ===
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is ''highly'' recommended that you provide one in case you need to be contacted about your add-on.

The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== Examples ==

=== Dependency Key Example ===

The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:

dependencies=Imperial_Era,Era_of_Myths

=== Version Key Examples ===

The following are examples of '''good''' version values:

version="1.5"

version="0.11.4"

version="0.1.4beta"

version="1.5c"

The following are examples of '''bad''' version values:

version="Beta1.5"

version="Incomplete (0.3.4)"

In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.

Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.

0.5 < 1.0

1.5 < 1.5c

1.0 < 1.0.1

1.0c < 1.0.1a

1.0.1a < 1.0.1c

1.0 Final < 1.0.1 Beta

=== Example .pbl File ===

title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"

== See Also ==

* [[ReferenceWML]]
* [[BuildingCampaignsThePBLFile]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

EditingWesnoth

2010-05-27T04:41:32Z

Nlmdejonge: /* Windows */ this section was messy, tried to clean it up/order it a bit

== Game and User Directories ==

Wherever you install the game, there will be a game data directory that contains, of course, the game's data. This directory should have the following subdirectories: data, music, sounds, and images. There are several others, but these are the important ones. In this wiki, the terms "game data", wesnoth/data, or ./data refers to the wesnoth/data directory. You normally do not need to modify these files, but you can if you want to modify a unit or something.

The user data directory allows you to add custom content without modifying the game's own files. Each OS puts its user data directory in a different place. In this wiki, "user data", ''userdata''/''subdirectory'', or (occasionally) ~wesnoth/ refer to this directory.

=== Where is my '''game''' data directory? ===

====Windows====
Usually C:\Program Files\Wesnoth\data but it will be different if you installed the game in a different location: look for the data folder in the folder where you installed the game.

====Mac OS X====
Downloaded from sourceforge: control-click on the application icon. Select "Show Package Contents." Select "Contents" then "Resources.

If you did not download from sourceforge what do you do?

Command line build: /usr/local/share/wesnoth

====Linux====
/usr/local/share/wesnoth 
From apt-get (Debian and Ubuntu) or emerge (Gentoo): /usr/share/games/wesnoth 
SUSE 10.0 (pre-installed): /usr/share/wesnoth 
Fedora 5 (Installed from yum repository RPM): /usr/share/wesnoth 
Mandriva 2006.0: /usr/share/games/wesnoth 
Slackware 12 (Installed from .tgz package at LinuxPackages.net): /usr/local/share/wesnoth 
If you don't find it, or if you use another distribution, try <code>find / -iname '*wesnoth*'</code>. (as yourself, not as superuser)

=== Where is my '''user''' data directory? ===

====Windows====
'''Before version 1.8:'''
 
* Program Files\Wesnoth\userdata

'''Version 1.8 and newer:'''
 
* in Windows XP: MyDocuments\My Games\Wesnoth1.8
* in Vista: Documents\My Games\Wesnoth1.8 or UserName\Documents\AppData\Local\VirtualStore (which may be a hidden folder)

''Note: If you don't remember where you installed the game, right click on the game's shortcut, open properties, and click on the "Find target" button, then search for the "data" folder.''

====Mac OS X====
Downloaded from sourceforge: 
*Wesnoth 1.7.x and 1.8.x: ~/Library/Application Support/Wesnoth_1.x/ 
*Earlier versions: ~/Library/Preferences/Wesnoth 
Command line build: 
*~/.wesnoth (same as Linux; see below for details)

====Linux====
~/.wesnoth 
For newer wesnoth versions it can also be ~/.wesnoth<version>. I.e. ~/.wesnoth1.6 
If unsure you can check stdout of wesnoth (run from a terminal) on startup where the used directory is mentioned.

== Game data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. These have the officially distributed campaigns and multiplayer maps. If you ever want to examine or edit one of the scenario configuration files, this is where you would go. For example, a common question is how a new player can give himself more turns or gold in scenario X. This is where you would go to do that.

Two very important directories are ./data/core/units/ and ./images. You have the ability to drop new units or images in these directories and have the game recognize them. When specifying an image for something, you do so relative to ./images.

== User Data ==
The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/campaigns - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/campaigns directory is particularly useful. A single configuration file here can selectively point to an entire subdirectory tree of units, images, sounds, scenarios, and macros. This allows you to wall off parts. Content included in the userdata units or images directories will be available globally whether you want it or not.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/campaigns directory might look like:
* ''userdata''/data/campaigns/MyCampaign/ - your campaign's directory
* ''userdata''/data/campaigns/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/campaigns/MyCampaign/scenarios
** ''userdata''/data/campaigns/MyCampaign/units
** ''userdata''/data/campaigns/MyCampaign/images
** ''userdata''/data/campaigns/MyCampaign/music
** ''userdata''/data/campaigns/MyCampaign/sounds
** ''userdata''/data/campaigns/MyCampaign/utils

{{DevFeature}} Note that in 1.7.0 and later versions, ''add-ons'' replaces ''campaigns'' for these paths.

== See Also ==

* [[Create]]

<div style="border:1px solid #5599FF; margin-top: 10px; margin-bottom: 5px; padding: 5px;">
- [[EditingWesnoth|English]] - [[Editer Wesnoth vf|Français]] -
</div>
[[Category:Create]]

MultiplayerServerWML

2010-05-25T22:33:06Z

Nlmdejonge: /* The login procedure */ added a link to HashedPasswords.pdf; file shows how hashed passwords are being generated

= Multiplayer Server WML =
This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come. Below you'll find information about what data the (unzipped) packages contain.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB).

* server response
** '''[join_lobby]''' or
** '''[error]'''
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''turn''': The current turn/max turn.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to {{DevFeature}}
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Room commands ==
Note: the room commands are in general {{DevFeature}} and are subject to change.
* '''[room_join]'''
** '''room''': The room name to join
** '''player''': (filled by server in response message sent to all room members) the player that joins the room
** '''[members]''': member list sent to the player that joined
*** '''[member]''': (repeated) members
**** '''name''': This member's name
* '''[room_part]'''
** '''room''': The room name to part (leave). Leaving the lobby is not allowed.
** '''player''': (filled by server in response message sent to all room members) the player that leaves the room
* '''[room_query]''': specific room-related queries.
** '''[rooms]''': List rooms created on the server, or
** '''[names]''': List members of a given room
*** '''room''': The room name (if applicable)
** '''[persist]''': Check or set room persistance
*** '''value''': (optional) set room persistance to this value (yes/no)
* '''[room_query_response]''': contains specific response to a room_query.
** '''message''': optional text message response
** '''room''': room name (if applicable)
** '''[rooms]''': room list
*** '''[room]''': (repeated) rooms
**** '''name''': This room's name
** '''[members]''': member list
*** '''[member]''': (repeated) members
**** '''name''': This member's name

== Nick registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[register]'''
*** '''password''': The password for the nick.
*** '''mail''': The email address for the nick.
** '''[drop]''': Drop this username.
** '''[set]''': Set a detail (e.g. email address) for this nick.
*** '''detail''': The detail, e.g. "mail".
*** '''value''': The new value for this detail, e.g. "user@edomain"
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** '''index''': The index of a user.
** '''[insert_child]''' A new user logged on.
*** '''[user]'''
**** '''name''': The name of the user.
**** '''available''' "yes"
*** '''[delete_child]''' A user logged off.
** '''[change_child]'''
*** '''[user]'''
**** '''[insert]''': A user joined/left a game.
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
***** '''location''': The name of the game the user joined.
**** '''[delete]'''
***** '''location''': "x" when a game was left.
*** '''[gamelist]'''
**** '''index''': Index of the game in question.
**** '''[insert_child]''': A game started.
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''': A game ended.
***** '''[game]'''
**** '''[change_child]''': Something changed in a game.
***** '''[game]'''
****** '''[insert]'''
******* '''slots''': The number of free slots in the form: free/max slots
******* '''turn''': The turn number in the form: current turn/max turns
****** '''[delete]'''
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game

== In-game communication ==

* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nick of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

[[Category:WML Reference]]

UsefulLinks

2010-05-14T02:29:15Z

Nlmdejonge: /* Other Links */ added WSRSW

=== Battle for Wesnoth ===
Home Page http://www.wesnoth.org/
Gna! Project Page http://svn.wesnoth.org/
Page on TheLinuxGameTome http://happypenguin.org/show?Battle%20for%20Wesnoth
Freshmeat entry http://freshmeat.net/projects/wesnoth/
Changelog http://changelog.wesnoth.org/ [http://stable-changelog.wesnoth.org stable]
This wiki http://wiki.wesnoth.org/
The manual http://manual.wesnoth.org/
Translation statistics http://gettext.wesnoth.org/
Campaign statistics http://stats.wesnoth.org/
Add-on server web interface http://addonlist.wesnoth.org/ [http://stable-addons.wesnoth.org stable] [http://dev-addons.wesnoth.org dev]
Multiplayer server statistics http://wesnothd.wesnoth.org/
http://wesnoth.yi.org/statistics/
Multiplayer replays http://replays.wesnoth.org
Unit advancement tree http://units.wesnoth.org/
http://zapicm.freeshell.org/
Forum for users and developers http://forum.wesnoth.org/ [http://forum.wesnoth.org/search.php?search_id=newposts new posts]
List of Frequently Proposed Ideas http://fpi.wesnoth.org/
IRC channel (Freenode) irc://irc.wesnoth.org/#wesnoth [http://webchat.freenode.net/?channels=wesnoth webchat]
IRC logs http://irclog.wesnoth.org/
http://www.wesnoth.org/irclogs/

=== Developers ===
SVN web interface http://websvn.wesnoth.org/
Subversion homepage http://subversion.tigris.org/
SVN book http://svnbook.org/
Code documentation http://devdocs.wesnoth.org/
Mailing lists https://gna.org/mail/?group=wesnoth
Bug/Feature tracker http://bugs.wesnoth.org/
Patch tracker http://patches.wesnoth.org/
CIA statistics http://cia.vc/stats/project/wesnoth
wesnoth.org server stats http://collectd.wesnoth.org
IRC channel (Freenode) irc://irc.wesnoth.org/#wesnoth-dev [http://webchat.freenode.net/?channels=wesnoth-dev webchat]

=== Other Links ===
1vs1 Wesnoth ladder http://ladder.subversiva.org/
Cruzan.info (a RAW map maker) http://www.cruzan.info/wesnoth
Voting on scenarios/campaigns http://www.wsrsw.org/

[[Category:Wesnoth Wiki]]

EditingWesnoth

2010-05-11T14:44:34Z

Nlmdejonge: /* Mac OS X */ and 1.8.x

== Game and User Directories ==

Wherever you install the game, there will be a game data directory that contains, of course, the game's data. This directory should have the following subdirectories: data, music, sounds, and images. There are several others, but these are the important ones. In this wiki, the terms "game data", wesnoth/data, or ./data refers to the wesnoth/data directory. You normally do not need to modify these files, but you can if you want to modify a unit or something.

The user data directory allows you to add custom content without modifying the game's own files. Each OS puts its user data directory in a different place. In this wiki, "user data", ''userdata''/''subdirectory'', or (occasionally) ~wesnoth/ refer to this directory.

=== Where is my '''game''' data directory? ===

====Windows====
Usually C:\Program Files\Wesnoth\data but it will be different if you installed the game in a different location: look for the data folder in the folder where you installed the game.

====Mac OS X====
Downloaded from sourceforge: control-click on the application icon. Select "Show Package Contents." Select "Contents" then "Resources.

If you did not download from sourceforge what do you do?

Command line build: /usr/local/share/wesnoth

====Linux====
/usr/local/share/wesnoth 
From apt-get (Debian and Ubuntu) or emerge (Gentoo): /usr/share/games/wesnoth 
SUSE 10.0 (pre-installed): /usr/share/wesnoth 
Fedora 5 (Installed from yum repository RPM): /usr/share/wesnoth 
Mandriva 2006.0: /usr/share/games/wesnoth 
Slackware 12 (Installed from .tgz package at LinuxPackages.net): /usr/local/share/wesnoth 
If you don't find it, or if you use another distribution, try <code>find / -iname '*wesnoth*'</code>. (as yourself, not as superuser)

=== Where is my '''user''' data directory? ===

====Windows====
C:\Program Files\Wesnoth\userdata

or C:\Users\USERNAME\AppData\Local\VirtualStore\Program Files\Wesnoth\userdata
on Vista, which has virtual folders. The AppData folder is hidden.
Or if you don`t remember where you installed it right click on the game`s shortcut open properties and click on the `Find target` button,then search for the `data` folder.

Starting from Wesnoth 1.8 it can be in MyDocuments\My Games\Wesnoth1.8 on Windows XP or Documents\My Games\Wesnoth1.8 on Vista.

====Mac OS X====
For Wesnoth 1.7.x and 1.8.x: ~/Library/Application Support/Wesnoth_1.x/ 
Downloaded from sourceforge: ~/Library/Preferences/Wesnoth 
Command line build: ~/.wesnoth (same as Linux; see below for details)

====Linux====
~/.wesnoth 
For newer wesnoth versions it can also be ~/.wesnoth<version>. I.e. ~/.wesnoth1.6 
If unsure you can check stdout of wesnoth (run from a terminal) on startup where the used directory is mentioned.

== Game data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. These have the officially distributed campaigns and multiplayer maps. If you ever want to examine or edit one of the scenario configuration files, this is where you would go. For example, a common question is how a new player can give himself more turns or gold in scenario X. This is where you would go to do that.

Two very important directories are ./data/core/units/ and ./images. You have the ability to drop new units or images in these directories and have the game recognize them. When specifying an image for something, you do so relative to ./images.

== User Data ==
The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/campaigns - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/campaigns directory is particularly useful. A single configuration file here can selectively point to an entire subdirectory tree of units, images, sounds, scenarios, and macros. This allows you to wall off parts. Content included in the userdata units or images directories will be available globally whether you want it or not.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/campaigns directory might look like:
* ''userdata''/data/campaigns/MyCampaign/ - your campaign's directory
* ''userdata''/data/campaigns/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/campaigns/MyCampaign/scenarios
** ''userdata''/data/campaigns/MyCampaign/units
** ''userdata''/data/campaigns/MyCampaign/images
** ''userdata''/data/campaigns/MyCampaign/music
** ''userdata''/data/campaigns/MyCampaign/sounds
** ''userdata''/data/campaigns/MyCampaign/utils

{{DevFeature}} Note that in 1.7.0 and later versions, ''add-ons'' replaces ''campaigns'' for these paths.

== See Also ==

* [[Create]]

<div style="border:1px solid #5599FF; margin-top: 10px; margin-bottom: 5px; padding: 5px;">
- [[EditingWesnoth|English]] - [[Editer Wesnoth vf|Français]] -
</div>
[[Category:Create]]

MultiplayerServerWML

2010-05-06T17:43:55Z

Nlmdejonge: /* The handshake */ receded->preceded

= Multiplayer Server WML =
This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come. Below you'll find information about what data the (unzipped) packages contain.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the username, the password and salt received from the server.

* server response
** '''[join_lobby]''' or
** '''[error]'''
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''turn''': The current turn/max turn.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to {{DevFeature}}
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Room commands ==
Note: the room commands are in general {{DevFeature}} and are subject to change.
* '''[room_join]'''
** '''room''': The room name to join
** '''player''': (filled by server in response message sent to all room members) the player that joins the room
** '''[members]''': member list sent to the player that joined
*** '''[member]''': (repeated) members
**** '''name''': This member's name
* '''[room_part]'''
** '''room''': The room name to part (leave). Leaving the lobby is not allowed.
** '''player''': (filled by server in response message sent to all room members) the player that leaves the room
* '''[room_query]''': specific room-related queries.
** '''[rooms]''': List rooms created on the server, or
** '''[names]''': List members of a given room
*** '''room''': The room name (if applicable)
** '''[persist]''': Check or set room persistance
*** '''value''': (optional) set room persistance to this value (yes/no)
* '''[room_query_response]''': contains specific response to a room_query.
** '''message''': optional text message response
** '''room''': room name (if applicable)
** '''[rooms]''': room list
*** '''[room]''': (repeated) rooms
**** '''name''': This room's name
** '''[members]''': member list
*** '''[member]''': (repeated) members
**** '''name''': This member's name

== Nick registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[register]'''
*** '''password''': The password for the nick.
*** '''mail''': The email address for the nick.
** '''[drop]''': Drop this username.
** '''[set]''': Set a detail (e.g. email address) for this nick.
*** '''detail''': The detail, e.g. "mail".
*** '''value''': The new value for this detail, e.g. "user@edomain"
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** '''index''': The index of a user.
** '''[insert_child]''' A new user logged on.
*** '''[user]'''
**** '''name''': The name of the user.
**** '''available''' "yes"
*** '''[delete_child]''' A user logged off.
** '''[change_child]'''
*** '''[user]'''
**** '''[insert]''': A user joined/left a game.
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
***** '''location''': The name of the game the user joined.
**** '''[delete]'''
***** '''location''': "x" when a game was left.
*** '''[gamelist]'''
**** '''index''': Index of the game in question.
**** '''[insert_child]''': A game started.
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''': A game ended.
***** '''[game]'''
**** '''[change_child]''': Something changed in a game.
***** '''[game]'''
****** '''[insert]'''
******* '''slots''': The number of free slots in the form: free/max slots
******* '''turn''': The turn number in the form: current turn/max turns
****** '''[delete]'''
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game

== In-game communication ==

* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nick of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

[[Category:WML Reference]]

MultiplayerServerWML

2010-05-06T17:38:07Z

Nlmdejonge: added information about the handshake

= Multiplayer Server WML =
This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are receded by four bytes that specify the size of the package to come. Below you'll find information about what data the (unzipped) packages contain.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the username, the password and salt received from the server.

* server response
** '''[join_lobby]''' or
** '''[error]'''
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''turn''': The current turn/max turn.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to {{DevFeature}}
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Room commands ==
Note: the room commands are in general {{DevFeature}} and are subject to change.
* '''[room_join]'''
** '''room''': The room name to join
** '''player''': (filled by server in response message sent to all room members) the player that joins the room
** '''[members]''': member list sent to the player that joined
*** '''[member]''': (repeated) members
**** '''name''': This member's name
* '''[room_part]'''
** '''room''': The room name to part (leave). Leaving the lobby is not allowed.
** '''player''': (filled by server in response message sent to all room members) the player that leaves the room
* '''[room_query]''': specific room-related queries.
** '''[rooms]''': List rooms created on the server, or
** '''[names]''': List members of a given room
*** '''room''': The room name (if applicable)
** '''[persist]''': Check or set room persistance
*** '''value''': (optional) set room persistance to this value (yes/no)
* '''[room_query_response]''': contains specific response to a room_query.
** '''message''': optional text message response
** '''room''': room name (if applicable)
** '''[rooms]''': room list
*** '''[room]''': (repeated) rooms
**** '''name''': This room's name
** '''[members]''': member list
*** '''[member]''': (repeated) members
**** '''name''': This member's name

== Nick registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[register]'''
*** '''password''': The password for the nick.
*** '''mail''': The email address for the nick.
** '''[drop]''': Drop this username.
** '''[set]''': Set a detail (e.g. email address) for this nick.
*** '''detail''': The detail, e.g. "mail".
*** '''value''': The new value for this detail, e.g. "user@edomain"
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** '''index''': The index of a user.
** '''[insert_child]''' A new user logged on.
*** '''[user]'''
**** '''name''': The name of the user.
**** '''available''' "yes"
*** '''[delete_child]''' A user logged off.
** '''[change_child]'''
*** '''[user]'''
**** '''[insert]''': A user joined/left a game.
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
***** '''location''': The name of the game the user joined.
**** '''[delete]'''
***** '''location''': "x" when a game was left.
*** '''[gamelist]'''
**** '''index''': Index of the game in question.
**** '''[insert_child]''': A game started.
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''': A game ended.
***** '''[game]'''
**** '''[change_child]''': Something changed in a game.
***** '''[game]'''
****** '''[insert]'''
******* '''slots''': The number of free slots in the form: free/max slots
******* '''turn''': The turn number in the form: current turn/max turns
****** '''[delete]'''
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game

== In-game communication ==

* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nick of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

[[Category:WML Reference]]

Talk:Competitive Gaming

2009-06-18T11:29:25Z

Nlmdejonge: New page: == Using an AI == Another way to cheat, apart from those mentioned under ''The Facts'' would be to use any kind of AI, for example that which comes with Wesnoth itself. -~~~~

== Using an AI ==
Another way to cheat, apart from those mentioned under ''The Facts'' would be to use any kind of AI, for example that which comes with Wesnoth itself. -[[User:Nlmdejonge|Nlmdejonge]] 11:29, 18 June 2009 (UTC)