GAME-SPECIFIC CONFIGURATION FILE GEMRB.INI
******************************************

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]. Comments have to be on their own line, they
start with a 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)

ScrollCursorBAM = <resref>
- - - - - - - - - - - - - -
Name of bitmap resource with scroll cursor images (e.g. BG2: CURSARW)

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

MovieFont = <resref>
- - - - - - - - - - -
Name of bitmap resource used for the movie subtitles

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.

StrrefSaveGame = 0|1
- - - - - - - - - - -
Determines whether the GameScript action SaveGame uses the int0 paramater
to lookup a strref, or to look in savegame.2da for the save game name.

ReverseToHit = 0|1
- - - - - - - - - -
Determines whether higher armor class is better (iwd2) or worse (the rest).

RedrawTile = 0|1
- - - - - - - - -
Force redraw of some overlay tiles??

CheckAbilities = 0|1
- - - - - - - - - - -
Determines if character abilities should matter in item usability checks.

SpellBookIconHack = 0|1
- - - - - - - - - - - -
Enables the spell book icon name hack needed for ToB.

DeathOnZeroStat = 0|1
- - - - - - - - - - -
Determines whether characters should die if any of their primary stats
reaches zero.

BreakableWeapons = 0|1
- - - - - - - - - - - -
Determines if weapons can randomly break when used (1% chance in bg1).

SelectiveMagicRes = 0|1
- - - - - - - - - - - -
Determines whether the magic resistance applies to all effects, even the
beneficial ones.

HasHideInShadows = 0|1
- - - - - - - - - - - -
Enable this if the characters also have the IE_HIDEINSHADOWS stat besides
IE_STEALTH.

ProperBackstab = 0|1
- - - - - - - - - - -
Determines how many checks the backstabbing code does before treating an
attack as a backstab.

HasSpecificDamageBonus = 0|1
- - - - - - - - - - - - - - -
Determines if the game supports specific damage bonus like for example +10%
extra cold damage.

StealIsAttack = 0|1
- - - - - - - - - -
Determines whether a detected stealing attempt causes the shopkeep to turn hostile.

CutsceneAreascripts = 0|1
- - - - - - - - - -
Determines whether area scripts should run during cutscenes or not.
