config.doc

Configurations can be specified by command-line arguments and by the
configuration file (it looks for ~/.superzz0rc by default). Command-line
arguments override whatever is in the [Options] division. Comments can be
made in the configuration file by # at the beginning of a line.

Each division of the configuration file starts with a line with [] around
the name of the division (mentioned below). If no division is specified
then the [Options] division will be used by default.


=== [Options] ===

Configuration format is the key and = and the value (if any one is omitted,
then the default value will be used instead). The possible keys are
explained below. (Default values may change in future; if you want to avoid
this, then you should explicitly set the value. Values that have been set
explicitly will not be overridden by future versions of Super ZZ Zero.)

alt_arrows
  Configures the effect of ALT and arrows in the board editor and screen
  editor. The first character tells what to be done and the rest is a
  8-bit decimal integer telling the multiplier. The things to be done can
  be "-" for normal, "s" for scrolling, and "m" for mark.

audio_buffer
  Audio buffer size; zero to disable audio.

audio_filter
  A filter coefficient for the audio.

audio_rate
  Audio sample rate (in Hz); zero to disable audio.

audio_volume
  Initial audio volume from 0 to 32767.

auto_suffix
  Set to 1 to automatically add the ".sav" suffix to entered file names
  that do not already have that suffix, or 0 to disable this feature.

block_color
  Colour of the selected block (in block mode) in the board editor. Zero
  means to just use the inverse colour.

brd_edit_status
  Set to 1 (default) to display the editor status line, or 0 to suppress.

confirm_overwrite
  Set to 1 (default) to ask to confirm overwriting an existing save file
  when using the F3 save menu (it never asks if you use F5).

ctrl_arrows
  See alt_arrows.

debug
  Set debug mode. The -e and -d switches both enable this automatically;
  this option allows it to be permanently enabled if desired.

default_colors
  If set to 1, then the default colours of elements selected from the F1
  to F12 menus in the board editor will be used, but if 0 then the colour
  specified by the user is used instead.

editor_auto
  Set to 1 (default) to enable some editor functions being automatic
  according to to the specifications in the assembly file (see the
  editops.doc for details). Set to 0 to disable some of these functions
  (others still work, or can be disabled in other ways).

editor_custom_labels
  Set to 1 (default) to enable custom labels in the editor. (These custom
  labels can be defined by the asm file; see editops.doc for details.)

editor_scroll_x
  Amount by which to scroll the board editor window if the cursor is moved
  out of the range of the screen.

editor_scroll_y
  Amount by which to scroll the board editor window if the cursor is moved
  out of the range of the screen.

enable_asn1_op
  Set to 1 to enable the ASN.1 operations, or 0 (which is the default) to
  disable them. In future, the default setting might be changed to enabled,
  or this setting might be removed entirely; do not rely on it too much.
  This will automatically be enabled if "external" is also specified.

event_input
  If set to 1, then it allows events to be read from stdin, in addition to
  occurring normally. Setting it to 0 disables this feature. Other numbers
  are not currently meaningful.

external
  An external command to run and connect to Super ZZ Zero. It is expected
  to communicate with its standard I/O in DER format. Game worlds should
  not use this feature except for specialized cases.

extra_lump_file
  See extra_lump_name.

extra_lump_name
  If defined as a lump name (which must be in all uppercase), and the lump
  is not found within the world file, then it will read it from the file
  named by the extra_lump_file option instead. This is mainly only useful
  for testing Super ZZ Zero itself, although there is the possibility that
  other uses for this may also be found.

file_list
  Specifies how files should be listed in a file list (currently, this
  means the save game file list). Use 0 to hide directories, 1 to show
  directories, 2 to list directories before regular files, and 3 to list
  directories after regular files. Add 4 to sort regular files descending
  by last modified time instead of by name. Add 8 to show hidden files.
  Add 32 if you want the default pattern to be "*" instead of "*.sav".

font_anim
  Set to 1 to enable font animations (if there are any defined in the
  world file) or 0 to disable font animations. This only affects animations
  that are defined in the .FNT lumps in the world file.

full_screen
  Set to 1 for full screen or 0 (default) for windowed. (If no windowing
  system is present, then it would be ignored.)

game_key_repeat
  Configure key repeat mode in the game. If it is 0 then this is the older
  behaviour of version 0.5.0. If it is 1 or 2 then it handles key repeat
  during the game in a special way while the key is held down; 1 will only
  start when the normal key repeat starts but 2 will start immediately.
  This does not affect menus at all.

help
  Name of a directory (including the trailing slash) of the online help
  files for the editor. This is not the same as the help lumps within a
  world file, although the file format is similar (but not the same).

joy_index
  The SDL joystick index number to use. To use joysticks, either joy_name
  or joy_index must be defined (but not both).

joy_name
  The SDL joystick name to match. To use joysticks, either joy_name or
  joy_index must be defined (but not both).

joy_sensitivity
  A number from 1 to 32767 indicating how far the joystick must be pushed
  in order to be recognized for translation to digital inputs. Higher
  numbers means that the joystick must be pushed more far from the centre
  in order to have any effect. (This only affects translation from analog
  to digital inputs within Super ZZ Zero itself. It is independent of any
  settings in Xorg, evdev, etc.)

key_repeat_delay
  Keyboad repeat delay.

key_repeat_interval
  Keyboard repeat interval.

mark_color
  Colour of marked tiles in the board editor. Zero means to just use the
  inverse colour.

menu_x
  The initial position of the F1 menu in the game.

menu_y
  The initial position of the F1 menu in the game.

message_scrollback
  Number of single-line text messages to store in the message scrollback.

message_timer
  Time limit for single-line text messages, in frames.

music_amp
  Music global amplitude, which is floating point.

music_debug
  Debug level for music, from 0 to 255. Zero (which is the default setting)
  disables the debug output for music.

music_resample
  Resampling mode for music. This must be defined in order for "BGM" music
  to work at all, and "0" is not valid. See the below section about the
  resampling configuration.

override_option
  Set to 1 to allow the options in the world file to override those in the
  configuration file and command-line arguments, or 0 to ignore override
  options in the world file. This only applies for world files that specify
  the options to be overridden.

overwrite_stats
  Set to 1 to allow overwriting stats by space or draw mode in the editor.

pause
  Set to 1 to automatically pause the game when starting; 0 (default) means
  that the game starts working immediately.

printer_begin
  Optional; specifies a name of a file with commands that will be sent to
  the printer at the beginning of a print job. In continuous mode, this
  file is only included once, before the first print.

printer_command
  On UNIX systems, this option specifies a system shell command to execute
  when you want to send text to a printer. It receives the text on stdin.

printer_end
  Optional; specifies a name of a file with commands that will be sent to
  the printer at the end of a print job. In continuous mode, this file is
  included after every print.

printer_option
  Configures printer-type-independent options for printing. See printer.doc
  for details.

printer_type
  Specifies the printer type. A PostScript printer cannot be specified
  here; if you use a PostScript printer then emulation is required. See
  printer.doc for details.

return_cancels
  Set to 1 (default) if the return key in a text window in the game play
  will cancel if the cursor is not at a link, like escape will do. If set
  to 0 then the return key will do nothing in such a circumstance.

save_dir
  Default directory to use for save game files. If not present, then the
  current directory will be used. If it starts with ~/ then it is relative
  to the current user's home directory. If it is ! then it will use a
  directory whose name is based on the world file name; it will replace
  ".sz0" with ".save" and use that directory, and will automatically create
  that directory if it does not already exist.

scr_edit_status
  Set to 1 (default) to display the editor status line, or 0 to suppress.

shift_arrows
  See alt_arrows. (Shift with arrows already has a meaning in the screen
  editor, so this only affects the board editor.)

show_status
  Set to 1 (default) to display the global status line, or 0 to hide it.
  (This setting has no effect in PC text mode.)

speed
  Game speed in milliseconds per frame, in normal speed mode.

speed_fast
  Game speed in milliseconds per frame, when fast-forward is activated.

template_board
  The board number to use as the template for new boards; the default value
  is zero. (See also: editor_auto)

temporary_file_1
  Name of temporary file for saving world files in the editor. The default
  value is ".superzz0_save". This must be in the same file system than the
  world file is stored in.

temporary_file_2
  Name of temporary file for saving test world files, when using the test
  function of the editor. The default value is ".superzz0_testgame". Note
  that this file will be deleted if it already exists.

test_mode
  Used for internal testing. The meaning of the value is undocumented (and
  may change in future), except that zero is used for normal operation.

text_editor_command
  If defined, an external command to execute for the text editor; the
  environment variable named "textfile" will contain the name of the
  temporary file. If this is not defined, then the internal text editor
  will be used instead.

text_editor_insert
  Controls the initial insert/overwrite mode in the text editor (not
  meaningful if text_editor_command is set). Set to 1 for insert mode
  or 0 for overwrite mode. This can be toggled by ^V at run time.

text_input
  Controls the mapping of keyboard inputs to character codes. If set to
  0, then the internal handling of SDL is used, but this only works for
  ASCII characters. If set to 1, then X11 keyboard handling is used. If
  set to 2, then it uses its own internal implementation (which assumes
  the US ASCII PC keyboard layout).

time_format
  The format to use for date/time display, in the same format of the
  strftime function in C.

time_utc
  Set to 1 to display date/time as UTC, or 0 (default) for local time.

version_auto
  Set to 1 (the default value) to automatically update the Super ZZ Zero
  version number in the world file when saving using the editor, so that
  an error message will be displayed when a new version of Super ZZ Zero
  is required or recommended for this world file if it is loaded using
  an older version.

version_check
  If set to 1 (which is the default value) then it checks the world
  version and file type by the !SZ0 lump; if 0 then it ignores them.

version_warn
  If set to 1 (which is the default value) then it will display a
  warning message if the world file lump specifies optional features
  or versions that do not match the current implementation.

video_gamma
  Can be three numbers with semicolons in between; affects the gamma
  setting of red, green, blue.

wave_resample
  Resampling mode for wave sounds. If it is "0" or undefined then it
  will use the SDL functions, which do not actually do any resampling.
  See the below section about resampling configuration.

wave_sound
  Set to 1 to enable wave sounds (the audio also must be configured).
  If set to 0 then wave sounds are disabled.


=== Resampling configuration ===

The resampling configuration consists of the following parameters with
spaces in between:

* Number of taps, from 4 to 1024; must be a multiple of four.

* Number of filters, from 1 to 1024.

* Optionally, L followed by a floating point number which is the low pass
filter ratio, which should be greater than 0.0 and less than 1.0.

* The letter B to use a Blackman Harris window, or H to use a Hann window.

* Optionally, I to enable subsample interpolation.


=== [Joystick] ===

Each line in this section has three parts, with colons in between:

* The buttons/axes/hats to be mapped.

* The levels. This can be an asterisk for all levels, or any combination
of the following: 0 for normal mode, 1 to 4 for a user-defined level, or
T for text windows.

* The command codes for this mapping.

The second and third parts can be repeated multiple times (after a command
code, another level and then another command, etc), as long as the levels
do not overlap, unless the first level is * in which case the rest of the
pairs will override the first one.

The first part of each line in this section consists of one or more the
following things, with commas in between:

* Button numbers preceded by an asterisk.

* Axis numbers preceded by - or + sign.

* Hat numbers preceded by a direction: n s e w

Any things listed together on the same line are considered to be
equivalent for the purpose of mapping. Up to 32 mappings can be defined.

The command codes are as follows:

* A normal key code; this can be a ASCII character with ' on both sides,
or one of the control keys: n s e w for unshifted arrows, N S E W for
shifted directions, b for backspace, t for tab, r for return. You may
prefix any of them by an exclamation mark for auto fire.

* One of the special command codes listed below.

* It can be a modifier button; use # and then a number 1 to 4 for the
modifier level.

* A string in quotation marks, representing the label to be mapped to; if
the world file contains a mapping for that label, it will use it. You may
optionally add a comma after the final quotation mark and then one of the
above possible command codes as well. See below for the possible escapes.

The following escapes are possible in label strings:

* \\ represents a backslash.

* \" represents a quotation mark.

* \x and two hex digits represents a PC character. (Null characters are not
allowed, and are meaningless, anyways.)

* \n \s \e \w represents primary arrows.

* \N \S \E \W represents secondary arrows.

Semicolons in label strings have a special meaning; you can have multiple
labels with semicolons in between and then whichever one is present in the
world file will be used, where the first one has priority over the others.

The possible special command codes are:

* ^0 = Toggle pause (same as the PAUSE key).

* ^1 = Display the F1 menu.

* ^2 = Toggle sound.

* ^5 = Quick save game (same as F5).

* ^7 = Quick restore game (same as F7).

* ^9 = Display the message scrollback.

* ^< = Display the previous page in a text window.

* ^> = Display the next page in a text window.

* ^A = Advance to next frame.

* ^F = Fast speed while button is held.

* ^T = Toggle speed (same as F12).

* ^X = Clear message.

* ^Z = Cancel a text window or other window.

* ^[ = Go to the top of a text window.

* ^] = Go to the bottom of a text window.


=== [Emulator] ===

This section is used for loading emulators for FM sound cards (or the
ability to use the real hardware, if it is available).

Each line has the file name (in the format accepted by dlopen; see the man
page for dlopen), and then a space and then the argument. The format of the
argument is defined by the plugin; see the plugin's documentation.

If multiple plugins register an emulator for the same OID, then only the
first one for each OID is used. This implementation is limited to no more
than 128 OIDs; if plugins try to register more than that, then any beyond
the first 128 are ignored. (Plugins that register a large number of OIDs
should probably have switches to disable some of them.)

It is possible to specify the same file multiple times with different
arguments in each case, although plugins are not guaranteed to support
that use, and this might cause undesired behaviours (and/or errors).


=== [Colors] ===

Defines the palette for the editor and system UI (including the F1 menu,
the save/restore game menu, etc). This palette is also used for any game
world that does not define its own palettes.

There are two syntaxes in this division. One is the hexadecimal colour
number followed by = and then the hexadecimal RGB colour (six hex digits).
The other is * followed a base64 encoding of the sixteen RGB colours, using
the base64 variant that is used in sixel graphics.

The hexadecimal colour number before = can be "0" to "F", or it can be "20"
for the screen border, and "21" for the text below the screen border.

Default colours:
*??????Ai?Ig??Iiii_??i_AiieW?iiiiTTTTTTV~T^|TT^~~~tTT~tV~~~|T~~~~

IBM 5153 colours:
*??????BC?KO??KRCp???p?BCpFw?pKRCRcxMRcz[RlpMRnNrvCxM{szr{~LM~~~~