GAME-SPECIFIC CONFIGURATION FILE GEMRB.INI
******************************************
$Id: GemRB_INI.txt 4503 2007-02-27 16:43:46Z wjpalenstijn $

Contents
--------
  - Introduction
  - INI File Format
  - Options Values Types
  - List of Options


Introduction
------------ 

gemrb.ini is a file containing game-specific configuration for GemRB
engine.  It's used for options with simple value types which are
specific to GemRB and which are not intended to be usually changed by
a user. More complicated configuration data (tables, etc.) are kept in
their own files. User specific configuration is in other file (GemRB.cfg).

[FIXME: eventually, this file could be searched for in user's config directory too]

This file's path can be 
  <source_dir>/gemrb/override/<game_type>/gemrb.ini
  <install_share_dir>/gemrb/override/<game_type>/gemrb.ini
  <install_dir>/override/<game_type>/gemrb.ini


INI File Format
---------------

gemrb.ini file is in Windows *.INI format. That means it's line
oriented, consisting of a list of options, each on its own
line. Options are grouped into sections, each section labeled with
section name in [brackets]. [FIXME: case sensitive??]. Comments have
to be on their own line, they start with semicolon (;) and last to the
end of the line.

Options are in this file described in the format optionname = <type>.
For the moment all the options have to be in [resources] section.


Options Values Types
--------------------
These are types of values used in description of particular options.

  resref - resource identifier as defined in KEY file, string of at most
      8 characters. The case is not important, but is usually written in
      all upper-case to be easily distinguished.

  string

  rgba_color - hexadecimal RGBA quadruplet written as #rrggbbaa, 
      e.g. #00ff00ff is opaque bright green.

  number - unsigned integer number

  bool - boolean value, for now either 0 (false) or 1 (true)


List of Options
---------------

CursorBAM = <resref>
- - - - - - - - - - -
Name of bitmap resource with cursor images (e.g. PST: CARET)


ButtonFont = <resref>
- - - - - - - - - - - 
Name of bitmap resource used for button font in dialog windows
(e.g. BG1: STONESML)


TooltipFont = <resref>
- - - - - - - - - - - -
Name of bitmap resource with font used to display tooltips 
(e.g. PST: TRMTFONT)


TooltipBack = <resref>
- - - - - - - - - - - -
Sprite displayed behind the tooltip text, if any. Leave undefined when
tooltips don't use background bitmap.
(e.g. BG1: TOOLTIP)


TooltipColor = <rgba_color>
- - - - - - - - - - - - - -
Tooltip text color. Default is #ffffffff, i.e. opaque white.


TooltipMargin = <number>
- - - - - - - - - - - - -
Space between tooltip text and sides of TooltipBack (x2)


GroundCircleBAM1 = <resref>
GroundCircleBAM2 = <resref>
GroundCircleBAM3 = <resref>/<int>
- - - - - - - - - - - - - - - - -
Sprites displayed as a ground circle under actors (PST only).
Actually, there should be this directive for each ground circle
size, from 1 to 3 (sizes in PST).

If the ResRef is immediately followed by a slash and a number, 
the bitmap is scaled down by this factor. That's used in PST, 
where resources exist for circle sizes 2 and 3 only.
(e.g. GroundCircleBAM1 = wmpickl/3)


INIConfig = <filename>
- - - - - - - - - - - -
Name of INI file from the original game. This file is searched for in
the game root directory.


Palette16 = <resref>
Palette32 = <resref>
Palette256 = <resref>
- - - - - - - - - - -
Palette bitmap resources for various number of colors in a gradient.
Each pixel line in these files is for one base color. Pixels in the
row then define the gradient of that color.


IgnoreButtonFrames = <bool>
- - - - - - - - - - - - - -
If set to 1, buttons will ignore frame numbers as set in button CHU
resource, and always use frames 0, 1, 2, 3 from their associated
BAM. (PST, ...)


AllStringsTagged = <bool>
- - - - - - - - - - -
If set to 1, .tlk tokens are always resolved regardless of the token
flag in dialog.tlk. Normally only BG2 has token flags (0), all other
games have this option set to 1.

HasDPLAYER = <bool>
- - - - - - - - - - 
If set to 1, then NPCs will get a default player script (DPLAYER2) set
when they join the party. PST has no such feature. 

HasPickSound = <bool>
- - - - - - - - - - -
If set to 1, items have a pick up sound resource reference instead of a
description icon. PST has this option. (Mutually exclusive with the 
HasDescIcon option).

HasDescIcon = <bool>
- - - - - - - - - - -
If set to 1, items have a description icon, instead of a pick up sound.
BG2 has this option. (Mutually exclusive with the HasPickSound option).

HasEXPTABLE = <bool>
- - - - - - - - - - -
If set to 1, then an exptable.2da file is responsible of storing quest
based experience awards. If the option doesn't exist, then the engine
will use xplist.2da table for a similar feature. AddXP2da and AddXPVar
scripting actions use this option to determine which .2da file to use.
XPList is bg2 specific, while exptable is an iwd2 feature.

SoundFolders = <bool>
- - - - - - - - - - -
If set to 1, then there are separate directories for each player
character soundset. IWD2 specific.

HasSongList = <bool>
- - - - - - - - - - -
If set to 1, then the music files are listed in a songlist.2da file.
Otherwise the music files are listed in a music.2da file. Original
BG1 and PST doesn't have either of these files (the list is hardcoded
into the engine), GemRB supplies a music.2da file for them.

UpperButtonText = <bool>
- - - - - - - - - - - - -
Set to 1 if button labels should be converted to upper-case (e.g. BG2)


LowerLabelText = <bool>
- - - - - - - - - - - -
Set to 1 if label text should be converted to lower-case.

HasPartyINI = <bool>
- - - - - - - - - - -
If set to 1, then there is a party.ini file describing pre-generated 
parties. Normally only IWD2 has this option set.

HasBeastsINI = <bool>
- - - - - - - - - - -
Whether original game data contains beasts.ini and quests.ini files
with descriptions of monsters and quests (PST only).

ForceStereo = <bool>
- - - - - - - - - - -
If set to 1, all acm files will be player as if they are stereo. 
Some early .ACM files (PST, IWD1) were encoded with a faulty channel
number, this option overrides the channel number.

TeamMovement = <bool>
- - - - - - - - - - -
If set to 1, the team always moves to the protagonist (first player).
This option is 1 for original PST.

OneByteAnimationID = <bool>
- - - - - - - - - - - - - -
If set to 1, then only the lower byte of the animation ID will be used 
to index the avatar.2da table. The upper byte is responsible for various
displaying properties (clown colour, transparency). This option is 1 for
original PST.  /warning/ Some other unrelated, but PST specific, features
are also controlled by this flag. One such example is the avatar icon
size in the saved games. If set to 1, then the avatar portrait won't be 
shrunk further. Otherwise the saved portrait bmp's will be shrunk 2:1.

AutomapINI = <bool>
- - - - - - - - - -
If set to 1, automap entries will be done PST style.

SmallFog = <bool>
- - - - - - - - - - -
Whether fog-of-war maintained in Map::ExploredBitmap is aligned with
map boundary (SmallFog=1, like in PST) or the fog is half a tile
larger in each of four cardinal directions (SmallFog=0, e.g. in BG2)

ReverseDoor = <bool>
- - - - - - - - - - -
If set to 1, doors will have a reversed open/closed state. PST quirk.

ProtagonistTalks = <bool>
- - - - - - - - - - - - -
If set to 1, only protagonist speaks with stranger for the whole party (PST).

HasKaputz = <bool>
- - - - - - - - - -
If set to 1, then death variables will be in a separate context.
This is PST specific.

IWDMapDimensions = <bool>
- - - - - - - - - - - - -
If set to 1, then the minimap dimensions are using the IWD specific ratio.

IWD2ScriptName = <bool>
- - - - - - - - - - - -
If set to 1, then areas always override the scripting name of the creature.
Normally there is an area flag for this.

DialogueScrolls = <bool>
- - - - - - - - - - - - -
If set to 1, dialogue window behaves as in PS:T - i.e. talk between 
Nameless One and others is appended into the window as it comes. If set to 0 (default) each new pair of NPC's talk and Nameless One's replies is written from the start of the page, like in BG2.

MaximumAbility = 25|40
- - - - - - - - - - - - -
Determines the maximum value of character abilities. Setting it to absurd values might cause problems. Its value should be 40 for IWD2, 25 for all other games.
