diff options
Diffstat (limited to 'docs/source/config.rst')
| -rw-r--r-- | docs/source/config.rst | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/docs/source/config.rst b/docs/source/config.rst new file mode 100644 index 0000000..d3aed3f --- /dev/null +++ b/docs/source/config.rst @@ -0,0 +1,129 @@ +Configuration +============= + +Configuration Files +------------------- + +At the time of writing, this is the default configuration file: + +.. code-block:: ini + + [Graphics] + Screen width: 640 + Screen height: 480 + # FPS should not be greater than refresh rate. + Maximum FPS: 60 + + [Sound] + Muted: no + # Volume must be between 0.0 and 1.0. + Music volume: 1.0 + # Use space music background, which sounds cold and creepy. + Space theme: no + + [Control] + # Touch-friendly control + Touch: no + # Input values should be either from Mouse1 to Mouse3 or a keyboard key + # and they are case-insensitively read. + # Aliases for special keys are listed here (without the K_ part): + # http://www.pygame.org/docs/ref/key.html + # Key combinations are not supported. + New game: F2 + Toggle pause: p + Toggle mute: m + Move left: a + Move right: d + Move up: w + Move down: s + Long-range attack: Mouse1 + Close-range attack: Mouse3 + + [Record] + # Directory to write record of game states, leave blank to disable. + Directory: + # Number of snapshots per second. This is preferably from 3 to 60. + Frequency: 30 + + [Server] + # Enabling remote control will disable control via keyboard and mouse. + Enable: no + Host: localhost + Port: 42069 + # Timeout on blocking socket operations, in seconds. + Timeout: 1.0 + # Disable graphics and sound (only if socket server is enabled). + Headless: no + +By default, Brutal Maze also then tries to read site (system-wide) +and user configuration. + +Site Config File Location +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Apple macOS: ``/Library/Application Support/brutalmaze/settings.ini`` +* Other Unix-like: ``$XDG_CONFIG_DIRS/brutalmaze/settings.ini`` or + ``/etc/xdg/brutalmaze/settings.ini`` +* Microsoft Windows: + + * XP: ``C:\Documents and Settings\All Users\Application Data\brutalmaze\settings.ini`` + * Vista: Fail! (``C:\ProgramData`` is a hidden *system* directory, + however if you use Windows Vista, please file an issue telling us + which error you receive) + * 7 and above: ``C:\ProgramData\brutalmaze\settings.ini`` + +User Config File Location +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Apple macOS: ``~/Library/Application Support/brutalmaze/settings.ini`` +* Other Unix-like: ``$XDG_CONFIG_HOME/brutalmaze/settings.ini`` or + ``~/.config/brutalmaze/settings.ini`` +* Microsoft Windows (roaming is not supported until someone requests): + + * XP: ``C:\Documents and Settings\<username>\Application Data\brutalmaze\settings.ini`` + * Vista and above: ``C:\Users\<username>\AppData\Local\brutalmaze\settings.ini`` + +Command-Line Arguments +---------------------- + +.. code-block:: console + + $ brutalmaze --help + usage: brutalmaze [options] + + optional arguments: + -h, --help show this help message and exit + -v, --version show program's version number and exit + --write-config [PATH] + write default config and exit, if PATH not specified use stdout + -c PATH, --config PATH + location of the configuration file + -s X Y, --size X Y the desired screen size + -f FPS, --max-fps FPS + the desired maximum FPS + --mute, -m mute all sounds + --unmute unmute sound + --music-volume VOL between 0.0 and 1.0 + --space-music use space music background + --default-music use default music background + --touch enable touch-friendly control + --no-touch disable touch-friendly control + --record-dir DIR directory to write game records + --record-rate SPF snapshots of game state per second + --server enable server + --no-server disable server + --host HOST host to bind server to + --port PORT port for server to listen on + -t TIMEOUT, --timeout TIMEOUT + socket operations timeout in seconds + --head run server with graphics and sound + --headless run server without graphics or sound + +First, Brutal Mazes read the default settings, then it try to read site and +user config whose locations are shown above. These files are listed as fallback +of the ``--config`` option and their contents are fallback for other options +(if they are absent default values are used instead). We don't support control +configuration via CLI because that is unarguably ugly. + +If ``--config`` option is set, Brutal Maze parse it before other command-line +options. Later-read preferences will override previous ones. |