1WESNOTH(6)                    Battle for Wesnoth                    WESNOTH(6)
2
3
4

NAME

6       wesnoth - Battle for Wesnoth, a turn-based fantasy strategy game
7

SYNOPSIS

9       wesnoth [OPTIONS] [PATH_TO_DATA]
10

DESCRIPTION

12       Battle for Wesnoth is a turn-based fantasy strategy game.
13
14       Defeat  all  enemy  leaders using a well-chosen cadre of troops, taking
15       care to manage your resources of gold  and  villages.  All  units  have
16       their own strengths and weaknesses; to win, deploy your forces to their
17       best advantage while denying your foes the chance to do  the  same.  As
18       units  gain experience, they acquire new abilities and become more pow‐
19       erful. Play in your own language and test your skill  against  a  smart
20       computer opponent, or join Wesnoth's large community of online players.
21       Create your own custom units, scenarios or campaigns,  and  share  them
22       with others.
23

OPTIONS

25       --all-translations
26              Show  all  translations  in the in-game language selection list,
27              even if they are deemed insufficiently complete.
28
29       --bunzip2 infile.bz2
30              decompresses a file which should be in bzip2 format  and  stores
31              it without the .bz2 suffix. The infile.bz2 will be removed.
32
33       --bzip2 infile
34              compresses  a  file in bzip2 format, stores it as infile.bz2 and
35              removes infile.
36
37       -c[id_campaign], --campaign[=id_campaign]
38              goes directly to the campaign with id id_campaign.  A  selection
39              menu will appear if no id was specified.
40
41       --campaign-difficulty[=difficulty]
42              The  difficulty  of  the  specified campaign (1 to max). If none
43              specified, the campaign difficulty selection widget will appear.
44
45       --campaign-scenario id_scenario
46              The id of the scenario from the specified campaign. The  default
47              is the first scenario.
48
49       --campaign-skip-story
50              Skip  [story]  screens  and  dialog through the end of the start
51              event.
52
53       --clock
54              Adds the option to show a clock for testing the drawing timer.
55
56       --config-dir name
57              Deprecated, use --userdata-dir.
58
59       --config-path
60              Deprecated, use --userdata-path.
61
62       --core id_core
63              overrides the loaded core with the one whose id is specified.
64
65       --data-dir directory
66              overrides the data directory with the one specified
67
68       --data-path
69              prints the path of the data directory and exits.
70
71       -d, --debug
72              enables additional command mode options in-game  (see  the  wiki
73              page at https://www.wesnoth.org/wiki/CommandMode for more infor‐
74              mation about command mode).
75
76       --debug-lua
77              enables some Lua debugging mechanisms
78
79       --strict-lua
80              disallow deprecated Lua API calls
81
82       -D,--diff left-file right-file
83              diffs the two WML files; does not preprocess them first  (to  do
84              that, run them through -p first). Outputs the diff as DiffWML on
85              standard output or to the file indicated by --output.
86
87       -e[file], --editor[=file]
88              start the in-game map editor directly.  If  file  is  specified,
89              equivalent to -l --load.
90
91       --fps  displays  the  number of frames per second the game is currently
92              running at, in a corner of the screen.
93
94       -f, --fullscreen
95              runs the game in full screen mode.
96
97       --gunzip infile.gz
98              decompresses a file which should be in gzip format and stores it
99              without the .gz suffix. The infile.gz will be removed.
100
101       --gzip infile
102              compresses  a  file  in  gzip format, stores it as infile.gz and
103              removes infile.
104
105       -h, --help
106              displays a summary of command line options to  standard  output,
107              and exits.
108
109       -l, --load file
110              loads  the  savegame file from the standard save game directory.
111              If the -e or --editor option is used as well, starts the  editor
112              with  the  map  from file open. If it is a directory, the editor
113              will start with a load map dialog opened there.
114
115       -L, --language lang
116              uses language lang (symbol) this session.   Example:  --language
117              ang_GB@latin
118
119       --log-level=domain1,domain2,...
120              sets  the severity level of the log domains.  all can be used to
121              match   any   log   domain.   Available   levels:   error, warn‐
122              ing, info, debug, none.   By  default  the warning level is used
123              for most domains, but deprecation defaults to none  unless  com‐
124              bined with the -d option.
125
126       --log-precise
127              shows the timestamps in log output with more precision.
128
129       --log-strict
130              sets  the  strict  level of the logger. Any messages sent to log
131              domains of this level or more severe will cause the unit test to
132              fail  regardless  of the victory result. Only relevant when used
133              with -u.
134
135       --logdomains[=filter]
136              lists defined log domains (only the ones  containing  filter  if
137              used) and exits
138
139       --max-fps fps
140              the  number  of  frames  per second the game can show, the value
141              should be between 1 and  1000,  the  default  is  the  monitor's
142              refresh rate.
143
144       -m, --multiplayer
145              runs  a  multiplayer game. There are additional options that can
146              be used together with --multiplayer as explained below.
147
148       --mp-test
149              load the test mp scenarios.
150
151       --new-widgets
152              there is a new WIP widget toolkit, this option enables it.  This
153              is  very  experimental,  don't  fill  bug reports since most are
154              known. Parts of the library are  deemed  stable  and  will  work
155              without this switch.
156
157       --nodelay
158              runs  the game without any delays for graphic benchmarking. This
159              is automatically enabled by --nogui.
160
161       --noaddons
162              disables loading of user addons.
163
164       --nocache
165              disables caching of game data.
166
167       --nogui
168              runs the game without the GUI.  Only  available  in  combination
169              with --multiplayer or --screenshot or --plugin.
170
171       --nobanner
172              suppress the startup banner.
173
174       --nomusic
175              runs the game without music.
176
177       --noreplaycheck
178              don't  try  to  validate replay of unit test. Only relevant when
179              used with -u.
180
181       --nosound
182              runs the game without sounds and music.
183
184       --output file
185              output to the specified file. Applicable to diffing operations.
186
187       --password password
188              uses password when connecting to a server, ignoring other  pref‐
189              erences. Unsafe.
190
191       --plugin script
192              (experimental)  load  a  script  which defines a Wesnoth plugin.
193              Similar to --script, but Lua file should return a function which
194              will  be  run  as  a  coroutine  and  periodically woken up with
195              updates.
196
197       -P,--patch base-file patch-file
198              applies a DiffWML patch to  a  WML  file;  does  not  preprocess
199              either of the files.  Outputs the patched WML to standard output
200              or to the file indicated by --output.
201
202       -p, --preprocess source-file/folder target-directory
203              preprocesses a specified file/folder. For each file(s)  a  plain
204              .cfg file and a processed .cfg file will be written in specified
205              target directory. If a folder is specified, it will  be  prepro‐
206              cessed  recursively  based  on the known preprocessor rules. The
207              common macros from the "data/core/macros" directory will be pre‐
208              processed  before  the  specified resources.  Example: -p ~/wes‐
209              noth/data/campaigns/tutorial ~/result.   For  details  regarding
210              the  preprocessor  visit: https://wiki.wesnoth.org/Preprocessor
211              Ref#Command-line_preprocessor.
212
213       --preprocess-defines=DEFINE1,DEFINE2,...
214              comma separated list of defines to be used by  the  --preprocess
215              command.  If  SKIP_CORE  is  in  the define list the "data/core"
216              directory won't be preprocessed.
217
218       --preprocess-input-macros source-file
219              used only by the --preprocess command.  Specifies  a  file  that
220              contains [preproc_define]s to be included before preprocessing.
221
222       --preprocess-output-macros[=target-file]
223              used  only  by the --preprocess command. Will output all prepro‐
224              cessed macros in the target file. If the file is  not  specified
225              the  output  will be file '_MACROS_.cfg' in the target directory
226              of preprocess's command. The output file can be passed to --pre‐
227              process-input-macros.   This  switch  should be typed before the
228              --preprocess command.
229
230       -r XxY, --resolution XxY
231              sets the screen resolution. Example: -r 800x600.
232
233       --render-image image output
234              takes a valid wesnoth 'image path string' with image path  func‐
235              tions, and outputs to a .png file. Image path functions are doc‐
236              umented at https://wiki.wesnoth.org/ImagePathFunctionWML.
237
238       -R, --report
239              initializes game directories, prints build information  suitable
240              for use in bug reports, and exits.
241
242       --rng-seed number
243              seeds  the random number generator with number.  Example: --rng-
244              seed 0.
245
246       --screenshot map output
247              saves a screenshot of  map  to  output  without  initializing  a
248              screen.
249
250       --script file
251              (experimental)  file  containing  a  Lua  script  to control the
252              client.
253
254       -s[host], --server[=host]
255              connects to the specified host if any, otherwise connect to  the
256              first  server  in  preferences.  Example:  --server  server.wes‐
257              noth.org.
258
259       --showgui
260              runs the game with the GUI, overriding any implicit --nogui.
261
262       --strict-validation
263              validation errors are treated as fatal errors.
264
265       -t[scenario_id], --test[=scenario_id]
266              runs the game in a small test scenario. The scenario  should  be
267              one  defined  with  a  [test]  WML  tag. The default is test.  A
268              demonstration of the [micro_ai]  feature  can  be  started  with
269              micro_ai_test.  Implies --nogui.
270
271       --translations-over percent
272              Set the standard for deeming a translation is complete enough to
273              show in the in-game language list to percent.  Valid values  are
274              0 to 100.
275
276       -u, --unit scenario-id
277              runs  the  specified  test  scenario  as  a  unit  test. Implies
278              --nogui.
279
280       --unsafe-scripts
281              makes the package package available to lua scripts, so that they
282              can  load  arbitrary  packages.  Do  not  do this with untrusted
283              scripts! This action gives lua the same permissions as the  wes‐
284              noth executable.
285
286       -S,--use-schema path
287              sets the WML schema for use with -V,--validate.
288
289       --userconfig-dir name
290              sets the user configuration directory to name under $HOME or "My
291              Documents\My Games" for windows.  You can also specify an  abso‐
292              lute  path  for the configuration directory outside the $HOME or
293              "My Documents\My Games". On Windows it is also possible to spec‐
294              ify  a  directory  relative  to the process working directory by
295              using path starting with ".\" or "..\".  Under X11 this defaults
296              to  $XDG_CONFIG_HOME  or $HOME/.config/wesnoth, on other systems
297              to the userdata path.
298
299       --userconfig-path
300              prints the path of the user configuration directory and exits.
301
302       --userdata-dir name
303              sets the userdata directory to name under  $HOME  or  "My  Docu‐
304              ments\My  Games"  for windows.  You can also specify an absolute
305              path for the userdata directory outside the $HOME or  "My  Docu‐
306              ments\My  Games".  On  Windows  it is also possible to specify a
307              directory relative to the process  working  directory  by  using
308              path starting with ".\" or "..\".
309
310       --userdata-path
311              prints the path of the userdata directory and exits.
312
313       --username username
314              uses  username when connecting to a server, ignoring other pref‐
315              erences.
316
317       --validate path
318              validates a file against the WML schema.
319
320       --validate-addon addon_id
321              validates the WML of the given addon as you play.
322
323       --validate-core
324              validates the core WML as you play.
325
326       --validate-schema  path
327              validates a file as a WML schema.
328
329       --validcache
330              assumes that the cache is valid. (dangerous)
331
332       -v, --version
333              shows the version number and exits.
334
335       -w, --windowed
336              runs the game in windowed mode.
337
338       --with-replay
339              replays the game loaded with the --load option.
340

Options for --multiplayer

342       The side-specific multiplayer options are marked with  number.   number
343       has  to  be replaced by a side number. It usually is 1 or 2 but depends
344       on the number of players possible in the chosen scenario.
345
346       --ai-config number:value
347              selects a configuration file to load for the AI  controller  for
348              this side.
349
350       --algorithm number:value
351              selects a non-standard algorithm to be used by the AI controller
352              for this side. The algorithm is defined by an  [ai]  tag,  which
353              can be a core one either in "data/ai/ais" or "data/ai/dev" or an
354              algorithm defined by an addon. Available values include: idle_ai
355              and experimental_ai.
356
357       --controller number:value
358              selects  the  controller for this side. Available values: human,
359              ai and null.
360
361       --era value
362              use this option to play in  the  selected  era  instead  of  the
363              Default  era.  The era is chosen by an id. Eras are described in
364              the data/multiplayer/eras.cfg file.
365
366       --exit-at-end
367              exits  once  the  scenario  is  over,  without  displaying  vic‐
368              tory/defeat dialog which normally requires the user to click End
369              Scenario.  This is also used for scriptable benchmarking.
370
371       --ignore-map-settings
372              do not use map settings, use default values instead.
373
374       --label label
375              sets the label for AIs.
376
377       --multiplayer-repeat value
378              repeats a multiplayer game value times. Best to use with --nogui
379              for scriptable benchmarking.
380
381       --parm number:name:value
382              sets additional parameters for this side. This parameter depends
383              on the options  used  with  --controller  and  --algorithm.   It
384              should  only  be  useful for people designing their own AI. (not
385              yet documented completely)
386
387       --scenario value
388              selects a multiplayer scenario by id. The default scenario id is
389              multiplayer_The_Freelands.
390
391       --side number:value
392              selects  a faction of the current era for this side. The faction
393              is chosen by an id. Factions are described  in  the  data/multi‐
394              player.cfg file.
395
396       --turns value
397              sets  the number of turns for the chosen scenario. By default no
398              turn limit is set.
399

EXIT STATUS

401       Normal exit status is 0.  An exit status of 1 indicates an (SDL, video,
402       fonts,  etc)  initialization  error.  An  exit status of 2 indicates an
403       error with the command line options.
404       When running unit tests (with -u), the exit  status  is  different.  An
405       exit  status  of 0 indicates that the test passed, and 1 indicates that
406       the test failed. An exit status of 3 indicates that  the  test  passed,
407       but produced an invalid replay file. An exit status of 4 indicates that
408       the test passed, but the replay produced errors. These latter  two  are
409       only returned if --noreplaycheck is not passed.
410

AUTHOR

412       Written by David White <davidnwhite@verizon.net>.
413       Edited by Nils Kneuper <crazy-ivanovic@gmx.net>, ott <ott@gaon.net> and
414       Soliton <soliton.de@gmail.com>.
415       This  manual  page   was   originally   written   by   Cyril   Bouthors
416       <cyril@bouthors.org>.
417       Visit the official homepage: https://www.wesnoth.org/
418
420       Copyright © 2003-2018 David White <davidnwhite@verizon.net>
421       This  is Free Software; this software is licensed under the GPL version
422       2, as published by the Free Software Foundation.  There is NO warranty;
423       not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
424

SEE ALSO

426       wesnothd(6)
427
428
429
430wesnoth                              2018                           WESNOTH(6)
Impressum