BatBrain

About BatBrain

BatBrain is a function library intended to greatly simplify writing a consult script. A general introduction, changelog, download, and forum discussion can be found in the BatBrain thread, but this page is the best place for scripters interested in writing a consult script with BatBrain to start. NOTE: BatBrain is not built into KoLmafia, it is a separate ASH script which you must download and import to make these functions available.

Spreads

BatBrain handles all damage done (both to you and to the monster) as spreads. In fact, it defines a data type called "spread":

typedef float[element] spread;

This means that all damage is a map of floats keyed by element, with positive values for damage and negative values for healing. We could have just used float[element] everywhere, but it strikes us as cleaner to use the single word "spread". You'll see this datatype occur fairly often if you peruse BatBrain and chances are if you're writing a combat script, before long you'll have to deal with one. Fortunately, there are some functions for dealing with spreads:

merge

spread merge(spread first ,spread second )

• first is the first spread to merge
• second is the second spread

Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

factor

spread factor(spread f ,float fact )

• f is the spread to factor
• fact is the factor

More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

to_html

string to_html(spread src )

• src is the spread to convert to HTML

This function returns an HTML string showing a spread the way KoL does, with elemental damage parenthesized and appropriately color-coded.

dmg_dealt

float dmg_dealt(spread action )

• action is the damage spread for a given source of monster damage

This function returns the actual damage a given spread would deal to your current opponent, accounting for the monster's resistances, vulnerabilities, and damage cap where applicable. For example, when fighting Groar, any cold damage present in action would be reduced to 1, and any damage of his vulnerable elements would be doubled. Secondly, any damage over Groar's soft damage cap would be reduced appropriately, and finally the damage would be summed together into a single float and returned.

dmg_taken

float dmg_taken(spread pain )

• pain is the damage spread for a given source of player damage

This function returns the actual damage a given spread would deal to the player, accounting for the player's elemental resistances and vulnerabilities.

Other Useful Functions

monster_stat

float monster_stat(string which )

• which can be "att","def". or "hp"

This function wraps ASH's monster_attack(), monster_defense(), and monster_hp() functions. Please use this function instead of the ASH functions, since the value may differ if you have enqueued actions causing BatBrain to predictively alter the monster's stats.

my_stat

float my_stat(string which )

• which can be "hp","mp", "Muscle", "Mysticality", or "Moxie"

This function wraps ASH's my_hp(), my_mp(), and my_buffedstat() functions. Anytime you're checking any of these five stats, please use this function rather than the ASH functions, for the same reason as above.

happened

boolean happened(string occurrence )

boolean happened(skill occurrence )

boolean happened(item occurrence )

boolean happened(advevent occurrence )

• occurrence is the advevent ID you want to check

Use this function to check if an action has already happened during this combat. For example, if you have already used a seal tooth on a previous round, or you have enqueued a seal tooth, happened("use 2") will return true. In addition to canonical action ID's (BALLS syntax), BatBrain also gives you a few other handles for special events: smusted, stolen, hipster_stats, sealwail, lackstool