
             Modifier Configuration File Notes

Change History:
    NatVac, 2009/01/25 - Field Alias support added
    NatVac, 2008/11/01 - FileChoice warning added
    NatVac, 2008/02/15 - Checkbox support added
    NatVac, 2007/11/08 - Initial release

There should be a mod customization file with the extension ".cfg", and a corresponding text file ending in .cfg.txt for the notes about the mod's customization file.  This file will be shown when the Config Notes button is clicked.

All files in the same directory as the Modifier program that have the ".cfg" extension will be shown in the dropdown combobox in the upper left of the window when the program is launched.

The Modifier program uses a straightforward MS-DOS INI file format, with each configurable item listed as a section name surrounded by square brackets followed by the item's parameters in "name=value" format.

Configurable items can have spaces.  When the configuration file is read, these items are listed (without the enclosing brackets) in the listbox on the left side of the program's window.

The "name=value" entries must not have spaces between the end of the name and the start of the value.  Spaces within the value strings are fine.

Perhaps the best way to present the structure is via explicit examples.  There are currently two types of entries, FileChoice and Field.  (More types may be added as needed.)


   The FileChoice Item:

[Name Of Configurable Item]
Title=Big Bold Short Description of Item
Type=FileChoice
NumberOfFiles=1
Target=relative\path\under\gamedata\file.ext
Choices=2
Choice1=Original
Choice1Source=
Choice2=Alternative
Choice2Source=relative\path\under\gamedata\file.ext.alternative
ToolTip=The user sees this tip when he or she\nmoves the mouse over the radio group box.

In the FileChoice example above, there is only one file being transferred from two sources.  An empty source means no file; when such is chosen, the original is backed up if possible, and then deleted if it exists.

At the moment, only one FileChoice item is allowed per configurable item. You can have multiple destination files, and more than two sources (currently, up to five).  They would look like this:

[Name Of Configurable Item]
Title=Big Bold Short Description of Item
Type=FileChoice
NumberOfFiles=2
Target1=relative\path\under\gamedata\file.ext
Target2=relative\path\under\gamedata\file2.ext
Choices=3
Choice1=Original
Choice1Source1=
Choice1Source2=
Choice2=New
Choice2Source1=relative\path\under\gamedata\file.ext.alternative
Choice2Source2=relative\path\under\gamedata\file2.ext.alternative
Choice3=New
Choice3Source1=relative\path\under\gamedata\file.ext.alternative
Choice3Source2=relative\path\under\gamedata\file2.ext.alternative
ToolTip=The user sees this tip when he or she\nmoves the mouse over the radio group box.

NumberOfFiles is optional and assumed to be 1 if missing.  The Type value case is not important, but names to the left of the equal sign should be camel-cased as shown.  The tooltip parameter is optional.  Note the use of "\n" to break the tooltip up into multiple lines.

When the Apply button is clicked, the corresponding choice's source files are copied to the target files after the original target files are backed up to "filename.ext.original" if possible.  Be sure to keep the source names synchronized with the destination names. 

The "1" is optional in each occurrence on the left side of the equal sign if there is only one corresponding item.  For a single file, single choice* you could have:

ChoiceSource=
Choice1Source=
ChoiceSource1=
Choice1Source1=

*A single choice is not normal here!

However, you must have the character "1" for the first choice when there are 2 or more choices, and the character "1" for the first source when there are two or more source files.


   The Field Item:

[Quest Time Limits]
Title=How Long Should Quests Take?
Parameters=3
Type1=Field
File1=scripts\task_manager.script
Name1=quest_days
Value1=5
DefaultValue1=5
ToolTip1=Set the number of days to complete a normal quest.\nZero means no time limit.
Type2=Field
File2=scripts\task_manager.script
Name2=autoquest_days
Value2=0
DefaultValue2=0
ToolTip2=Set the number of days to complete an auto-quest.\nZero means no time limit.
Type3=Field
File3=scripts\task_manager.script
Alias3=before task can repeat
Name3=idle_time_days
Value3=1
DefaultValue3=1
ToolTip3=Set the default number of days delay\nafter completing or rejecting a\nquest before you can get it again.\nZero means don't ever repeat a quest.

You can have up to five fields for a Field-based configuration entry.  They can refer to five different files, or the same file can be reused.  The system is smart enough to change and save just one instance.

The Parameters entry says how many fields will follow.  If missing, one field is assumed.

Fields are used to edit assignment values in both configuration and script files, of the form "variable = value".  The variable is the text to the left of the "=" sign, so it could be more than one word (e.g., "local reload_time").

The Name parameter is shown above the edit box, and it is used to match the variable entry in the file to be changed.

Note the Alias entry for the third parameter in the example.  It is an optional entry, to help clarify the variable name.  The display will show the field label in the form "name (alias)".

Right now, the Value field is normally not used; the actual value will be taken from the file entry.

The DefaultValue is shown to the right of the edit box for the field, and is the value that will be put into the edit box when the Default button is clicked.

Here is a more complex field item example:

[Carry Weight]
Title=How much Marked One can carry
Parameters=3
Type1=Field
File1=config\creatures\actor.ltx
Section1=[actor]
Name1=max_item_mass
Value1=150.0
DefaultValue1=50.0
ToolTip1=Up to this amount, you won't tire as easily.
Type2=Field
File2=config\creatures\actor.ltx
Section2=[actor_condition]
Name2=max_walk_weight
Value2=200.0
DefaultValue2=60.0
ToolTip2=If you weigh more than this,\nyou will not be able to move.
Type3=Field
File3=config\system.ltx
Section3=[inventory]
Name3=max_weight
Value3=150.0
DefaultValue3=50.0
ToolTip3=This affects the color on the inventory screen.\nIt should be the same as max_item_mass.

Note the use of Section here.  You can also specify a Subsection to further refine the match; it uses the same form as Section.  The brackets are required for the right-hand side of both Section and Subsection.

The files to be changed must exist.  You could specify a FileChoice for the first configurable item, and note that in your Mod.cfg.txt file.


   The LineToggle Item:

New with the 1.1 release: Checkbox support via the LineToggle item.  It follows the same form as the Field item:

[_ZRP Mod Stuff]
Title=Special _z.script Options
Parameters=4
Type1=LineToggle
File1=scripts\_z.script
Name1=Anomaly Evasion (Stalkers Are Not Blind 0.99)
Unchecked1=sanb_enabled = false
Checked1=sanb_enabled = true
DefaultValue1=Unchecked
ToolTip1=Enable/disable the ability of stalkers to avoid anomalies.\nRed75's famous mod.
Type2=LineToggle
File2=scripts\_z.script
Name2=Automatic ammo boxing
Unchecked2=ammo_aggregation = false
Checked2=ammo_aggregation = true
DefaultValue2=Checked
ToolTip2=Enable/disable the automatic repackaging of ammo\ninto complete boxes (IG2007's Dunin ammo fix).
Type3=LineToggle
File3=scripts\_z.script
Name3=Show Animations on Main Menu
Unchecked3=mainmenu_anims = false
Checked3=mainmenu_anims = true
DefaultValue3=Checked
ToolTip3=Enable/disable the animations or movies on screen menus.
Type4=LineToggle
File4=scripts\_z.script
Name4=Antirad Hotkey
Unchecked4=use_antirad_hotkey = false
Checked4=use_antirad_hotkey = true
DefaultValue4=Checked
ToolTip4=If checked, pressing Esc followed by F1 will\nadminister a dose of antirad if you have one.

There is a Checked entry and an Unchecked entry.  The program will look through the file and set the checkbox depending on which of the entries is found, or it will show an error message.  You can use Section and Subsection here, just as with Field items.

The DefaultValue is the state of the checkbox (Checked or Unchecked).

