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

Options for --multiplayer

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

EXIT STATUS

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

AUTHOR

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

SEE ALSO

427       wesnothd(6)
428
429
430
431wesnoth                              2021                           WESNOTH(6)
Impressum