CommandLineOptions.wiki
author Wuzzy
Sat, 09 Apr 2016 08:22:46 +0100
changeset 865 ed6a7ad2770f
parent 798 30c5f1ebd552
child 1055 754e0a7bdd44
permissions -rw-r--r--
LuaAPI: PlaceSprite return value

#summary Full list of command line switches for hedgewars, hwengine and server
#labels Documentation,Engine,Frontend

= Commnd-line options =

<wiki:toc max_depth="2" />

== Frontend ==
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).

Symtax: `hedgewars [OPTION …] [CONNECTSTRING]`

All command-line arguments are optional. When invoked without any command-line arguments, the Hedgewars frontend will start normally with standard directory locations.

`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:

  * {{{--data-dir=[path containing 'hedgewars/Data']}}}: Data directory
  * {{{--config-dir=[path containing 'Demos' 'Saves' etc.]}}}: Configuration directory
  * {{{--help:}}}: Display help about command-line arguments and exit the program thereafter

The program exits if either one of the folders is not correct; quotes are optional, but needed if your path contains spaces.

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).

=== Examples ===
This is an example on GNU/Linux on a shell (the dollar sign is not part of the input):

{{{
$ /usr/bin/hedgewars --data-dir="/opt/local/share/" --config-dir=".hedgewars/tesing config/"
}}}

This starts Hedgewars with the data directory `/opt/local/share/` and the configuration directory `.hedgewars/testing config/` (relative to the current working directory).

Another example:
{{{
$ /usr/bin/hedgewars hwplay://example.org
}}}

Makes Hedgewars join an alternative server `example.org` on start.

== Engine ==
The engine is the program which runs the actual game.

It is possible to start a replay or save file directly from the console issuing the standalone {{{hwengine}}} utility with a very simple syntax. 

=== Standard usage ===
{{{hwengine [options] <path to replay file>}}}

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.

The replay file can be stored anywhere. Note that, as always, engine can only load replay files generated from the same Hedgewars version.

=== Advanced usage ===
It is possible to specify almost any settings by adding additional arguments:

  * {{{--prefix [path to Hedgewars data folder]}}} - Sets the path to the system game data folder
  * {{{--user-prefix [path to custom Hedgewars folder]}}} - Sets the path to the custom data folder to find game content
  * {{{--locale [language file]}}} - Sets the game language (en.txt for sample)
  * {{{--nick [string]}}} - Represents the user nickname
  * {{{--width [size]}}} - Starts the game with the given width (in pixels)
  * {{{--height [size]}}} - Starts the game with the given height (in pixels)
  * {{{--volume [level]}}} - Sets the volume level, possible values range from 0-100 (negative is muted)
  * {{{--nomusic}}} - Disables music
  * {{{--nosound}}} - Disables sound effects
  * {{{--fullscreen}}} - Starts game in fullscreen
  * {{{--showfps}}} - Shows a fps counter in the top right
  * {{{--altdmg}}} - Uses an alternative damage indicator
  * {{{--low-quality}}} - Lowers the game quality
  * {{{--stereo [type]}}} - Sets stereoscopic rendering type (1 to 14)
  * {{{--help}}} - Shows a list of command line options and exits the program directly after

==== More advanced usage ====
Generally you don't need to set these options but here they are for full documentation:

  * {{{--frame-interval [interval]}}} - Sets minimum interval (in ms) between each frame. Eg, 40 would make the game run at most 25 fps
  * {{{--raw-quality [flags]}}} - (For advanced users only). Manually specifies the reduced quality flags, see below. 
  * {{{--stats-only}}} - Outputs the round information without launching the game, useful for statistics only
  * {{{--fullscreen-width [size]}}} - Starts the game with the given width (in pixels) when fullscreen
  * {{{--fullscreen-height [size]}}} - Starts the game with the given height (in pixels) when fullscreen

Note: any modification to the command line arguments should be reflected in the autostart `.desktop` file, `game.cpp`, `GameInterfaceBridge.m`.

`--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`.

Personal game data is by default contained in one of the following directories:

  * _Windows_: {{{%USERPROFILE%\Hedgewars}}}
  * _GNU/Linux_: {{{~/.hedgewars}}}
  * _Mac OS X_: {{{~/Library/Application Support/Hedgewars}}}

`--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]

  * {{{qLowRes        = 1}}}
  * {{{rqBlurryLand   = 2}}}
  * {{{rqNoBackground = 4}}}
  * {{{rqSimpleRope   = 8}}}
  * {{{rq2DWater      = 16}}}
  * {{{rqAntiBoom     = 32}}}
  * {{{rqKillFlakes   = 64}}}
  * {{{rqSlowMenu     = 128}}}
  * {{{rqPlainSplash  = 256}}}
  * {{{rqClampLess    = 512}}}
  * {{{rqTooltipsOff  = 1024}}}
  * {{{rqDesyncVBlank = 2048}}}

E.g., to have blurry land and simple rope, you would use the number 10 (2+8).

There are some internal commands, such as `--internal`, `--port [int]`, that are not meant for command-line usage.

If you want to get your hands dirty and see how the engine interprets commands, you can check out the source code:
[https://hg.hedgewars.org/hedgewars/file/default/hedgewars/ArgParsers.inc ArgParsers.inc]

== Server ==

The server can be configured to run on non standard port or to run as separate process.

  * {{{--port=PORT}}} or {{{-p PORT}}}: Server listens on `PORT`
  * {{{--dedicated=BOOL}}} or {{{-d BOOL}}}: Spawn a separate process (`BOOL` is either “True” or “False”)
  * {{{--help}}}: Shows a short text explaining the command-line arguments and exists the program thereafter.