Batfactors

What is batfactors?

batfactors.txt is a data file used by BatBrain, containing information about all the various factors pertinent to battle. These are saved in a data-entry-friendly format rather than just saving a map of advevents, which would be bulkier and harder to edit. Most of BatBrain's knowledge about items, skills, equipment, etc. is found in this file. As it is publicly editable on the Map Manager, a guide to understanding the format could be handy for someone looking to either add new content or fix old or previously unspaded content.

The Format

Like all mafia data files, batfactors is a map file, in the following format:

record combat_rec {
   string ufname;          // user-friendly name, not really used by BatBrain
   string dmg;             // damage to monster
   string pdmg;            // damage to player
   string special;         // comma-delimited list of other action results
};
combat_rec [string, int] factors;

Note that the map has two indices. The first string represents the category. The second index is the integer identifying the relevant item/skill/familiar. For example the "bander" category, which contains information about your Bandersnatch's enhancements to combat skills, is indexed by skill number.

Category	Indexed by	What?
bander	skill number	Your Bandersnatch's enhancements to the specified skill.
chef	staff item number	Jiggle results for the specified chefstaff.
crown	familiar number	Results for the Crown of Thrones when the specified familiar is enthroned.
effect	effect number	Average per-round results when you have the specified effect active (e.g. passive damage).
fam	familiar number	Results for the specified familiar.
gear	equipment item number	Average per-round results when you have the specified item equipped.
hatrack	hat item number	Familiar results for your Mad Hatrack when it has the specified hat equipped.
item	item number	Results for throwing the specified combat item.
scare	pants item number	Familiar results for your Fancypants Scarecrow when it has the specified pants equipped.
skill	skill number	Results for casting the specified combat skill.

After these important identifiers comes the actual information. The first field, ufname, is merely to make the data file easy to read and isn't really used by BatBrain when reading the file. The remaining three fields contain all the information and need to be formatted in a certain way to be understood, but I believe you'll find that format both intuitive and easy to edit.

Spreads in Batfactors

The dmg and pdmg fields contain damage information, which is converted to a spread (float[element] map) in BatBrain. The format is versatile and can include formulas and any of BatBrain's fvars. Basically damage is expressed as

amount (elements)

where amount is the damage formula and elements is a comma (but not space!)-delimited list of elements, using "none" for physical damage, "perfect" for always-correctly-tuned damage, and "prismatic" for damage in all five elements. If the action does only physical damage, elements (and the preceding space) may be omitted. If multiple elements are present, the damage in amount will be equally distributed among those elements.

Examples

10	deals 10 physical damage
-10	heals 10 hit points
myhp/2	deals half of your current hitpoints in physical damage
10 spooky	deals 10 spooky damage
10 spooky,hot	deals 5 spooky damage and 5 hot damage
10 prismatic	deals 2 each of hot, cold, spooky, sleaze, and stench damage

For cases where the damage is not equally distributed among elements, the above pattern may be repeated, separated by a pipe:

Examples

3 hot|7 spooky	deals 3 hot damage and 7 spooky damage
50 prismatic|4 hot	deals 14 hot damage and 10 each of cold, spooky, sleaze, and stench

Special

Of course, events may have many results besides just damage, and that is all contained in the special field. The special field, quite simply, is a comma (and space)-delimited list of keywords and values, like so:

keyword1 value1, keyword2 value2, keyword3 value3

As few as 0 keywords and values may be present. Here are all the keywords BatBrain presently understands:

Keyword	Meaning of Value
aoe	For skills with an area of effect, specifies the maximum number of monsters the skill affects.
att	Monster attack modifier.
def	Monster defense modifier.
stun	Number of rounds the monster is stunned by this action, on average.
mp	Amount of MP gained/lost.
meat	Amount of meat gained/lost.
item	A semicolon+space-delimited list of item names. This action results in one of the items from this list. Estimated profit averages the value of these items.
monster	A monster name, or multiple pipe-delimited names. This event only happens for monsters specified here.
notmonster	A monster name, or multiple pipe-delimited names. This event happens for any monster except those specified here.
phylum	A phylum name. This event only applies to monsters of the specified phylum.
stats	Mys|Mox.
rate	For familiars only (which includes hatrack and scare categories). The action rate of the familiar, expressed as a percent (1.0 = 100%).
!!	Note. Usually used to explain something BatBrain is currently unable of knowing or tracking, i.e. unspaded data, ongoing damage, or some other strange mechanic.

Some keywords have no values. BatBrain merely checks for the presence of the keyword to determine the relevant information.

Keyword	Presence Indicates
once	The action can only be used once per combat.
endscombat	The action automatically ends combat.
custom	The action requires special handling and should be ignored by BatBrain.
retal	The results happen when the monster successfully hits you.
oncrit	The results happen when you get a critical hit.