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. The vast majority of BatBrain's knowledge about items, skills, equipment, monsters, 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. |
| cadenza | accordion item number | The results of Cadenza using the specified accordion. |
| canhandle | beans item number | The results of Canhandle when wielding the specified can of beans. |
| 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 | 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 | 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. |
| headbutt | hat item number | Bonus damage from the specified turtle helmet. |
| item | item number | Results for throwing the specified combat item. |
| monster | monster ID | Special monster attributes such as resistances, damage caps, and immunities. This category is a bit special (see below). |
| scare | pants item number | Familiar results for your Fancypants Scarecrow when it has the specified pants equipped. |
| servant | servant ID | Results for your servant as Ed the Undying. |
| skill | skill number | Results for casting the specified combat skill. |
| thrall | thrall ID | Per-round results from having the specified pasta thrall active. |
After these important identifiers comes the actual information. The first field, ufname (user-friendly name), exists solely to make the data file human-readable and isn't even 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. Since this value is handled by ASH's modifier_eval(), any of those key letters or text functions will also work. 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 or "perfect" for always-correctly-tuned damage. You may also use "prismatic" as shorthand for specifying 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.
| 10 | deals 10 physical damage |
| -10 | heals 10 hit points |
| 10*L | deals 10 times your level in physical damage |
| 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:
| 3 hot|7 spooky | deals 3 hot damage and 7 spooky damage |
| 50 hot,cold|4 hot | deals 29 hot damage and 25 cold damage |
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. For numeric values such as MP or meat, formulas may be used since (as with the spreads above) these values will be handled by modifier_eval(). 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. Defaults to 1 if no value is specified. |
| 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. |
| itemcost | An item required and expended by this action. This event uses up one of the specified item, and will be ignored if you lack it. |
| 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 | Substats earned, formatted as Mus|Mys|Mox. |
| custom | If specified at all, this action is a custom action and should not be used in regular automation. The optional value represents the type of custom action (runaway, yellow, attract, banish, copy, etc). |
| mutex | A mutually exclusive group this action belongs to. Any action in the group makes all other actions in the same-named group unavailable (e.g. Sauceror curses, sixguns, etc). |
| 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. |
| underwater | The action is only valid underwater. |
| retal | The results happen when the monster successfully hits you. |
| onhit | The results happen when you hit the monster with a melee attack. |
| oncrit | The results happen when you get a critical hit. |
The "monster" Category
The monster category is handled differently to the other categories. The monster attributes are not loaded into an advevent, so it is not handled by to_event() as all the other categories are. Here are the key differences:
First of all, the integer index is the monster's ID, which is accessible in the $monster.id proxy field. Since some monsters' IDs are unknown, and therefore are listed as 0, batfactors uses an arbitrary negative index for those monsters, checking to_monster(ufname) to find a match against the monster name.
Secondly, the dmg field does not contain damage information, but rather monster resistances/vulnerabilities, still expressed as a spread. For each element, 0 is normal, 1.0 is immunity, and -1.0 is vulnerability. Normal elemental resistances/vulnerabilities are already calculated by BatBrain, and physical resistance, though it can be specified, is accessible in the physical_resistance proxy field, so you only need to include resistance information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.
The pdmg field is also re-purposed -- for monsters, it specifies the monster's "penetration", also expressed as a spread. For each element, the monster treats your resistance as being lower by the amount of levels specified. Since $element[none] is usually used for physical damage, it is used here to specify DA penetration.
Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:
| Keyword | Value/Indicates |
|---|---|
| variable | The monster is variable and should not be loaded from cache. |
| nopotato | Potato-type familiars do not work vs. this monster. |
| nofamiliar | Your familiar will not act vs. this monster. |
| onlyhurtby X | The monster can only be damaged by X. Currently supported: aoe, pottery, healing, club (and all other weapon types) |
| aura X | The monster has an aura dealing X player damage (specified as a spread) every round. |
| retal X | Use this to specify retaliation damage (damage dealt to you when you succeed with a melee attack) as a spread. |
| maxround X | Use this to specify combats of unusual durations (e.g. "maxround 50" for basement monsters). |
| group X | Use this to specify group monsters, where X is the amount of monsters in the group (integer). |
| dmgformula X | Use this to specify a monster's unique damage formula as a spread (for example, Your Shadow uses "95+maxhp/6") |
| damagecap X | Use this to specify the monster's soft damage cap boundary (integer). |
| capexp X | This is only meaningful with a soft damage cap, and specifies the exponent used to reduce damage above the boundary. |
| dodge (X) | The monster has an X percent chance to dodge melee attacks. |
| autohit (X) | The monster has an X percent chance to automatically hit you (e.g. gremlins). |
| automiss (X) | The monster has an X percent chance to automatically miss you (e.g. crates). |
| nostagger (X) | The monster has an X percent chance to ignore staggers. |
| nostun (X) | The monster has an X percent chance to shrug a multi-round stunner each round. |
| noitems (X) | The monster has an X percent chance of blocking items (e.g. Bonerdagon). |
| noskills (X) | The monster has an X percent chance of blocking skills (e.g. Naughty Sorceress). |
| delevelres (X) | The monster resists X percent of delevel effects. |
| spellres (X) | The monster resists X percent of damage from combat spells. |
| dmgformula X | Specify a monster's unique formula for dealing damage. For example, the entry for Your Shadow includes "dmgformula 95+maxhp/6". |
| drpenetration X | The monster ignores your first X DR. The Doctor is IN! |
Any keyword that expresses a "percent" should be specified as a float between 0 and 1. For any keyword listed with (X) in parentheses, the value is optional and defaults to 1.0.