#summary Documentation of configuration files on desktop

#labels Documentation

= Configuration files =

== Introduction ==

This documents the structure and content of the configuration (.ini) files found in the desktop version of Hedgewars.

<wiki:toc max_depth="2" />

== `settings.ini` ==

=== {{{[video]}}} ===

_Graphics rendering settings, back-end (engine)_

|| *Setting* || *Type* || *Description* ||

|| fullscreenResolution=1280x768 || String || Screen resolution the game is rendered when using fullscreen mode ||

|| windowedWidth=1280 || Integer || Window width when using window mode ||

|| windowedHeight=1024 || Integer || Window height when using window mode ||

|| fullscreen=false || Boolean || If the game is rendered in fullscreen ||

|| quality=5 || Integer || Quality of game rendering (0-5, 5 is best quality) ||

|| stereo=0 || Integer || Mode of stereoscopic 3D rendering, 0 being no 3D ||

=== {{{[frontend]}}} ===

_Graphics and sound settings, front-end (GUI)_

|| *Setting* || *Type* || *Description* ||

|| effects=true || Boolean || If game effects are displayed ||

|| fullscreen=false || Boolean || If the game is in fullscreen-mode, instead of windowed-mode ||

|| width=800 || Integer || Width of the game window ||

|| height=600 || Integer || Height of the game window ||

|| sound=true || Boolean || If sounds are being played in the frontend ||

|| music=true || Boolean || If background music is being played in the frontend ||

=== {{{[misc]}}} ===

_Miscellaneous settings_

|| *Setting* || *Type* || *Description* ||

|| weaponTooltips=true || Boolean || If tooltips should be shown in the ammo menu ||

|| altdamage=false || Boolean || If damage pop-ups should be shown on every shot, instead of only at the end of a round ||

|| appendTimeToRecords=false || Boolean || If date and time should be appended to the file name when demo records are saved ||

|| locale=en_US || String || Language used in game in the format "ISO 639-1 Code underscore ISO 3166-1 alpha-2 Code", or system default if left blank ||

|| teamtag || Boolean || Whether to show the team name above hedgehogs by default ||

|| hogtag || Boolean || Whether to show the hog name above hedgehogs by default ||

|| healthtag || Boolean || Whether to show the health above hedgehogs by default ||

|| tagopacity || Boolean || If true, name and health tags above hedgehogs are translucent ||

=== {{{[audio]}}} ===

_Sound settings for the sounds and music in the game itself_

|| *Setting* || *Type* || *Description* ||

|| sound=true || Boolean || If sound effects should be played  in-game ||

|| music=true || Boolean || If background music should be played in-game ||

|| volume=100 || Integer || Volume level (in percent) of sound effects and music ||

=== {{{[net]}}} ===

_Online and LAN settings_

|| *Setting* || *Type* || *Description* ||

|| nick=username || String || Username/nickname used for online play, or promt the user when first connecting if left blank ||

|| passwordhash=d41d8cd98f00b204e9800998ecf8427e || String || Hash of password used for online play ||

|| passwordlength=0 || Integer || Currently unused ||

|| savepassword=true || Boolean || If true, password will be saved ||

|| ip=10.0.0.0 || String || Default IP address or hostname when connecting to a LAN server ||

|| port=46631 || Integer || Default port number when connecting to a LAN server ||

|| servername=hedgewars server || String || Default name when creating a LAN server ||

|| serverport=46631 || Integer || Default port number when creating a LAN server ||

=== {{{[fps]}}} ===

_Frames per second settings_

|| *Setting* || *Type* || *Description* ||

|| show=false || Boolean || If the number of frames rendered per second should be shown in-game ||

|| limit=27 || Integer || Maximum number of frames rendered per second, calculated as _1000 / (35 - limit)_ ||

=== {{{[proxy]}}} ===

_Proxy settings_

|| *Setting* || *Type* || *Description* ||

|| type=0 || Integer || Proxy type. 0: no proxy, 1: system proxy, 2: SOCKS5 proxy, 3: HTTP proxy. The following settings are ignored if the proxy type is 0 or 1. ||

|| host || String || Hostname or IP adress of proxy ||

|| port || Integer || Port number of proxy ||

|| login || String || User name to login to the proxy ||

|| password || String || Password (in clear text) to login to the proxy ||

=== {{{[videorec]}}} ===

_Video recording settings_

|| *Setting* || *Type* || *Description* ||

|| format=mp4 || String || Container format (the file format of the resulting file) ||

|| videocodec || String || Video codec ||

|| audiocodec || String || Audio codec ||

|| framerate || Integer || Frame rate in frames per second ||

|| bitrate || Integer || The bit rate in 1000 bytes per second ||

|| width || Integer || Video width ||

|| height || Integer || Video height ||

|| usegameres || Boolean || If true, use the game resolution and ignore the width and height settings ||

|| audio || Boolean || Whether to use audio ||

=== {{{[colors]}}} ===

Setup 9 team colors here, the setting names are from `color0` to `color8`. The values are 3-byte hexadecimal numbers in RGB notation with “#” prefixed.

|| *Setting* || *Default* ||

|| color0 || #ff0204 ||

|| color1 || #4980c1 ||

|| color2 || #1de6ba ||

|| color3 || #b541ef ||

|| color4 || #e55bb0 ||

|| color5 || #20bf00 ||

|| color6 || #fe8b0e ||

|| color7 || #874b06 ||

|| color8 || #ffff01 ||

=== {{{[Binds]}}} ===

This section defines the global key bindings. They can be overwritten by teams.

Each key binding is written in the form `action=keycode`, e.g. “`ammomenu=b`” for opening the ammo menu with the B key.

==== Actions ====

|| *Setting* || *Description* ||

|| %2Bup || Up ||

|| %2Bleft || Left ||

|| %2Bright || Right ||

|| %2Bdown || Down ||

|| %2Bprecise || Precise ||

|| ljump || Long jump ||

|| hjump || High jump ||

|| switch || Switch hog ||

|| ammomenu || Ammo menu ||

|| slot%201 || Slot 1 ||

|| slot%202 || Slot 2 ||

|| slot%203 || Slot 3 ||

|| slot%204 || Slot 4 ||

|| slot%205 || Slot 5 ||

|| slot%206 || Slot 6 ||

|| slot%207 || Slot 7 ||

|| slot%208 || Slot 8 ||

|| slot%209 || Slot 9 ||

|| slot%20%3A || Slot 10 ||

|| timer%201 || Timer: 1 second ||

|| timer%202 || Timer: 2 seconds ||

|| timer%203 || Timer: 3 seconds ||

|| timer%204 || Timer: 4 seconds ||

|| timer%205 || Timer: 5 seconds ||

|| %2Battack || Attack ||

|| put || Place hedgehog or select target ||

|| findhh || Automatic camera / find hedgehog ||

|| %2Bcur_u || Move camera or cursor up ||

|| %2Bcur_l || Move camera or cursor left ||

|| %2Bcur_r || Move camera or cursor right ||

|| %2Bcur_d || Move camera or cursor down ||

|| zoomin || Zoom in ||

|| zoomout || Zoom out ||

|| zoomreset || Reset zoom ||

|| chat || Open chat input ||

|| chat%20team || Open clan chat input ||

|| history || Toggle chat history ||

|| pause || Toggle pause ||

|| quit || Quit ||

|| confirm || Confirm ||

|| %2Bvoldown || Raise volume ||

|| %2Bvolup || Lower volume ||

|| mute || Mute ||

|| fullscr || Toggle window mode (window/fullscreen) ||

|| capture || Take screenshot ||

|| %2Bspeedup || Increase demo replay speed ||

|| rotmask || Toggle team bars ||

|| rottags || Toggle hedgehog tags ||

|| record || Record video ||

==== Key codes ====

===== Keyboard =====

Keyboard names are based on the [https://wiki.libsdl.org/SDL_Scancode SDL scancode].

The key name is constructed as follows:

 * Take the name from the “Key Name” column of the aforementioned webpage

 * Convert it to lower-case

 * Replace spaces with underscores

Examples:

|| *Code* || Description ||

|| `a` || A ||

|| `f1` || F1 ||

|| `shift_left` || Left shift key ||

|| `space` || Space bar ||

|| `tab` || Tabulator ||

===== Mouse =====

The codes for the mouse are as follows:

|| *Code* || Description ||

|| `mousel` || Left mouse button ||

|| `mousem` || Middle mouse button ||

|| `mouser` || Right mouse button ||

|| `wheelup` || Mouse wheel up ||

|| `wheeldown` || Mouse wheel down ||

===== Controller/Gamepad/Joystick =====

Controllers, gamepads and joysticks are written in a somewhat cryptic syntax.

====== Buttons ======

Syntax: `jJbB`

 * `J`: Controller ID beginning with 0

 * `A`: Button ID beginning with 0

Examples:

|| *Code* || Description ||

|| `j0b0` || First controller, first button ||

|| `j0b1` || First controller, second button ||

|| `j1b2` || Second controller, third button ||

====== Axes ======

Syntax: `jJaAD`

 * `J`: Controller ID beginning with 0

 * `A`: Axis 

 * `D`: Axis direction. One of the following letters:

  * `u`: positive (“up”)

  * `d`: negative (“down”)

Examples:

|| *Code* || Description ||

|| `j0a0u` || First controller, first axis up ||

|| `j0a1d` || First controller, second axis down ||

|| `j1a1d` || Second controller, second axis down ||

====== Hats/D-pads ======

Syntax: `jJhHD`

 * `J`: Controller ID beginning with 0

 * `A`: D-pad ID 

 * `D`: Direction, it is one of 4 letters:

  * `u`: up

  * `r`: right

  * `d`: down

  * `l`: left

Examples:

|| *Code* || Description ||

|| `j0h0u` || First controller, first D-pad up ||

|| `j0h1l` || First controller, second D-pad left ||

|| `j1h1r` || Second controller, second D-pad right ||

== `Schemes/Game/<SchemeName>.hwg` ==

A game scheme. Each game scheme has its own file. `<SchemeName>` is the name of the scheme. Each game scheme setting is stored as a key-value pair, one setting per line:

|| *Setting* || *Type* || *Description* ||

|| switchhog=false || Boolean || If free hog switching is enabled on turn start ||

|| divteams=false || Boolean || If teams start at the opposite side of the terrain ||

|| solidland=false || Boolean || If land is indestructible ||

|| border=false || Boolean || If an insestructible border is added around the map ||

|| lowgrav=false || Boolean || If gravity is lowered ||

|| laser=false || Boolean || If aiming is assisted with laser sights ||

|| invulnerability=false || Boolean || If hogs have a personal forcefield ||

|| resethealth=false || Boolean || If living hogs' health is reset to 100 at end of round ||

|| vampiric=false || Boolean || If hogs gain life equal to 80 percent of the damage they deal ||

|| karma=false || Boolean || If hogs lose life equal to the damage they deal ||

|| artillery=false || Boolean || If hogs are unable to move ||

|| randomorder=true || Boolean || If turn order is generated randomly ||

|| king=false || Boolean || If a chess-like king is used ||

|| placehog=false || Boolean || If players take turns placing their hogs before the start of a game ||

|| sharedammo=false || Boolean || If ammo is shared between all teams of the same color ||

|| disablegirders=false || Boolean || If girders are removed from randomly-generated maps ||

|| disablelandobjects=false || Boolean || If land objects are removed from randomly-generated maps ||

|| aisurvival=false || Boolean || If AI hogs respawn on death ||

|| infattack=false || Boolean || If hogs can attack an unlimited number of times each turn ||

|| resetweps=false || Boolean || If weapons are reset at end of each turn ||

|| perhogammo=false || Boolean || If each hog has seperate ammo ||

|| disablewind=false || Boolean || If wind is disabled ||

|| morewind=false || Boolean || If wind is much stronger then usually ||

|| tagteam=false || Boolean || If players in a team share time on each turn ||

|| bottomborder=false || Boolean || If an indestructible border is added at the bottom of the map ||

|| damagefactor=100 || Integer || Percentage of damage dealt ||

|| turntime=45 || Integer || Maximum time in seconds of each turn ||

|| health=100 || Integer || The initial health of the hogs ||

|| suddendeath=15 || Integer || Number of rounds to play until Sudden Death begins, _after the first round was played_. 0 = SD starts in 2nd round ||

|| caseprobability=5 || Integer || Number of turns between cases drops ||

|| minestime=3 || Integer || Seconds before mines explode ||

|| minesnum=4 || Integer || Number of mines on a level ||

|| minedudpct=0 || Integer || Percentage chance of each mine being a dud ||

|| explosives=2 || Integer || Number of explosives on a level ||

|| healthprobability=35 || Integer || Percentage chance of each crate being a health crate ||

|| healthcaseamount=25 || Integer || Amount of life restored by each health crate ||

|| waterrise=47 || Integer || Number of pixels the water rises each turn in "Sudden Death" mode ||

|| healthdecrease=5 || Integer || Damage dealth each turn to hogs in water during "Sudden Death" mode ||

|| ropepct=100 || Integer || Maximum length of rope as a percentage ||

|| getawaytime=100 || Integer || Time you have to get away from an explosive after arming it, as a percentage ||

|| worldedge=0 || Integer || Type of world edges at the left and right side. `0` for no edge (default), `1` for wrap-around, `2` for bouncy edges, `3` for ocean. ||

|| scriptparam="" || String || 0.9.21: Script parameter, this is read by scripts. Can have any arbitrary srting value, the meaning of this value depends on the script used. ||

== `Schemes/Ammo/<SchemeName>.hwa` ==

A weapon scheme. `<SchemeName>` is the name of this weapon scheme. This file contains a long sequence of numbers between `0` to `9` to configure all weapon settings.

The number string has 4 equally long sections, in this order:

 * Start ammo (9 = infinite)

 * Crate probability (higher = more)

 * Ammo in crate

 * Delay

In each section, each number represents one weapon. The order of these weapons is noted in the source code file `weapons.h` ([https://hg.hedgewars.org/hedgewars/file/tip/QTfrontend/weapons.h#l24]). This means the first number of a section is for the grenade, followed by the cluster bomb, then bazooka, and so on.

== `schemes.ini` ==

Legacy file for game schemes for version 0.9.23 and older. Since 0.9.24, this file is no longer actively used, it is now only used to import schemes to the new format when the `Schemes/Game/` directory has not been created yet.

=== {{{[schemes]}}} ===

List of custom scheme settings as key-value pairs, each with a key of "index number of scheme backslash setting name". The only exception is `size` which holds the number of game schemes in this file.

|| *Setting* || *Type* || *Description* ||

|| size=1 || Integer || Number of custom scheme settings ||

|| 1\name=new || String || Name of scheme no. 1 ||

|| 1\fortsmode=false || Boolean || Whether forts are used in scheme no. 1. This is no longer used since 0.9.23 ||

|| 1\<setting>=value || _See above_ || A setting of scheme no. 1. `<setting>` is any of the game scheme settings listed above in the new game scheme format ||

== `weapons.ini` ==

Legacy file for weapon schemes for version 0.9.23 and older. Since 0.9.24, this file is no longer actively used, it is now only used to import weapon schemes to the new format when the `Schemes/Ammo/` directory has not been created yet.

=== {{{[General]}}} ===

_List of weapon settings as key-value pairs, each with a string name and integer value_

|| *Setting* || *Type* || *Description* ||

|| `<Scheme name>`=93919...11101 || Integer || Weapon settings. `<Scheme name>` is the name of the scheme. The number string has the same meaning as in the new ammo scheme file ||

== `TeamName.hwt` ==

These files are found in the `Teams` directory and contain the team settings, one file per team.

=== {{{[Team]}}} ===

_General team settings_

|| *Setting* || *Type* || *Description* ||

|| Name=!TeamName || String || Name of team ||

|| Grave=Statue || String || Type of grave created when hog dies ||

|| Fort=Plane || String || Type of fort if Forts Mode is enabled ||

|| Voicepack=Default || String || Sounds used for hog voice ||

|| Flag=hedgewars || String || Name of flag (flag file name without suffix). This is ignored for AI teams; their flags will always be based on their difficulty level ||

|| Difficulty=0 || Integer || Diffuculty of AI (1-5, 1 = most difficult), or human if 0 ||

|| Rounds=0 || Integer || _Unused_ ||

|| Wins=0 || Integer || _Unused_ ||

|| !CampaignProgress=0 || Integer || _Unused_ ||

=== {{{[Hedgehog0]}}} - {{{[Hedgehog7]}}} ===

_8 sections, one per hedgehog of the team_

|| *Setting* || *Type* || *Description* ||

|| Name=Hedgehog Name || String || Name of hog ||

|| Hat=!NoHat || String || Type of hat used by hog ||

|| Rounds=0 || Integer || _Unused_ ||

|| Kills=0 || Integer || _Unused_ ||

|| Deaths=0 || Integer || _Unused_ ||

|| Suicides=0 || Integer || _Unused_ ||

=== {{{[Binds]}}} ===

Key bindings of the team. Teams can optionally overwrite the global key bindings or leave everything at default.

This section follows the same format as in `settings.ini`, with one addition: The key code `default` is used for using the default (global) key binding.

==== Values ====

The special value “`default`” is for the default keybinding as specified in the game preferences.

Regarding other keys: See [Binds] of settings.ini.

=== {{{[Campaign%20<CAMPAIGN_NAME>]}}} ===

This section stores campaign variables which are stored and read by Lua scripts. Replace “`<CAMPAIGN_NAME>` with the folder name of the campaign. Example: The section for “A Classic Fairytale” would be “`[Campaign%20A_Classic_Fairytale]`”.

Campaign variables are stored on a key-value basis, where the key is the name of the campaign variable and the value is the value of the campaign variable.

Campaign variable names and their values can are chosen by the Lua script authors, but there are some special variables which are used to determine which missions are available in the main menu, and since 0.9.23, also to determine which missions and campaigns have been completed.

For linear campaigns, the variables `Progress` and `Won` are used.

For non-linear campaigns, the variables `UnlockedMissions`, `MissionX`, `MissionXWon` and `Won` are used.

The variables should not be mixed up.

Since Hedgewars 0.9.23, completed missions and campaigns get a check mark in the campaign screen.

|| *Setting* || *Type* || *Description* ||

|| `Progress` || Integer || Since version 0.9.23, this variable stands for the number of completed missions in a linear campaign, starting with mission 1. For each completed mission, the next one gets unlocked. Previous versions have a slightly trickier definition: If present, this number of missions _additional to the first mission_ are unlocked in the menu, starting with the second mission and continuing with the following missions in their regular order (as specified in `campaign.ini`). If the number is `0`, only the first mission is available. ||

|| `UnlockedMissions` || Integer || This number specifies how many missions are unlocked. If this variable is set, then the variables `Mission1`, `Mission2`, etc. must be used to specfify the IDs of the unlocked missions. ||

|| `MissionX` || Integer || E.g. `Mission1`, `Mission2`, etc. Contains the `campaign.ini` ID of the `X`th unlocked mission, must be used together with `UnlockedMissions` ||

|| `MissionXWon` || Boolean || E.g. `Mission1Won`, `Mission2Won`, etc. If `true`, the mission with the number `X` in `campaign.ini` has been completed. ||

|| `Won` || Boolean || If `true`, the team has completed the campaign. Note that campaign victory is completely separate from mission victory, so this setting must be set seperately. ||

By default, the first mission (Mission 1 in `campaign.ini`) is available.

==== Examples ====

Simple campaign with 10 missions, missions 1-5 are available and missions 1-4 count as completed:

{{{

[Campaign%20Simple_Campaign]

Progress=4

}}}

Simple 0.9.23 campaign with 6 missions. This campaign and all its missions have been unlocked and completed:

{{{

[Campaign%20Simple_Campaign_2]

Progress=6

Won=true

}}}

Complex campaign with 13 missions, missions 2, 7 and 3 are available (in that order):

{{{

[Campaign%20Complex_Campaign]

UnlockedMissions=3

Mission1=2

Mission2=7

Mission3=3

}}}

Another campaign with some custom campaign variables:

{{{

[Campaign%20Another_Campaign]

Progress=2

MyCustomVariable=54

MyCustomString=Hedgewars

}}}

=== {{{[Mission%20<MISSION_NAME>]}}} ===

This section stores mission variables. Mission variables are very similar to campaign variables, but they are for single missions (training/challenge/scenario) that are not part of a campaign. Replace “`<MISSION_NAME>` with the file name of the mission.

Like campaign variables, mission variables are stored on a key-value basis. You can choose custom names but there are also a few special key names with a special meaning.

`Won` is to mark victory and it's often useful to be used together with `onGameResult`. The other special keys are to store challenge records. Use these only when they make sense.

|| *Setting* || *Type* || *Description* ||

|| `Won` || Boolean || If `true`, the team has completed the mission. ||

|| `Highscore` || Integer || Team's best score in this mission, where higher = better ||

|| `Lowscore` || Integer || Team's best score in this mission, where lower = better ||

|| `TimeRecord` || Integer || Team's best time in this mission, where faster = better ||

|| `TimeRecordHigh` || Integer || Team's best time in this mission, where longer = better ||

|| `AccuracyRecord` || Integer || Team's highest accuracy in this mission, in percent ||

By default, the first mission (Mission 1 in `campaign.ini`) is available.