CommandLineOptions.wiki
author alfadur
Thu, 26 Dec 2019 00:10:00 +0300
changeset 2124 3dfeac5b03db
parent 2044 683467addd2e
permissions -rw-r--r--
add server walkthrough
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
     1
#summary Full list of command line switches for hedgewars, hwengine and server
3
ba86e3ce90c3 Ported command line options from http://www.hedgewars.org/node/1465
vittorio.giovara@gmail.com
parents:
diff changeset
     2
#labels Documentation,Engine,Frontend
292
27c4a3aec2a0 summary
vittorio.giovara@gmail.com
parents: 291
diff changeset
     3
1055
754e0a7bdd44 Explain briefly how engine testing works
Wuzzy <almikes@aol.com>
parents: 798
diff changeset
     4
= Command-line options =
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
     5
<wiki:toc max_depth="2" />
5
5889169b9459 Added frontend options
vittorio.giovara@gmail.com
parents: 4
diff changeset
     6
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
     7
== Frontend ==
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
     8
The frontend in Hedgewars refers to the main and all the other menus before an actual game has started. It does *not* refer to the part where the actual game takes place (see “Engine” for this).
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
     9
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    10
Symtax: `hedgewars [OPTION …] [CONNECTSTRING]`
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    11
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    12
All command-line arguments are optional. When invoked without any command-line arguments, the Hedgewars frontend will start normally with standard directory locations.
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    13
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    14
`OPTION` is a sequence of one or more options (seperated by spaces. There are options that enable to load the data directory and the configuration directory in non-standard locations. The following options are available:
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    15
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    16
  * {{{--data-dir=[path containing 'hedgewars/Data']}}}: Data directory
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    17
  * {{{--config-dir=[path containing 'Demos' 'Saves' etc.]}}}: Configuration directory
735
f749a4528835 CommandLineOptions: clarify --help
Wuzzy
parents: 734
diff changeset
    18
  * {{{--help:}}}: Display help about command-line arguments and exit the program thereafter
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    19
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    20
The program exits if either one of the folders is not correct; quotes are optional, but needed if your path contains spaces.
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    21
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    22
Specify `CONNECTSTRING` if you want Hedgewars to join a server and possibly even a room on start. This must be a `hwplay` URL (see [HWPlaySchemeSyntax] to learn more about this).
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    23
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    24
=== Examples ===
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    25
This is an example on GNU/Linux on a shell (the dollar sign is not part of the input):
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    26
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    27
{{{
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    28
$ /usr/bin/hedgewars --data-dir="/opt/local/share/" --config-dir=".hedgewars/tesing config/"
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    29
}}}
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    30
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    31
This starts Hedgewars with the data directory `/opt/local/share/` and the configuration directory `.hedgewars/testing config/` (relative to the current working directory).
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    32
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    33
Another example:
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    34
{{{
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    35
$ /usr/bin/hedgewars hwplay://example.org
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    36
}}}
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    37
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    38
Makes Hedgewars join an alternative server `example.org` on start.
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    39
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    40
== Engine ==
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    41
The engine is the program which runs the actual game.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    42
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    43
It is possible to start a replay or save file directly from the console issuing the standalone {{{hwengine}}} utility with a very simple syntax. 
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    44
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    45
=== Standard usage ===
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    46
{{{hwengine [options] <path to replay file>}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    47
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    48
By default, `hwengine` will look in the current folder for game assets, if you wish to use another directory you should set the `--prefix` and `--user-prefix` options. See below for even more commands.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    49
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    50
The replay file can be stored anywhere. Note that, as always, engine can only load replay files generated from the same Hedgewars version.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    51
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    52
=== Advanced usage ===
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    53
It is possible to specify almost any settings by adding additional arguments:
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    54
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    55
  * {{{--prefix [path to Hedgewars data folder]}}} - Sets the path to the system game data folder
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    56
  * {{{--user-prefix [path to custom Hedgewars folder]}}} - Sets the path to the custom data folder to find game content
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    57
  * {{{--locale [language file]}}} - Sets the game language (en.txt for sample)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    58
  * {{{--nick [string]}}} - Represents the user nickname
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    59
  * {{{--width [size]}}} - Starts the game with the given width (in pixels)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    60
  * {{{--height [size]}}} - Starts the game with the given height (in pixels)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    61
  * {{{--volume [level]}}} - Sets the volume level, possible values range from 0-100 (negative is muted)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    62
  * {{{--nomusic}}} - Disables music
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    63
  * {{{--nosound}}} - Disables sound effects
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    64
  * {{{--fullscreen}}} - Starts game in fullscreen
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    65
  * {{{--showfps}}} - Shows a fps counter in the top right
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    66
  * {{{--altdmg}}} - Uses an alternative damage indicator
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    67
  * {{{--low-quality}}} - Lowers the game quality
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    68
  * {{{--stereo [type]}}} - Sets stereoscopic rendering type (1 to 14)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    69
  * {{{--help}}} - Shows a list of command line options and exits the program directly after
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    70
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    71
==== More advanced usage ====
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    72
Generally you don't need to set these options but here they are for full documentation:
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    73
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    74
  * {{{--frame-interval [interval]}}} - Sets minimum interval (in ms) between each frame. Eg, 40 would make the game run at most 25 fps
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    75
  * {{{--raw-quality [flags]}}} - (For advanced users only). Manually specifies the reduced quality flags, see below. 
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    76
  * {{{--stats-only}}} - Outputs the round information without launching the game, useful for statistics only
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    77
  * {{{--fullscreen-width [size]}}} - Starts the game with the given width (in pixels) when fullscreen
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    78
  * {{{--fullscreen-height [size]}}} - Starts the game with the given height (in pixels) when fullscreen
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    79
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    80
Note: any modification to the command line arguments should be reflected in the autostart `.desktop` file, `game.cpp`, `GameInterfaceBridge.m`.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    81
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    82
`--prefix location` is usually hardcoded at compile time, but should you changed the installation directory, then you can use this flag to override it; alternatively you can just specify `--user-prefix`.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    83
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    84
Personal game data is by default contained in one of the following directories:
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    85
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    86
  * _Windows_: {{{%USERPROFILE%\Hedgewars}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    87
  * _GNU/Linux_: {{{~/.hedgewars}}}
1963
1175d2f6f198 Rename “Mac OS” to “macOS”
Wuzzy <almikes@aol.com>
parents: 1478
diff changeset
    88
  * _macOS_: {{{~/Library/Application Support/Hedgewars}}}
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    89
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 760
diff changeset
    90
`--raw-quality value` is determined by combining the values of the flags you wish to enable. Up-to-date variables (in hexadecimal) are online here: [https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l62 uConsts.pas]
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    91
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    92
  * {{{qLowRes        = 1}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    93
  * {{{rqBlurryLand   = 2}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    94
  * {{{rqNoBackground = 4}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    95
  * {{{rqSimpleRope   = 8}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    96
  * {{{rq2DWater      = 16}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    97
  * {{{rqAntiBoom     = 32}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    98
  * {{{rqKillFlakes   = 64}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    99
  * {{{rqSlowMenu     = 128}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   100
  * {{{rqPlainSplash  = 256}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   101
  * {{{rqClampLess    = 512}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   102
  * {{{rqTooltipsOff  = 1024}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   103
  * {{{rqDesyncVBlank = 2048}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   104
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   105
E.g., to have blurry land and simple rope, you would use the number 10 (2+8).
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   106
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   107
There are some internal commands, such as `--internal`, `--port [int]`, that are not meant for command-line usage.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   108
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   109
If you want to get your hands dirty and see how the engine interprets commands, you can check out the source code:
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 760
diff changeset
   110
[https://hg.hedgewars.org/hedgewars/file/default/hedgewars/ArgParsers.inc ArgParsers.inc]
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   111
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
   112
== Server ==
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
   113
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   114
The server can be configured to run on non standard port or to run as separate process.
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
   115
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   116
  * {{{--port=PORT}}} or {{{-p PORT}}}: Server listens on `PORT`
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   117
  * {{{--dedicated=BOOL}}} or {{{-d BOOL}}}: Spawn a separate process (`BOOL` is either “True” or “False”)
1055
754e0a7bdd44 Explain briefly how engine testing works
Wuzzy <almikes@aol.com>
parents: 798
diff changeset
   118
  * {{{--help}}}: Shows a short text explaining the command-line arguments and exists the program thereafter.