CommandLineOptions.wiki
author Wuzzy
Wed, 11 Jul 2018 13:39:34 +0100
changeset 1443 d25ab95f2311
parent 1055 754e0a7bdd44
child 1477 73e1bbc61037
permissions -rw-r--r--
LuaAPI: deprecate lfCurrentHog
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 =
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
     5
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
     6
<wiki:toc max_depth="2" />
5
5889169b9459 Added frontend options
vittorio.giovara@gmail.com
parents: 4
diff changeset
     7
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
     8
== Frontend ==
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
     9
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
    10
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    11
Symtax: `hedgewars [OPTION …] [CONNECTSTRING]`
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    12
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    13
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
    14
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    15
`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
    16
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    17
  * {{{--data-dir=[path containing 'hedgewars/Data']}}}: Data directory
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    18
  * {{{--config-dir=[path containing 'Demos' 'Saves' etc.]}}}: Configuration directory
735
f749a4528835 CommandLineOptions: clarify --help
Wuzzy
parents: 734
diff changeset
    19
  * {{{--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
    20
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    21
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
    22
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    23
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
    24
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    25
=== Examples ===
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    26
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
    27
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    28
{{{
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    29
$ /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
    30
}}}
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
    31
733
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    32
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
    33
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    34
Another example:
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    35
{{{
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    36
$ /usr/bin/hedgewars hwplay://example.org
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
5e67a58c1361 CommandLineOptions: Update command-line arguments of frontend
Wuzzy
parents: 587
diff changeset
    39
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
    40
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    41
== Engine ==
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    42
The engine is the program which runs the actual game.
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    43
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    44
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
    45
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    46
=== Standard usage ===
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    47
{{{hwengine [options] <path to replay file>}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    48
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    49
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
    50
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    51
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
    52
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    53
=== Advanced usage ===
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    54
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
    55
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    56
  * {{{--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
    57
  * {{{--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
    58
  * {{{--locale [language file]}}} - Sets the game language (en.txt for sample)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    59
  * {{{--nick [string]}}} - Represents the user nickname
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    60
  * {{{--width [size]}}} - Starts the game with the given width (in pixels)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    61
  * {{{--height [size]}}} - Starts the game with the given height (in pixels)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    62
  * {{{--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
    63
  * {{{--nomusic}}} - Disables music
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    64
  * {{{--nosound}}} - Disables sound effects
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    65
  * {{{--fullscreen}}} - Starts game in fullscreen
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    66
  * {{{--showfps}}} - Shows a fps counter in the top right
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    67
  * {{{--altdmg}}} - Uses an alternative damage indicator
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    68
  * {{{--low-quality}}} - Lowers the game quality
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    69
  * {{{--stereo [type]}}} - Sets stereoscopic rendering type (1 to 14)
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    70
  * {{{--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
    71
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
    72
==== More advanced usage ====
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    73
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
    74
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    75
  * {{{--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
    76
  * {{{--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
    77
  * {{{--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
    78
  * {{{--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
    79
  * {{{--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
    80
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    81
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
    82
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    83
`--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
    84
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    85
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
    86
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    87
  * _Windows_: {{{%USERPROFILE%\Hedgewars}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    88
  * _GNU/Linux_: {{{~/.hedgewars}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    89
  * _Mac OS X_: {{{~/Library/Application Support/Hedgewars}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    90
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 760
diff changeset
    91
`--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
    92
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    93
  * {{{qLowRes        = 1}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    94
  * {{{rqBlurryLand   = 2}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    95
  * {{{rqNoBackground = 4}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    96
  * {{{rqSimpleRope   = 8}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    97
  * {{{rq2DWater      = 16}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    98
  * {{{rqAntiBoom     = 32}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
    99
  * {{{rqKillFlakes   = 64}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   100
  * {{{rqSlowMenu     = 128}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   101
  * {{{rqPlainSplash  = 256}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   102
  * {{{rqClampLess    = 512}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   103
  * {{{rqTooltipsOff  = 1024}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   104
  * {{{rqDesyncVBlank = 2048}}}
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   105
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   106
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
   107
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   108
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
   109
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   110
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
   111
[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
   112
760
7d419f65a27d CommandLineOptions: Add title, fix header levels
Wuzzy
parents: 735
diff changeset
   113
== Server ==
293
2dc603c7d7e6 added server options and table of contents
vittorio.giovara@gmail.com
parents: 292
diff changeset
   114
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   115
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
   116
734
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   117
  * {{{--port=PORT}}} or {{{-p PORT}}}: Server listens on `PORT`
63cad3d4a62b CommandLineOptions: Reorder text and simple copy-editing
Wuzzy
parents: 733
diff changeset
   118
  * {{{--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
   119
  * {{{--help}}}: Shows a short text explaining the command-line arguments and exists the program thereafter.