Kolmafia - User contributions [en]

Last choice

2020-03-11T17:05:56Z

Zarqon: Created page

{{
#vardefine:name|last_choice}}{{
#vardefine:return_type|int}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
return_type={{#var:return_type}}|

}}|

function_description=Returns the number of the last choice you encountered, whether you are currently in it or not. Use [[handling_choice|handling_choice()]] to determine if you are currently in a choice.

}}

[[Category:Adventuring]]

Handling choice

2020-03-11T17:02:46Z

Zarqon: Page creation

{{
#vardefine:name|handling_choice}}{{
#vardefine:return_type|boolean}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|

}}|

function_description=Returns true if you are currently in a choice and [[last_choice|last_choice()]] and [[available_choice_options|available_choice_options()]] are accurate for the choice.|
see_also={{SeeAlso|choice_follows_fight|available_choice_options|last_choice|run_choice}}|

}}

[[Category:Adventuring]]

Batfactors

2018-10-01T16:37:35Z

Zarqon: added dmgformula keyword

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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.

Batfactors

2018-10-01T16:34:29Z

Zarqon: better wording

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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.
|-
|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.

Batfactors

2018-10-01T16:32:45Z

Zarqon: added mutex keyword

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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 X
|If specified, this action is part of a mutually exclusive group X. Any action in group X makes all other actions in the 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.

{| class="wikitable"
!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:

{| class="wikitable"
!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.
|-
|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.

Batfactors

2018-10-01T16:30:22Z

Zarqon: added "servant" category

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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.
|-
|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.

Batfactors

2018-09-21T16:47:38Z

Zarqon: new keyword 'dmgformula'

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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.
|-
|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.

Batfactors

2018-08-31T17:22:03Z

Zarqon: aoe

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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).
|-
|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.
|-
|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.

BatBrain

2018-08-31T16:54:34Z

Zarqon: "finished"

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download instructions, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready; attack/jiggle/skill s/use i
string cid; // unique combat identifier: lastCombatStarted
spread dmg; // raw dmg dealt, before resists/vulns
spread pdmg; // raw dmg taken, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // this action ends combat
string custom; // if not empty, this action should not be used in normal automation -- value is action category (banish, attract, yellow, copy, runaway, etc)
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m; // the monster currently being fought
record monster_data {
int variable; // the +ML currently being run; if the same, the monster will be reloaded from cache
boolean nopotato; // potatos are useless here
boolean nofamiliar; // your familiar is useless here
spread aura; // passive damage dealt to you every round
spread retal; // damage dealt to you if you hit with a melee attack
spread res; // resistances to each element, expressed as -1.0 (vulnerability) to 1.0 (immunity)
spread pen; // the monster's penetration ($element[none] for DA penetration)
int drpen; // DR penetration. The doctor is IN!
int howmany; // group monster size (default 1)
int multiattack; // number of attacks per round (default 1)
int maxround; // combat lasts till this round (default 30)
int damagecap; // damage in amounts beyond this will be reduced...
float capexp; // ...by this exponent
float autohit; // chance of automatically hitting, regardless of moxie
float automiss; // chance of automatically missing
float nostagger; // chance of shrugging staggers. Usually 1.0 if anything
float nostun; // chance of shrugging multi-round stuns
float noitems; // chance of ignoring combat items
float noskills; // chance of ignoring skills
float delevelres; // percent resistance to deleveling
float spellres; // percent resistance to spells
float dodge; // chance of dodging melee attacks
string onlyhurtby; // can only be damaged by X. possible: aoe, club, pottery, healing
string[string] dmgkey; // normalized damage type(s) vs. this monster (sauce, pasta, perfect)
string note; // special note about this monster
};
monster_data mdata; // m's monster_data
float mvalcache; // the value of the monster, including substats and meat/item drops
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
boolean[monster, int, string, int] happenings; // events that have happened in this fight. Indices: m, lastCombatStarted, action id, round => playeraction
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // empty by default; calling scripts may insert additional macro code to batround (macro called each round between actions), formatted as "commands; "
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|finished}}{{Function|
name=finished|
return_type=boolean|
}}
This function simply returns true if your combat is over. Useful as a condition in your combat script's master while() loop.

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|which}} can be one of: att, def, hp, drpen, howmany, damagecap, capexp, autohit, automiss, nostun, noskills, noitems, nostagger, delevelres, spellres, dodge, or itemres|
}}
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. This function is also used to return any of the special monster attributes listed above (these attributes are specified in [[batfactors]]).

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

[[Category:ASH Function Libraries]]

BatBrain

2018-08-31T16:54:05Z

Zarqon: BatBrain is a function library

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download instructions, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready; attack/jiggle/skill s/use i
string cid; // unique combat identifier: lastCombatStarted
spread dmg; // raw dmg dealt, before resists/vulns
spread pdmg; // raw dmg taken, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // this action ends combat
string custom; // if not empty, this action should not be used in normal automation -- value is action category (banish, attract, yellow, copy, runaway, etc)
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m; // the monster currently being fought
record monster_data {
int variable; // the +ML currently being run; if the same, the monster will be reloaded from cache
boolean nopotato; // potatos are useless here
boolean nofamiliar; // your familiar is useless here
spread aura; // passive damage dealt to you every round
spread retal; // damage dealt to you if you hit with a melee attack
spread res; // resistances to each element, expressed as -1.0 (vulnerability) to 1.0 (immunity)
spread pen; // the monster's penetration ($element[none] for DA penetration)
int drpen; // DR penetration. The doctor is IN!
int howmany; // group monster size (default 1)
int multiattack; // number of attacks per round (default 1)
int maxround; // combat lasts till this round (default 30)
int damagecap; // damage in amounts beyond this will be reduced...
float capexp; // ...by this exponent
float autohit; // chance of automatically hitting, regardless of moxie
float automiss; // chance of automatically missing
float nostagger; // chance of shrugging staggers. Usually 1.0 if anything
float nostun; // chance of shrugging multi-round stuns
float noitems; // chance of ignoring combat items
float noskills; // chance of ignoring skills
float delevelres; // percent resistance to deleveling
float spellres; // percent resistance to spells
float dodge; // chance of dodging melee attacks
string onlyhurtby; // can only be damaged by X. possible: aoe, club, pottery, healing
string[string] dmgkey; // normalized damage type(s) vs. this monster (sauce, pasta, perfect)
string note; // special note about this monster
};
monster_data mdata; // m's monster_data
float mvalcache; // the value of the monster, including substats and meat/item drops
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
boolean[monster, int, string, int] happenings; // events that have happened in this fight. Indices: m, lastCombatStarted, action id, round => playeraction
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // empty by default; calling scripts may insert additional macro code to batround (macro called each round between actions), formatted as "commands; "
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|finished}}{{Function|
name=monster_stat|
return_type=boolean|
}}
This function simply returns true if your combat is over. Useful as a condition in your combat script's master while() loop.

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|which}} can be one of: att, def, hp, drpen, howmany, damagecap, capexp, autohit, automiss, nostun, noskills, noitems, nostagger, delevelres, spellres, dodge, or itemres|
}}
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. This function is also used to return any of the special monster attributes listed above (these attributes are specified in [[batfactors]]).

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

[[Category:ASH Function Libraries]]

Zlib

2018-08-31T16:19:15Z

Zarqon: added kadrop()

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them). Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|stringlist}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|stringlist}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|stringlist}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|stringlist}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|stringlist}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|stringlist}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|stringlist}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|stringlist}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|stringlist}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|varname}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p2desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it adds it and the default value specified in {{pspan|dfault}} to vars_defaults.txt. Also, if the setting has been changed from its default value, it normalizes the value according to the type of {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing defaults, not for editing existing settings. That is done by calling ZLib in the CLI or running a setting editor tool such as Prefref Plus.

{{HideLink|getvar}}{{Function|
name=getvar|
return_type=string|
parameter1={{Param|string|varname}}|
p1desc={{pspan|name}} is the setting to retrieve the value of|
}}
This function returns the value of the specified script setting. Authors are encouraged to use this rather than a direct vars[] lookup, since values which have not been changed from the default will eventually not be present in vars[].

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them.
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia properties (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, all ZLib setting default values are stored in vars_defaults.txt in your data directory. Your character's ZLib settings that have been changed from default are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will initialize the settings -- saving their default value and type in vars_defaults.txt -- when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Use setvar() to initialize a setting that your script will reference. To reference the setting, use getvar() and convert from string to whichever type the setting is supposed to be. Accessing vars[] or vardefaults[] directly is not recommended, as a value may exist in one but not the other, or both.
* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence in vardefaults[], which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* Settings are intended to be set only by users, not scripts. If you want a persistent variable that a script will use, consider static variables. However, there may be cases where a script needs to edit a setting (i.e. a relay script specifically for editing settings). To alter a setting, change the map entry directly with vars["propertyToChange"] = newValue, followed by updatevars() to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads the setting defaults from vars_defaults.txt and a map of your script settings that have been changed from vars_myname.txt. To access a script setting within an ASH script, use getvar(varname).

When a script calls setvar("threshold",4), ZLib checks to see if a setting called "threshold" already exists. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist, it initializes its default value to 4, its type to int, and saves those defaults back to vars_defaults.txt. The setting may now be accessed by getvar() or edited using ZLib in the CLI.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" is used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|kadrop}}{{Function|
name=kadrop|
return_type=float|
parameter1={{Param|monster|m}}|
p1desc={{pspan|m}} is the monster under inquiry|
}}
Returns the amount of ka dropped by {{pspan|m}} as Ed the Undying, accounting for priest servants and the crown of Ed. Will always return 0 outside of Edcore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // including items/meat gained
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
return (m.fromname == "Your Pen Pal");
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

[[Category:Scripting]][[Category:ASH Function Libraries]]

BatBrain

2017-06-01T04:40:20Z

Zarqon: advevents changed slightly

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready; attack/jiggle/skill s/use i
string cid; // unique combat identifier: lastCombatStarted
spread dmg; // raw dmg dealt, before resists/vulns
spread pdmg; // raw dmg taken, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // this action ends combat
string custom; // if not empty, this action should not be used in normal automation -- value is action category (banish, attract, yellow, copy, runaway, etc)
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m; // the monster currently being fought
record monster_data {
int variable; // the +ML currently being run; if the same, the monster will be reloaded from cache
boolean nopotato; // potatos are useless here
boolean nofamiliar; // your familiar is useless here
spread aura; // passive damage dealt to you every round
spread retal; // damage dealt to you if you hit with a melee attack
spread res; // resistances to each element, expressed as -1.0 (vulnerability) to 1.0 (immunity)
spread pen; // the monster's penetration ($element[none] for DA penetration)
int drpen; // DR penetration. The doctor is IN!
int howmany; // group monster size (default 1)
int multiattack; // number of attacks per round (default 1)
int maxround; // combat lasts till this round (default 30)
int damagecap; // damage in amounts beyond this will be reduced...
float capexp; // ...by this exponent
float autohit; // chance of automatically hitting, regardless of moxie
float automiss; // chance of automatically missing
float nostagger; // chance of shrugging staggers. Usually 1.0 if anything
float nostun; // chance of shrugging multi-round stuns
float noitems; // chance of ignoring combat items
float noskills; // chance of ignoring skills
float delevelres; // percent resistance to deleveling
float spellres; // percent resistance to spells
float dodge; // chance of dodging melee attacks
string onlyhurtby; // can only be damaged by X. possible: club, pottery, healing
string[string] dmgkey; // normalized damage type(s) vs. this monster (sauce, pasta, perfect)
};
monster_data mdata; // m's monster_data
float mvalcache; // the value of the monster, including substats and meat/item drops
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
boolean[monster, int, string, int] happenings; // events that have happened in this fight. Indices: m, lastCombatStarted, action id, round => playeraction
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // empty by default; calling scripts may insert additional macro code to batround (macro called each round between actions), formatted as "commands; "
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|which}} can be one of: att, def, hp, drpen, howmany, damagecap, capexp, autohit, automiss, nostun, noskills, noitems, nostagger, delevelres, spellres, dodge, or itemres|
}}
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. This function is also used to return any of the special monster attributes listed above (these attributes are specified in [[batfactors]]).

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

BatBrain

2017-06-01T04:18:19Z

Zarqon: Monster data has changed considerably

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready name -- attack/jiggle/skill s/use i
spread dmg; // raw dmg dealt to the monster, before resists/vulns
spread pdmg; // raw dmg taken by the player, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // whether or not this action ends the combat
string custom; // flag for special actions that should not be used in normal automation
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m; // the monster currently being fought
record monster_data {
int variable; // the +ML currently being run; if the same, the monster will be reloaded from cache
boolean nopotato; // potatos are useless here
boolean nofamiliar; // your familiar is useless here
spread aura; // passive damage dealt to you every round
spread retal; // damage dealt to you if you hit with a melee attack
spread res; // resistances to each element, expressed as -1.0 (vulnerability) to 1.0 (immunity)
spread pen; // the monster's penetration ($element[none] for DA penetration)
int drpen; // DR penetration. The doctor is IN!
int howmany; // group monster size (default 1)
int multiattack; // number of attacks per round (default 1)
int maxround; // combat lasts till this round (default 30)
int damagecap; // damage in amounts beyond this will be reduced...
float capexp; // ...by this exponent
float autohit; // chance of automatically hitting, regardless of moxie
float automiss; // chance of automatically missing
float nostagger; // chance of shrugging staggers. Usually 1.0 if anything
float nostun; // chance of shrugging multi-round stuns
float noitems; // chance of ignoring combat items
float noskills; // chance of ignoring skills
float delevelres; // percent resistance to deleveling
float spellres; // percent resistance to spells
float dodge; // chance of dodging melee attacks
string onlyhurtby; // can only be damaged by X. possible: club, pottery, healing
string[string] dmgkey; // normalized damage type(s) vs. this monster (sauce, pasta, perfect)
};
monster_data mdata; // m's monster_data
float mvalcache; // the value of the monster, including substats and meat/item drops
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
boolean[monster, int, string, int] happenings; // events that have happened in this fight. Indices: m, lastCombatStarted, action id, round => playeraction
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // empty by default; calling scripts may insert additional macro code to batround (macro called each round between actions), formatted as "commands; "
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|which}} can be one of: att, def, hp, drpen, howmany, damagecap, capexp, autohit, automiss, nostun, noskills, noitems, nostagger, delevelres, spellres, dodge, or itemres|
}}
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. This function is also used to return any of the special monster attributes listed above (these attributes are specified in [[batfactors]]).

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

Zlib

2017-05-14T15:54:47Z

Zarqon: Kmail message now includes items/meat gain

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them). Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|varname}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p2desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it adds it and the default value specified in {{pspan|dfault}} to vars_defaults.txt. Also, if the setting has been changed from its default value, it normalizes the value according to the type of {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing defaults, not for editing existing settings. That is done by calling ZLib in the CLI or running a setting editor tool such as Prefref Plus.

{{HideLink|getvar}}{{Function|
name=getvar|
return_type=string|
parameter1={{Param|string|varname}}|
p1desc={{pspan|name}} is the setting to retrieve the value of|
}}
This function returns the value of the specified script setting. Authors are encouraged to use this rather than a direct vars[] lookup, since values which have not been changed from the default will eventually not be present in vars[].

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them.
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia properties (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, all ZLib setting default values are stored in vars_defaults.txt in your data directory. Your character's ZLib settings that have been changed from default are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will initialize the settings -- saving their default value and type in vars_defaults.txt -- when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Use setvar() to initialize a setting that your script will reference. To reference the setting, use getvar() and convert from string to whichever type the setting is supposed to be. Accessing vars[] or vardefaults[] directly is not recommended, as a value may exist in one but not the other, or both.
* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence in vardefaults[], which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* Settings are intended to be set only by users, not scripts. If you want a persistent variable that a script will use, consider static variables. However, there may be cases where a script needs to edit a setting (i.e. a relay script specifically for editing settings). To alter a setting, change the map entry directly with vars["propertyToChange"] = newValue, followed by updatevars() to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads the setting defaults from vars_defaults.txt and a map of your script settings that have been changed from vars_myname.txt. To access a script setting within an ASH script, use getvar(varname).

When a script calls setvar("threshold",4), ZLib checks to see if a setting called "threshold" already exists. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist, it initializes its default value to 4, its type to int, and saves those defaults back to vars_defaults.txt. The setting may now be accessed by getvar() or edited using ZLib in the CLI.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" is used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // including items/meat gained
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
return (m.fromname == "Your Pen Pal");
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2017-05-14T10:02:31Z

Zarqon: Added getvar() and updated settings description to reflect new behavior regarding defaults

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them). Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|varname}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p2desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it adds it and the default value specified in {{pspan|dfault}} to vars_defaults.txt. Also, if the setting has been changed from its default value, it normalizes the value according to the type of {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing defaults, not for editing existing settings. That is done by calling ZLib in the CLI or running a setting editor tool such as Prefref Plus.

{{HideLink|getvar}}{{Function|
name=getvar|
return_type=string|
parameter1={{Param|string|varname}}|
p1desc={{pspan|name}} is the setting to retrieve the value of|
}}
This function returns the value of the specified script setting. Authors are encouraged to use this rather than a direct vars[] lookup, since values which have not been changed from the default will eventually not be present in vars[].

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them.
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia properties (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, all ZLib setting default values are stored in vars_defaults.txt in your data directory. Your character's ZLib settings that have been changed from default are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will initialize the settings -- saving their default value and type in vars_defaults.txt -- when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Use setvar() to initialize a setting that your script will reference. To reference the setting, use getvar() and convert from string to whichever type the setting is supposed to be. Accessing vars[] or vardefaults[] directly is not recommended, as a value may exist in one but not the other, or both.
* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence in vardefaults[], which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* Settings are intended to be set only by users, not scripts. If you want a persistent variable that a script will use, consider static variables. However, there may be cases where a script needs to edit a setting (i.e. a relay script specifically for editing settings). To alter a setting, change the map entry directly with vars["propertyToChange"] = newValue, followed by updatevars() to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads the setting defaults from vars_defaults.txt and a map of your script settings that have been changed from vars_myname.txt. To access a script setting within an ASH script, use getvar(varname).

When a script calls setvar("threshold",4), ZLib checks to see if a setting called "threshold" already exists. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist, it initializes its default value to 4, its type to int, and saves those defaults back to vars_defaults.txt. The setting may now be accessed by getvar() or edited using ZLib in the CLI.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" is used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

[[Category:Scripting]][[Category:ASH Function Libraries]]

Limit mode

2016-10-04T15:26:56Z

Zarqon:

{{
#vardefine:name|limit_mode}}{{
#vardefine:return_type|string}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
}}|

function_description=Returns your current limit mode, for example "spelunky" or "batman". If you are not limited by a minigame, returns an empty string.|

code1={{CodeSample|
title=Code Sample|
description=The following example|
code=<syntaxhighlight>

</syntaxhighlight>
}}

}}

Zlib

2016-08-15T03:11:03Z

Zarqon: a bit more dissuasion for scripts editing settings

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them). Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* Settings are intended to be set only by users, not scripts. If you want a persistent variable that a script will use, consider static variables. However, there may be cases where a script needs to edit a setting (i.e. a relay script specifically for editing settings). To alter a setting, change the map entry directly with vars["propertyToChange"] = newValue, followed by updatevars() to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2016-08-15T03:06:33Z

Zarqon: redundant "more information" section removed

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them). Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* To change a setting after setvar() within ash use: vars["propertyToChange"] = newValue; followed by: updatevars(); to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2016-08-15T02:51:42Z

Zarqon: even here I forget parentheses

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them). Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* To change a setting after setvar() within ash use: vars["propertyToChange"] = newValue; followed by: updatevars(); to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2016-08-15T02:48:24Z

Zarqon: optional glue parameter added to normalized()

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
p3desc={{pspan|glue}} is only relevant for lists of a type. You can specify the delimiter (which could be necessary if dealing with list entries that have commas in them. Defaults to ", ".|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* To change a setting after setvar() within ash use: vars["propertyToChange"] = newValue; followed by: updatevars(); to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2016-08-15T02:44:27Z

Zarqon: formatting

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* To change a setting after setvar() within ash use: vars["propertyToChange"] = newValue; followed by: updatevars(); to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|qprop}}{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2016-08-15T02:43:30Z

Zarqon: added qprop()

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.
* To change a setting after setvar() within ash use: vars["propertyToChange"] = newValue; followed by: updatevars(); to update the map with the new setting. If you don't use updatevars(), the change will not stick.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{Function|
name=qprop|
return_type=boolean|
parameter1={{Param|string|test}}|
p1desc={{pspan|test}} is a basic logical expression using a quest property|
}}
Simplifies checking mafia's quest tracking properties ("prefref quest" in the CLI will reveal them). You should supply {{pspan|test}} like so:

<quest property> <logical operator> <possible property value>

For instance:
To check that a quest is complete: qprop("questLXXSomequest == finished")
To check that a quest has reached or passed "step2": qprop("questLXXSomequest >= step2")
To check that a quest is not complete: qprop("questLXXSomequest != finished")
To check that a quest hasn't reached step3 yet: qprop("questLXXSomequest < step3")

The function converts these text properties to numbers internally, so to save the function a completely insignificant amount of milliseconds (and more importantly yourself a little typing) you can also just use numbers directly instead of text values, where "step3" is 3, "unstarted" is -1, "started" is 0, and "finished" is 999. Thus, the last example above would also work as qprop("questLXXSomequest < 3").

One more bit of shorthand: you can supply only the property name by itself to check whether the quest is finished. The first example above would also work as qprop("questLXXSomequest").

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Batfactors

2016-06-13T04:45:52Z

Zarqon: /* The Format */

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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: 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).
|-
|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.
|-
|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.

Batfactors

2016-06-13T04:44:53Z

Zarqon: /* The Format */

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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, 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. 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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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: 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).
|-
|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.
|-
|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.

Batfactors

2016-02-01T10:10:24Z

Zarqon: A few updated monster keywords.

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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.
|-
|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. 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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!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: 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).
|-
|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.
|-
|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.

Goal exists

2015-10-25T15:42:44Z

Zarqon: "factoid" also works

{{
#vardefine:name|goal_exists}}{{
#vardefine:return_type|boolean}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|type}}|
p1desc=Valid values for {{pspan|type}} are:
* choiceadv
* autostop
* meat
* health
* factoid
* mana
* item|
}}|

function_description=This function returns true if there are any goals that match {{pspan|type}}.|
code1={{CodeSample|
title=CodeSample|
description=You could set your current mood in a preAdventureScript based on goal types.|
code=
<syntaxhighlight>
void set_mood() {
if( goal_exists( "item" ) )
cli_execute( "mood default, item" );
else if( goal_exists( "meat" ) )
cli_execute( "mood default, meat" );
}
</syntaxhighlight>}}|

see_also={{SeeAlso|adventure|add_item_condition|get_goals|is_goal}}|
}}

[[Category:Adventuring]]

Modifier eval

2015-06-05T16:01:02Z

Zarqon: updated from documentation in mafia source

{{
#vardefine:name|modifier_eval}}{{
#vardefine:return_type|float}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|expression}}|
p1desc={{pspan|expression}} is a mathematical expression to be solved.|
}}|

function_description= Evaluates an expression in the format used by variable modifiers. The following was copied from http://sourceforge.net/p/kolmafia/code/HEAD/tree/src/data/modifiers.txt :

* No spaces are allowed within the expression, except as part of a zone/location name.
* + - * / ( ) have their usual mathematical meaning and precedence.
* ^ is exponentiation, with the highest precedence.
* Functions available:
** ceil(x) floor(x) sqrt(x) min(x,y) max(x,y) abs(x)
* Location functions: loc(text) zone(text) env(text)
** These have a value of 1 if the current adventure location, zone, or environment contains the specified text, 0 elsewhere.
* Path function: path(text)
** This has a value of 1 if the player's path matches the text.
* Familiar function: fam(text)
** This has a value of 1 if the player's familiar type contains the text, else 0.
* Weapon function: mainhand(text)
** This has a value of 1 if the player's mainhand weapon class (sword, club, etc.) contains the text.
* Preferences function: pref(text)
** Returns the value of the specified preference
* function: pref(text,compare)
** Returns 1 if the specified preference is equal to "compare", otherwise 0
* Effect function: effect(text)
** This returns the number of turns remaining of the effect uniquely matching text.
* Resistance function: res(text)
** This returns the number of resistance levels for the listed element
* Class function: class(text)
** This has a value of 1 if the player's class matches the text.
* Skill function: skill(text)
** This has a value of 1 if the player has the skill matching the text.
* Upper-case letters are varying values:
** A - number of Ascensions
** B - Blood of Wereseal effect
** C - Clancy's level
** D - Drunkenness
** E - active (nonintrinsic) Effects
** F - Fullness
** G - Grimace darkness (0..5)
** H - Hobo Power
** I - Disco Momentum
** J - 1 on Festival of Jarlsberg, 0 otherwise
** K - Smithsness
** L - player Level
** M - total Moonlight (0..9)
** N - AudieNce
** P - Pasta Thrall level
** R - Reagent potion duration
** S - Spleenness
** T - Turns remaining of this effect
** U - telescope Upgrades
** W - familiar Weight
** X - gender (-1=male, 1=female)
** Y - furY

* This wrapper allows user-defined variables to be used as well, which must have names starting with a lower-case letter (or underscore) to distinguish them from built-in variables. Variables are supplied as a float[string] map.
 |

code1={{CodeSample|
title=Code Sample|
description=This script expands modifier_eval() to include support for user-defined variables. It is a bit complex, but it is extremely useful to anyone who wants to use modifier_eval().|
code=
<syntaxhighlight>
float eval(string expr, float[string] vars) {
buffer b;
matcher m = create_matcher( "\\b[a-z_][a-zA-Z0-9_]*\\b", expr );
while (m.find()) {
string var = m.group(0);
if (vars contains var) {
m.append_replacement(b, vars[var].to_string());
}
// could implement functions, pref access, etc. here
}
m.append_tail(b);
return modifier_eval(b.to_string());
}

# Everything below this line shows how to make use of eval().
# TESTING:

float[string] v;
v["pi"] = 3.14159265;
v["ten"] = 10;
print(eval("2+3", v));
print(eval("max(pi^ten,ten^pi)", v));
print(eval("sqrt(pi)*L", v));
print(eval("undefined/2", v));

</syntaxhighlight>}}|
}}

[[Category:Math and Numbers]]

Batfactors

2015-05-30T08:24:45Z

Zarqon: Reimplemented "prismatic"

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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.
|-
|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. 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.

{| class="wikitable"
|+Examples
|-
|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:

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|nopotato
|Potato-type familiars do not work vs. this monster.
|-
|nofamiliar
|Your familiar will not act vs. this monster.
|-
|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).
|-
|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.
|-
|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.

Batfactors

2015-05-30T08:22:48Z

Zarqon:

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|nopotato
|Potato-type familiars do not work vs. this monster.
|-
|nofamiliar
|Your familiar will not act vs. this monster.
|-
|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).
|-
|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.
|-
|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.

Batfactors

2015-05-30T08:22:11Z

Zarqon: Monsters are now indexed by ID!

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|nopotato
|Potato-type familiars do not work vs. this monster.
|-
|nofamiliar
|Your familiar will not act vs. this monster.
|-
|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).
|-
|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.
|-
|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.

Zlib

2015-05-07T16:59:24Z

Zarqon: is_goal(stat) no longer defaults to true for primestat

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2015-05-07T16:46:53Z

Zarqon: Split be_good() parameter into four types. Removed tower_items().

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|item|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|familiar|johnny}}|
}}
{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|skill|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path (hence the name), has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, or any of the newer paths that have similar restrictions, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. In an Avatar of Boris run, your normal permed skills are not active. And so forth.

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal. Additionally, the function treats your primestat as a permanent goal until you are level 13. So for both a level 9 Sauceror or a level 10 Seal Clubber who set "200 mysticality" as a goal, is_goal($stat[mysticality]) would return true.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Batfactors

2015-01-25T13:21:48Z

Zarqon: New keyword "itemcost"

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). (For now.) Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this 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:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|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).
|-
|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.
|-
|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.

Batfactors

2015-01-25T13:17:55Z

Zarqon:

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). (For now.) Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this 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:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|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).
|-
|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.
|-
|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.

BatBrain

2014-10-12T05:54:36Z

Zarqon: new monster attribute system

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready name -- attack/jiggle/skill s/use i
spread dmg; // raw dmg dealt to the monster, before resists/vulns
spread pdmg; // raw dmg taken by the player, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // whether or not this action ends the combat
string custom; // flag for special actions that should not be used in normal automation
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m // the monster currently being fought
float mvalcache // the value of the monster, including substats and meat/item drops
spread mres // the monster's resistances/vulnerabilities
spread mpen // the monster's penetrations
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
record[string] happenings // events that have already happened
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // macro commands to insert into every round
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|which}} can be one of: att, def, hp, drpen, howmany, damagecap, capexp, autohit, automiss, nostun, noskills, noitems, nostagger, delevelres, spellres, dodge, or itemres|
}}
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. This function is also used to return any of the special monster attributes listed above (these attributes are specified in [[batfactors]]).

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

BatBrain

2014-10-12T05:53:14Z

Zarqon: /* Other Useful Functions */

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready name -- attack/jiggle/skill s/use i
spread dmg; // raw dmg dealt to the monster, before resists/vulns
spread pdmg; // raw dmg taken by the player, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // whether or not this action ends the combat
string custom; // flag for special actions that should not be used in normal automation
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m // the monster currently being fought
boolean isseal // true if the monster is a seal
boolean nostun // true if the monster is immune to stuns and staggers
boolean nomultistun // true if the monster is only immune to multi-round stuns
boolean nomiss // true if the monster never misses (i.e. gremlins)
boolean nohit // true if the monster never hits (i.e. crates)
int howmanyfoes // the size of the group you are facing (usually 1)
float mvalcache // the value of the monster, including substats and meat/item drops
spread mres // the monster's resistances/vulnerabilities
int damagecap // the monster's damage cap
float capexp // for damage caps; the exponent by which to reduce the amount over the cap
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
record[string] happenings // events that have already happened
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // macro commands to insert into every round
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|which}} can be one of: att, def, hp, drpen, howmany, damagecap, capexp, autohit, automiss, nostun, noskills, noitems, nostagger, delevelres, spellres, dodge, or itemres|
}}
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. This function is also used to return any of the special monster attributes listed above (these attributes are specified in [[batfactors]]).

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

Batfactors

2014-10-12T05:49:27Z

Zarqon: /* The "monster" Category */

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). (For now.) Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this 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:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|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).
|-
|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.
|-
|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.

Batfactors

2014-10-12T05:45:53Z

Zarqon: /* The "monster" Category */

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|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).
|-
|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.
|-
|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.

Batfactors

2014-10-12T05:45:02Z

Zarqon: all new keywords

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|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).
|-
|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)
|This monster has an X percent chance to automatically hit you (e.g. gremlins).
|-
|automiss (X)
|This 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.
|-
|drpenetration X
|The monster ignores your first X DR. The Doctor is IN!
|}

Any keyword that expresses a "percent chance" 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.

Batfactors

2014-08-29T02:57:23Z

Zarqon: nostun -> nostagger

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|nohit
|This monster never hits.
|-
|nomiss
|This monster never misses (e.g. gremlins).
|-
|nostagger (X)
|The monster is immune to staggers. If a value is specified, it should be a float 0-1 representing the monster's chance of ignoring staggers.
|-
|nomultistun
|The monster is immune to multi-round stunners, such as Entangling Noodles.
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|noitems (X)
|You cannot use items in combat with this monster. If a value is specified, it should be a float representing the monster's chance of blocking item use.
|-
|noskills (X)
|As with noitems above, but for skills.
|-
|nospells
|As with noitems above, but if present, means that the monster is immune to spells.
|-
|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).
|-
|damagecap X
|Use this to specify the monster's soft damage cap boundary (integer).
|-
|retal X
|Use this to specify retaliation damage (damage dealt to you when you succeed with a melee attack) as a spread.
|-
|capexp X
|This is only meaningful with a soft damage cap, and specifies the exponent used to reduce damage above the boundary.
|}

Batfactors

2014-08-19T01:51:16Z

Zarqon: /* The "monster" Category */

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|nohit
|This monster never hits.
|-
|nomiss
|This monster never misses (e.g. gremlins).
|-
|nostun
|The monster is completely immune to stuns and staggers of any duration.
|-
|nomultistun
|The monster is immune to multi-round stunners, such as Entangling Noodles.
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|noitems (X)
|You cannot use items in combat with this monster. If a value is specified, it should be a float representing the monster's chance of blocking item use.
|-
|noskills (X)
|As with noitems above, but for skills.
|-
|nospells
|As with noitems above, but if present, means that the monster is immune to spells.
|-
|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).
|-
|damagecap X
|Use this to specify the monster's soft damage cap boundary (integer).
|-
|retal X
|Use this to specify retaliation damage (damage dealt to you when you succeed with a melee attack) as a spread.
|-
|capexp X
|This is only meaningful with a soft damage cap, and specifies the exponent used to reduce damage above the boundary.
|}

Zlib

2014-02-13T08:57:44Z

Zarqon: /* Adventuring Functions */

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check -- usually an item or familiar|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path, has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. And so forth.

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|tower_items}}{{Function|
name=tower_items|
aggregate=true|
return_type=boolean [string]|
}}
{{Function|
name=tower_items|
aggregate=true|
return_type=boolean [string]|
parameter1={{Param|boolean|combat_safe}}|
p1desc={{pspan|combat_safe}} is optional. Supply it as true if you are in combat.|
}}
This handy function returns a map of the items you definitely need (value: true) or might need (value: false) to pass the entryway and climb the tower. You can check (tower_items() contains X) to determine whether an item has a nonzero chance of being required for the tower, or check tower_items(X) to determine whether an item has a 100% chance of being needed (i.e. it was indicated necessary by your telescope). If you haven't yet checked your telescope yet this run, it will also do that to populate the relevant mafia properties, unless you have supplied the optional {{pspan|combat_safe}} parameter as true (you can't access your telescope during combat).

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|patient}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal. Additionally, the function treats your primestat as a permanent goal until you are level 13. So for both a level 9 Sauceror or a level 10 Seal Clubber who set "200 mysticality" as a goal, is_goal($stat[mysticality]) would return true.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Zlib

2014-02-13T08:57:12Z

Zarqon: added braindrop()

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check -- usually an item or familiar|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path, has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. And so forth.

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|tower_items}}{{Function|
name=tower_items|
aggregate=true|
return_type=boolean [string]|
}}
{{Function|
name=tower_items|
aggregate=true|
return_type=boolean [string]|
parameter1={{Param|boolean|combat_safe}}|
p1desc={{pspan|combat_safe}} is optional. Supply it as true if you are in combat.|
}}
This handy function returns a map of the items you definitely need (value: true) or might need (value: false) to pass the entryway and climb the tower. You can check (tower_items() contains X) to determine whether an item has a nonzero chance of being required for the tower, or check tower_items(X) to determine whether an item has a 100% chance of being needed (i.e. it was indicated necessary by your telescope). If you haven't yet checked your telescope yet this run, it will also do that to populate the relevant mafia properties, unless you have supplied the optional {{pspan|combat_safe}} parameter as true (you can't access your telescope during combat).

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|braindrop}}{{Function|
name=braindrop|
return_type=item|
parameter1={{Param|monster|patient}}|
p1desc={{pspan|patient}} is the monster under inquiry|
}}
Returns the brain dropped by {{pspan|combat_safe}} in Zombiecore. All five types of brains are properly accounted for, as well as monsters that drop no brains. Will always return $item[none] outside of Zombiecore.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal. Additionally, the function treats your primestat as a permanent goal until you are level 13. So for both a level 9 Sauceror or a level 10 Seal Clubber who set "200 mysticality" as a goal, is_goal($stat[mysticality]) would return true.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|place}} is the location to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

BatBrain

2014-01-28T07:52:32Z

Zarqon: /* Useful Global Variables */

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready name -- attack/jiggle/skill s/use i
spread dmg; // raw dmg dealt to the monster, before resists/vulns
spread pdmg; // raw dmg taken by the player, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // whether or not this action ends the combat
string custom; // flag for special actions that should not be used in normal automation
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m // the monster currently being fought
boolean isseal // true if the monster is a seal
boolean nostun // true if the monster is immune to stuns and staggers
boolean nomultistun // true if the monster is only immune to multi-round stuns
boolean nomiss // true if the monster never misses (i.e. gremlins)
boolean nohit // true if the monster never hits (i.e. crates)
int howmanyfoes // the size of the group you are facing (usually 1)
float mvalcache // the value of the monster, including substats and meat/item drops
spread mres // the monster's resistances/vulnerabilities
int damagecap // the monster's damage cap
float capexp // for damage caps; the exponent by which to reduce the amount over the cap
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
record[string] happenings // events that have already happened
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options currently available to you
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // macro commands to insert into every round
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

BatBrain

2014-01-28T07:51:35Z

Zarqon: /* Useful Global Variables */ basic explanations

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready name -- attack/jiggle/skill s/use i
spread dmg; // raw dmg dealt to the monster, before resists/vulns
spread pdmg; // raw dmg taken by the player, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // whether or not this action ends the combat
string custom; // flag for special actions that should not be used in normal automation
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act(). Most of these values are set in BatBrain's set_monster() function.

MONSTER

<syntaxhighlight>
monster m // the monster currently being fought
boolean isseal // true if the monster is a seal
boolean nostun // true if the monster is immune to stuns and staggers
boolean nomultistun // true if the monster is only immune to multi-round stuns
boolean nomiss // true if the monster never misses (i.e. gremlins)
boolean nohit // true if the monster never hits (i.e. crates)
int howmanyfoes // the size of the group you are facing (usually 1)
float mvalcache // the value of the monster, including substats and meat/item drops
spread mres // the monster's resistances/vulnerabilities
int damagecap // the monster's damage cap
float capexp // for damage caps; the exponent by which to reduce the amount over the cap
</syntaxhighlight>

ENVIRONMENT

<syntaxhighlight>
spread pres // your resistances/vulnerabilities
string page // the text of the most recent fight.php page load
int round // the current/simulated round
int maxround // the maximum rounds the combat can extend
float beatenup // the cost of getting beaten up
float meatperhp // the value of 1 HP
float meatpermp // the value of 1 MP
</syntaxhighlight>

TRACKING

<syntaxhighlight>
int[item] stolen // all items you have acquired during this combat
advevent adj // all adjustments to the current combat (used when queueing)
record[string] happenings // events that have already happened
</syntaxhighlight>

YOUR COMBAT OPTIONS

<syntaxhighlight>
advevent[int] opts // all known combat options
advevent[int] custom // custom actions which SS has determined apply to this combat
advevent[int] queue // queued actions (affects round number and uses adj to track adjustments)
int[string] blacklist // blacklisted actions to be ignored
string batround_insert // macro commands to insert into every round
</syntaxhighlight>

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

BatBrain

2013-12-10T05:09:44Z

Zarqon: add global variables; need to format into table later

{{TOCright}}{{DISPLAYTITLE:BatBrain (BatBrain.ash)}}
== About BatBrain ==
BatBrain is a function library intended to greatly simplify writing a [[Custom_Combat_Script#Consult_Scripts|consult script]]. A general introduction, changelog, download, and forum discussion can be found in the [http://kolmafia.us/showthread.php?6445 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.

== What It Does ==

yadda yadda

== Spreads ==

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

<syntaxhighlight>
typedef float[element] spread;
</syntaxhighlight>

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 frequently if you peruse BatBrain and if you're writing a combat script, you may have to deal with one. Fortunately, there are some functions for dealing with spreads:

{{HideLink|to_spread}}{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
}}
{{Function|
name=to_spread|
return_type=spread|
parameter1={{Param|string|dmg}}|
parameter2={{Param|float|factor}}|
p1desc={{pspan|dmg}} is the damage string, in the same format used by batfactors.|
p2desc={{pspan|factor}} is optional; supply this if you want to factor the supplied damage by an amount other than 1.0|
}}
This function creates a spread from a string. For example, an attack which deals 10 hot damage would deal to_spread("10 hot") damage. The format for {{pspan|dmg}} is flexible and described in greater detail on the [[batfactors]] page. An optional {{pspan|factor}} parameter is available as shorthand for factor(to_spread()).

{{HideLink|merge}}{{Function|
name=merge|
return_type=spread|
parameter1={{Param|spread|first}}|
parameter2={{Param|spread|second}}|
p1desc={{pspan|first}} is the first spread to merge|
p2desc={{pspan|second}} is the second spread|
}}
Basic arithmetic, a + b. It returns a spread combining the damage in first and second.

{{HideLink|factor}}{{Function|
name=factor|
return_type=spread|
parameter1={{Param|spread|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the spread to factor|
p2desc={{pspan|fact}} is the factor|
}}
More basic arithmetic, this time multiplication. This function returns spread f factored by fact.

{{HideLink|to_html}}{{Function|
name=to_html|
return_type=string|
parameter1={{Param|spread|src}}|
p1desc={{pspan|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.

{{HideLink|dmg_dealt}}{{Function|
name=dmg_dealt|
return_type=float|
parameter1={{Param|spread|action}}|
p1desc={{pspan|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 {{pspan|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.

{{HideLink|dmg_taken}}{{Function|
name=dmg_taken|
return_type=float|
parameter1={{Param|spread|pain}}|
p1desc={{pspan|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.

== Advevents ==

Now that we've discussed spreads, we can really get down to it. Absolutely everything that happens, every single "adventure event" that takes place, is treated as an advevent. Your familiar performs an advevent every round, the monster performs an advevent, each action you have available is an advevent, and sometimes even your current gear or running effects contribute an advevent or two. Your current combat environment could be described with an advevent, and in fact any adjustments made to your current environment when enqueueing actions are tracked in an advevent. Get the picture? Advevents make BatBrain's world turn. And here's what they look like:

<syntaxhighlight>
record advevent { // record of changes due to an event
string id; // macro-ready name -- attack/jiggle/skill s/use i
spread dmg; // raw dmg dealt to the monster, before resists/vulns
spread pdmg; // raw dmg taken by the player, before resists/vulns
float att; // monster attack adjustment
float def; // monster defense adjustment
float stun; // stun chance (expressed as average rounds stunned)
float mp; // mp gained/lost
float meat; // meat gained/lost
float profit; // profit cache to avoid recalculating
int rounds; // rounds consumed
substats stats; // substats gained/lost
boolean endscombat; // whether or not this action ends the combat
string custom; // flag for special actions that should not be used in normal automation
string note; // user-friendly name or special note
};
</syntaxhighlight>

Note that each advevent contains two spreads, one for damage to the monster and one for damage to the player. The rest is mostly self-explanatory, but a few things require clarification.

First, the profit field will contain nothing (0) until to_profit() is called on the advevent in question, at which point the result is cached in this field for further reference, since to_profit() has a fair amount of calculations and is thus much more expensive (in processing terms) than simply checking a.profit. Keep that in mind if you're calling to_profit() a lot; chances are you could speed up your script by changing a few of those to check the profit cache instead.

Second, substats is another datatype defined by BatBrain, and it's simply a float[stat] map.

The custom field will be empty for most actions, so scripts ought to be checking a.custom == "" before using an action in regular automation. For special actions, the custom field will contain the type of custom action (and sometimes additional information). Some custom types currently being used are: attract, banish, copy, yellow, and runaway.

Finally, the note field is not really used by BatBrain, but is used by BatMan RE to display extra information about certain actions (such as notices of estimates due to unspaded numbers, or ongoing damage not predicted by BatBrain, etc).

Here are some functions to help you deal with advevents should the need arise:

{{HideLink|to_event}}{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
parameter5={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|spread|dmg}}|
parameter3={{Param|spread|pdmg}}|
parameter4={{Param|string|special}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
parameter3={{Param|int|howmanyrounds}}|
}}
{{Function|
name=to_event|
return_type=advevent|
parameter1={{Param|string|id}}|
parameter2={{Param|string|special}}|
p1desc={{pspan|id}} is the ID of the event. BALLS-friendly name (will be used in macros)|
p2desc={{pspan|dmg}} is for damage/healing to the monster.|
p3desc={{pspan|pdmg}} is for damage/healing to the player.|
p4desc={{pspan|special}} is for specifying other qualities of the action, such as deleveling, stunning, meat gained/lost, etc.|
p5desc={{pspan|howmanyrounds}} is optional, default 0. It specifies the number of rounds this action takes. Will be 0 for all but actual player actions.|
}}
Builds and returns an advevent, used ubiquitously by BatBrain internally but also useful to a scripter for creating custom actions that are not present in opts[]. You may omit both spreads if the event being constructed deals no damage to either monster or player. The format for the special field is generally a comma-delimited list of "keyword value", although some keywords lack values. The format is described in greater detail on the [[batfactors]] page -- quite a few keywords are available. Note that if you have an elemental form, all damage specified in {{pspan|dmg}} will be converted to that element by this function.

{{HideLink|merge}}{{Function|
name=merge|
return_type=advevent|
parameter1={{Param|advevent|first}}|
parameter2={{Param|advevent|second}}|
p1desc={{pspan|first}} is the first advevent to merge|
p2desc={{pspan|second}} is the second advevent|
}}
As with the spread version, this function combines two advevents into a single advevent by individually combining each field. It isn't always just simple addition, however. First of all, the id field will be merged using a semicolon and a space, so if you were merging "jiggle" with "attack", the new combined id would be "jiggle; attack". This allows merging events to retain a BALLS-friendly ID. Second, if both first and second are single item actions and you have Funkslinging, the events will be merged into a single funkslinging action "use X,Y". The rounds field likewise will be added together unless it's being auto-funked, in which case 1 + 1 = 1. Last, the stun field is not simply added together, because if you perform two actions, each with a 50% stun chance, that does not guarantee a 100% stun chance; that's a 75% stun chance, because you have a 50% chance of stunning 50% of the time when the first action fails to stun. Merging takes this into account.

{{HideLink|factor}}{{Function|
name=factor|
return_type=advevent|
parameter1={{Param|advevent|f}}|
parameter2={{Param|float|fact}}|
p1desc={{pspan|f}} is the advevent to factor|
p2desc={{pspan|fact}} is the factor|
}}
This function multiplies an advevent by {{pspan|fact}}, and is much more straightforward than merge(). All numeric fields are simply multiplied, with one exception: the rounds field is not multiplied since that would be undesirable. BatBrain uses this function internally to apply the hitchance of an event to the event.

{{HideLink|to_profit}}{{Function|
name=to_profit|
return_type=float|
parameter1={{Param|advevent|haps}}|
parameter2={{Param|boolean|nodelevel}}|
p1desc={{pspan|haps}} is the advevent to evaluate|
p2desc={{pspan|nodelevel}} is optional, default false. If supplied as true, will ignore profit from deleveling.|
}}
Returns the profit of performing the action {{pspan|haps}} at the current point in the combat. It looks ahead one round (including the monster's event, your familiar's event, and any equipment and effects) and determines what you gained and lost, and converts all of that to a single number, which it returns. This is a very useful function for combining with other criteria and sorting opts[]. HP and MP gain/loss are evaluated based on your _meatpermp and _meatperhp properties, which are set by Bale's Universal Recovery Script. If you are not using this script, basic calculations are made using the price of common restoratives. HP/MP regeneration is also factored into the profit appropriately. By default, this function includes profit from deleveling (i.e. reducing the monster's attack by X means it will deal Y less damage, effectively earning you Y HP). However, this may be undesirable if you intend to stun beforehand, so an optional {{pspan|nodelevel}} flag was included.

== Useful Global Variables ==

BatBrain has a not-small number of global variables which may simplify writing your script. Most of these variables are automatically populated as soon as your script runs act().

MONSTER

monster m
boolean isseal
boolean nostun
boolean nomultistun
boolean nomiss
boolean nohit
int howmanyfoes
float mvalcache
spread mres
int damagecap
float capexp

ENVIRONMENT

spread pres
string page
int round
int maxround
float beatenup
float meatperhp
float meatpermp

TRACKING

int[item] stolen
advevent adj
record[string] happenings

YOUR COMBAT OPTIONS

advevent[int] opts
advevent[int] custom
advevent[int] queue
int[string] blacklist
string batround_insert

== Other Useful Functions ==

{{HideLink|monster_stat}}{{Function|
name=monster_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|my_stat}}{{Function|
name=my_stat|
return_type=float|
parameter1={{Param|string|which}}|
p1desc={{pspan|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.

{{HideLink|happened}}{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|string|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|skill|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|item|occurrence}}|
}}
{{Function|
name=happened|
return_type=boolean|
parameter1={{Param|advevent|occurrence}}|
p1desc={{pspan|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: crit, shieldcrit, smusted, stolen, icecapstun, hipster_stats, sealwail, and lackstool.

Batfactors

2013-11-14T16:33:25Z

Zarqon: 'retal' keyword

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|nohit
|This monster never hits.
|-
|nomiss
|This monster never misses (e.g. gremlins).
|-
|nostun
|The monster is completely immune to stuns and staggers of any duration.
|-
|nomultistun
|The monster is immune to multi-round stunners, such as Entangling Noodles.
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|noitems (X)
|You cannot use items in combat with this monster. If a value is specified, it should be a float representing the monster's chance of blocking item use.
|-
|noskills (X)
|As with noitems above, but for skills.
|-
|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).
|-
|damagecap X
|Use this to specify the monster's soft damage cap boundary (integer).
|-
|retal X
|Use this to specify retaliation damage (damage dealt to you when you succeed with a melee attack) as a spread.
|-
|capexp X
|This is only meaningful with a soft damage cap, and specifies the exponent used to reduce damage above the boundary.
|}

Zlib

2013-10-27T06:21:01Z

Zarqon: add list_contains()

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About ZLib ==
ZLib is a function library intended to make life easier for both script authors and script users. A more detailed introduction, as well as instructions on installing it and other details, can be found in the [http://kolmafia.us/showthread.php?2072 ZLib thread].

== String Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|equals}}{{Function|
name=equals|
return_type=boolean|
parameter1={{Param|string|s1}}|
parameter2={{Param|string|s2}}|
p1desc={{pspan|s1}} is a string.|
p2desc={{pspan|s2}} is the string to compare with {{pspan|s1}}.|
}}
Since string comparisons in ASH using == and != are case-insensitive, this function allows you to strictly compare two strings, including case sensitivity.

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} controls the return value and specifies the verbosity level of the message|
}}
This function is an enhanced version of the ASH function {{f|print}}. The {{pspan|message}} and optional {{pspan|color}} parameters are exactly like in print(), but the {{pspan|level}} parameter gives you a lot of additional control. Specifically, it allows you to control the return value, specify the verbosity level of the output, and maybe even abort the script.

First, the return value. If level is positive, it returns true. If negative, it returns false. If level is 0, vprint() will abort with the specified message. You can see now that vprint effectively replaces both {{f|abort}} and print. I recommend it as your go-to function anytime you need to show anything in the CLI, for any reason.

Having a boolean return value (as opposed to ASH's print returning void) allows you to include helpful information in your script easily, without needing to significantly edit your code. For example:
{{CodeSample|
code=
<syntaxhighlight>
// add debugging info to an if check:
if (somevar == 2 && vprint("somevar equals 2",10)) dosomething();
// add additional info to a return true/false:
if (everythingsgreat) return vprint("Everything's great!",7);
else return vprint("Everything is not great.",-7);
</syntaxhighlight>}}

Secondly, level represents the verbosity of the message. ZLib includes a script setting called "verbosity". Users can adjust this value to specify how verbose they want scripts to be. If they set it to 1, they want the script to print almost nothing -- only the most important messages. If they set it to 10, they want it to print a lot of details. The level of each vprint command thus determines whether or not the message will actually be printed. If the absolute value of level is more than verbosity, the message will not be printed. For example, a user with the default verbosity of 3 would not see any of the example messages given above. This allows users to control the chattiness of scripts, and allows authors to include helpful debugging print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

The color parameter is optional. If you omit it, the default color is black for positive values of level, and red for negative values. Usually, you won't be calling vprint() with the color parameter, unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to, which can be any primitive type or any typed constant. You can also specify "list of <type>", for a comma-delimited list of the given type.|
}}
Returns {{pspan|mixvar}}, normalized to the specified KoLmafia {{pspan|type}}. For example, normalized("badger", "familiar") would return "Astral Badger". It can also normalize comma-delimited lists of any of these types if you specify "list of <type>" for {{pspan|type}}. For example, normalized("bloop, dair go, possess", "list of monster") would return "Blooper, Dairy Goat, Possessed Silverware Drawer".

{{HideLink|join}}{{Function|
name=join|
return_type=string|
parameter1={{Param|string [int]|pieces|ag=t}}|
parameter2={{Param|string|glue}}|
p1desc={{pspan|pieces}} is a map of strings which you want to join into a single string.|
p2desc={{pspan|glue}} is the string to put between the pieces.|
}}
This function is the opposite of the ASH function {{f|split_string}}. It joins {{pspan|pieces}} together, inserting {{pspan|glue}} between each piece, and returns the assembly as a single string. Useful for working with comma-delimited lists (or anything-delimited lists, actually).

{{HideLink|list_contains}}{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
}}
{{Function|
name=list_contains|
return_type=boolean|
parameter1={{Param|string|list}}|
parameter2={{Param|string|needle}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join().|
p2desc={{pspan|needle}} is the entry to check for.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Returns true if {{pspan|list}} contains {{pspan|needle}}. Avoids false positives which could result from using contains_text().

{{HideLink|list_add}}{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
}}
{{Function|
name=list_add|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|add}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|add}} is the entry to add to the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Adds unique entry {{pspan|add}} to a {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. If the entry already exists in the list, another entry will not be added. For example, list_add("a, b, c","d") would return "a, b, c, d", but list_add("a, b, c", "a") would return "a, b, c", since the entry "a" already exists.

{{HideLink|list_remove}}{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
}}
{{Function|
name=list_remove|
return_type=string|
parameter1={{Param|string|list}}|
parameter2={{Param|string|del}}|
parameter3={{Param|string|glue}}|
p1desc={{pspan|list}} is a glue-delimited string list such as returned by join() above.|
p2desc={{pspan|del}} is the entry to remove from the list.|
p3desc={{pspan|glue}} is optional (defaults to ", ") and represents the delimiter for the list.|
}}
Removes {{pspan|del}} from {{pspan|glue}}-delimited {{pspan|list}}, and returns the modified list. It will remove all instances of {{pspan|del}}. For example, list_remove("a, b, c","a") would return "b, c", and list_remove("a, a, b, b, c, c", "a") would return "b, b, c, c".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string, appropriate to the user's computer's region. For ints, this means it adds grouping separators where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string(int).

== Number Functions ==

{{HideLink|abs}}{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is any number.|
}}
Returns the absolute value of the number {{pspan|n}}. Don't worry if you are working with integers, it will still work just fine. This function already exists in many programming languages; ZLib makes it handily available in ASH.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}. Another function common to many languages.

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this function three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=float|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. Brief documentation is also included in ZLib. (NB: This section needs more infoz.)

== Script Functions ==

{{HideLink|check_version}}{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|proj}}|
parameter3={{Param|int|thread}}|
p1desc={{pspan|soft}} is the script name, which must match the page source of the {{pspan|thread}} being parsed|
p2desc={{pspan|proj}} is the name of the SVN project name to check.|
p3desc={{pspan|thread}} is the script's thread number on kolmafia.us|
}}
{{Function|
name=check_version|
return_type=string|
parameter1={{Param|string|soft}}|
parameter2={{Param|string|prop}}|
parameter3={{Param|string|this_version}}|
parameter4={{Param|int|thread}}|
p1desc={{pspan|soft}} is as above.|
p2desc={{pspan|prop}} is used as part of the name of the property saved to user preferences.|
p3desc={{pspan|this_version}} is the version of the script currently running|
p4desc={{pspan|thread}} is as above.|
}}
Server-friendly once-daily version-checking. There are two versions of this function, one for SVN and one for forum threads. The three-parameter SVN version uses mafia's SVN client to check if a previously checked-out SVN project is current and if not, it updates it automatically, meaning the script will be current the next time it runs. In the event that a user has checked the option for mafia to automatically update all projects on login, it detects that the script has updated and prints an informative message with a link to the script's kolmafia.us thread -- and if the project is hosted on SourceForge, an additional link to the changelog there.

For the four-parameter forum thread version, it visits the specified {{pspan|thread}} on the kolmafia.us forums to find the current version of your script. The thread must include <nowiki>"<b></nowiki>{{pspan|soft}} {{pspan|version}}<nowiki></b>"</nowiki> for the version info to be successfully parsed. Optionally, you may include <nowiki>"[requires revision XXXX]"</nowiki> somewhere in your post if you want to indicate a required minimum revision of mafia. If a new version is available, it alerts the user in large text and provides an update link.

The return value of both versions is a blank string unless an update is/was found, in which case it is a <nowiki><div class='versioninfo'></nowiki> containing the update message. This allows this function to work equally well for relay scripts. The current version/revision (and the last date checked) is stored in a data file "zversions.txt". Example:
{{CodeSample|
code=
<syntaxhighlight>
check_version("Hardcore Checklist","checklist","1.2.7",1045);
</syntaxhighlight>}}

{{HideLink|load_current_map}}{{Function|
name=load_current_map|
return_type=boolean|
parameter1={{Param|string|map_name}}|
parameter2={{Param|aggregate|destination}}|
p1desc={{pspan|map_name}} is the name of the map, without the file extension|
p2desc={{pspan|destination}} is a previously-declared map to load with data|
}}
Acts as a wrapper for the built-in {{f|file_to_map}} with automatic update capability. The first time the function is called for a given map each day, it will check [http://zachbardon.com/mafiatools/autoupdate.php Zarqon's Map Manager] to see if an update for the given {{pspan|map_name}} is available, and if so will load from there. Otherwise, it merely loads it from disk. (Note: you should not include a file extension, such as ".txt" in the {{pspan|map_name}} parameter.)

{{HideLink|setvar}}{{Function|
name=setvar|
return_type=void|
parameter1={{Param|string|name}}|
parameter2={{Param|mixed|dfault}}|
p1desc={{pspan|name}} is the name of the setting|
p1desc={{pspan|dfault}} can be any primitive or ASH type (e.g. item, effect, coinmaster, etc.), but not an array, map, or record.|
}}
This function ensures that a ZLib script setting called {{pspan|name}} exists. If not, it creates it and sets it to {{pspan|dfault}}. If the setting already exists, it normalizes it to the same type as {{pspan|dfault}}, but otherwise does nothing. Note that this function is for initializing settings, not for editing existing settings. That is done by calling ZLib in the CLI.

==== For Users ====

* Script settings are now all saved in one place, separate from mafia properties. I've read more than one post wishing that script-defined settings and mafia properties would be separate. This provides a solution.
* Script settings are independent from scripts. This means that you will no longer need to edit scripts to adjust your settings. Further, when you download a script update, the script will still use your saved settings and you won't need to reset them!
* To see all of your current settings, type "zlib vars" in the CLI. You can also type "zlib <whatever>" to see a list of current settings and values containing <whatever>. To change a setting, type "zlib settingname = value". If you're adjusting threshold, you can use "up" or "down" as the value to adjust your threshold relatively. This is almost exactly as convenient as mafia settings (possibly more so since you don't need to open a text file to find setting names!).
* If for some reason you prefer to open a text file, ZLib settings are stored in a file called vars_myname.txt in your data directory.
* Scripts that use Zlib script settings will only create these settings when you run them for the first time. Attempting to edit a nonexisting setting won't work, so you'll need to run a script once (then, usually, mash the ESC key before it actually does anything) before you can configure it. Script documentation should tell you which settings to change to get your desired behavior.

==== For Script Authors ====

* Script settings may now be used across scripts, in exactly the same way that mafia properties are. Basically, this works almost exactly like mafia properties, except that new settings can only be created by setvar() or manually editing the file ("zlib nonexistentsetting = value" will fail).
* Settings are only stored if you run a script that defines/uses them. So your settings file will not contain any extraneous unused settings.
* Script authors can now test for a setting's existence, which means you can check to see if a user has used a given script. It's almost as good as a script_exists() function. This can allow scripts to work together with other scripts, if they exist!
* Scripts with overlapping or related functionality can be designed to access a single shared setting, in much the same way that my scripts have until now all shared a "threshold" mafia setting. Changing a single setting can now change the behavior of every script that accesses that setting.

==== Functional Details ====

When importing ZLib, it loads a map of your script settings from vars_myname.txt. It is a basic string[string] map called vars. To access a script setting within an ASH script, use vars[varname]. To check if a setting exists you can simply use if (vars contains varname).

When a script calls setvar("threshold",4), ZLib checks to see if a variable called "threshold" already exists in vars. If so, since dfault is an integer, it ensures that the value is an integer using normalize() (saving changes if necessary), but unless normalization changed the value, nothing else happens. If "threshold" does not exist in vars, it creates it, sets it to 4, and saves the updated map back to vars_myname.txt.

==== Choosing Setting Names ====

The file of script settings will contain all script settings, sorted alphabetically. Also, there is no way to detect if a setting is unused, so if you decide to change the name, the old setting will never be deleted. '''Please think carefully about your setting names.''' If you have a setting named "setting1", a user will probably not have a clue which script that is for or what it does. True, this can be overcome with documentation, but it is far better to have settings that make sense just by looking at them.

'''Recommendations:'''

1. Use a name that clearly identifies what the setting is/does.

2. Prefix your setting names with a script identifier. For example, here are some of my One-Click Wossname script settings:

{{CodeSample|
code=
<syntaxhighlight>
setvar("ocw_warplan","optimal");
setvar("ocw_change_to_meat",true);
setvar("ocw_nunspeed",false);
setvar("defaultoutfit","current");
setvar("ocw_f_default","zombie");
setvar("ocw_m_default","");
</syntaxhighlight>}}
Those settings which are specific to OCW are prefixed with "ocw_" so as to be found together in the settings file. However, some of the settings are usable across scripts, and are not so prefixed. For example, the "defaultoutfit" will be used by nearly all of my adventuring scripts that swap outfits, so no prefix is given.

== Adventuring Functions ==

{{HideLink|be_good}}{{Function|
name=be_good|
return_type=boolean|
parameter1={{Param|string|johnny}}|
p1desc={{pspan|johnny}} is the thing you want to check -- usually an item or familiar|
}}
This function, originally created to check whether items were allowed in the Bees Hate You path, has been expanded to an all-purpose check to see whether something is acceptable in your current path. For example, in a Trendy path, outdated items would not be_good. Likewise, during Bees Hate You, a familiar containing a 'b' would not be_good. In Fistcore, anything you hold in your hands is not allowed. And so forth.

{{HideLink|mall_val}}{{Function|
name=mall_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is optional, default 0. It represents the age at which {{f|historical_price}} is no longer valid, after which {{f|mall_price}} is used.|
p3desc={{pspan|combatsafe}} is optional, default false. If true, the function will avoid calling mall_price and use only historical_price, regardless of age.|
}}
The ASH functions {{f|mall_price}}, {{f|historical_price}}, and {{f|historical_age}} are often combined to save server hits when checking for the price of multiple items. Scripts will use the historical price if it is fairly recent, or hit the server with mall_price if it is too old. This function wraps all of that up, and even adds a flag for getting item values during combat (when you don't have mall access). You'll generally call this with only one of the two parameters.

If you want to only use historical_price: mall_val(someitem, true)
If you want to only use mall price: mall_val(someitem,0)
If you want to use historical prices no more than 2 days old, otherwise use mall price: mall_val(someitem,3)

{{HideLink|sell_val}}{{Function|
name=sell_val|
return_type=int|
parameter1={{Param|item|it}}|
parameter2={{Param|float|expirydays}}|
parameter3={{Param|boolean|combatsafe}}|
p1desc={{pspan|it}} is the item being valued.|
p2desc={{pspan|expirydays}} is the same as in mall_val() above.|
p3desc={{pspan|combatsafe}} is also as in mall_val() above.|
}}
This function is concerned with the meat you could realistically expect to get from selling the item. It returns mall_val, unless the mall value is at minimum, meaning it's junk which probably won't sell. In that case it returns the item's autosell value.

{{HideLink|tower_items}}{{Function|
name=tower_items|
aggregate=true|
return_type=boolean [string]|
}}
{{Function|
name=tower_items|
aggregate=true|
return_type=boolean [string]|
parameter1={{Param|boolean|combat_safe}}|
p1desc={{pspan|combat_safe}} is optional. Supply it as true if you are in combat.|
}}
This handy function returns a map of the items you definitely need (value: true) or might need (value: false) to pass the entryway and climb the tower. You can check (tower_items() contains X) to determine whether an item has a nonzero chance of being required for the tower, or check tower_items(X) to determine whether an item has a 100% chance of being needed (i.e. it was indicated necessary by your telescope). If you haven't yet checked your telescope yet this run, it will also do that to populate the relevant mafia properties, unless you have supplied the optional {{pspan|combat_safe}} parameter as true (you can't access your telescope during combat).

{{HideLink|have_item}}{{Function|
name=have_item|
return_type=int|
parameter1={{Param|string|to_lookup}}|
p1desc={{pspan|to_lookup}} is the item to count|
}}
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped. Similar but not equivalent to the ASH function {{f|available_amount}}, since this function completely ignores your closet and storage.

{{HideLink|is_goal}}{{Function|
name=is_goal|
return_type=boolean|
parameter1={{Param|stat|whichstat}}|
p1desc={{pspan|whichstat}} is the stat to check|
}}
The ASH function {{f|is_goal}} takes an item parameter and returns true if the given item is a goal. ZLib extends that function by also including a version which accepts a stat as a parameter. Stats can be goals when a user or script sets "level X" or "X muscle" as a goal. Additionally, the function treats your primestat as a permanent goal until you are level 13. So for both a level 9 Sauceror or a level 10 Seal Clubber who set "200 mysticality" as a goal, is_goal($stat[mysticality]) would return true.

{{HideLink|isxpartof}}{{Function|
name=isxpartof|
return_type=float|
parameter1={{Param|item|child}}|
parameter2={{Param|item|ancestor}}|
p1desc={{pspan|child}} is the ingredient/component you want to check.|
p2desc={{pspan|ancestor}} is the concoction you want to check.|
}}
In the sentence "child is X part of ancestor", this function returns X. It assumes the minimum amount of other ingredients necessary. For example, isxpartof($item[white pixel], $item[digital key]) returns 0.033333335 (1/30), since 30 white pixels are needed to make a digital key. However, isxpartof($item[red pixel], $item[digital key]) returns 0.03125 (1/32), assuming 1 each of green and blue pixels and 29 other white pixels (rather than 30 each RGB pixels -- 1/90). This function is used by has_goal(item) but may have uses in your own script.

{{HideLink|has_goal}}{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|item|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=has_goal|
return_type=float|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the item, monster or locationto check|
}}
At the base of this function is the item parameter version, which returns the chance that the item {{pspan|check_me}} is or results in a goal. If the item is itself a goal, returns 1.0. Otherwise, returns what percentage of a goal the item is, which could be nonzero in two cases: 1) you could get a goal by using the item (returns the chance of success), or 2) the item is an ingredient of a goal. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58.

When supplied a monster as the parameter for {{pspan|check_me}}, returns the percent chance that encountering the given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

When supplied a location as the parameter for {{pspan|check_me}}, returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

These functions also have an optional boolean parameter, usespec. If supplied as true, these functions will use speculative values. (See "whatif")

{{HideLink|obtain}}{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
}}
{{Function|
name=obtain|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|string|condition}}|
parameter3={{Param|location|place}}|
parameter4={{Param|string|filter}}|
p1desc={{pspan|qty}} is the quantity of the item or choice adventure desired|
p2desc={{pspan|condition}} is the item or choice adventure to use as a goal|
p3desc={{pspan|location}} is the place to adventure to obtain your goal|
p4desc={{pspan|filter}} is an optional combat filter used the same as in {{f|adventure}}|
}}
Attempts to get {{pspan|qty}} (minus existing) of {{pspan|condition}}, either by purchasing (if you have the KoLmafia preference set), pulling from Hangk's, or adventuring at the specified {{pspan|place}}. It also works with choice adventures.

{{HideLink|use_upto}}{{Function|
name=use_upto|
return_type=boolean|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|thing}}|
parameter3={{Param|boolean|purchase}}|
p1desc={{pspan|qty}} is the quantity to use|
p2desc={{pspan|thing}} is the item to use|
p3desc={{pspan|purchase}} is true if KoLmafia should purchase extras if you don't already have {{pspan|qty}}|
}}
Gets (if purchase is true) and uses {{pspan|qty}} of the item(s) {{pspan|thing}} if possible. Otherwise, uses as many as you have up to {{pspan|qty}}.

{{HideLink|resist}}{{Function|
name=resist|
return_type=boolean|
parameter1={{Param|element|resist_it}}|
parameter2={{Param|boolean|really}}|
p1desc={{pspan|resist_it}} is the element to resist|
p2desc={{pspan|really}} is true to actually attemp resistance, false to check only|
}}
Returns whether you are able to resist a given element {{pspan|resist_it}}, or if {{pspan|really}} is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot) and returns its success.

{{HideLink|my_defstat}}{{Function|
name=my_defstat|
return_type=int|
parameter1={{Param|boolean|usespec}}|
p1desc={{pspan|usespec}} is optional. If true, uses speculative values rather than real values.|
}}
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

{{HideLink|get_safemox}}{{Function|
name=get_safemox|
return_type=int|
parameter1={{Param|location|where}}|
p1desc={{pspan|where}} is the location to check for safe moxie|
}}
Using mafia's location/monster data, returns the safe moxie of a given zone {{pspan|where}}.

{{HideLink|auto_mcd}}{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|int|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|monster|check_me}}|
}}
{{Function|
name=auto_mcd|
return_type=boolean|
parameter1={{Param|location|check_me}}|
p1desc={{pspan|check_me}} is the int, monster or location to check|
}}
If your ZLib setting "automcd" is true, automatically adjusts your mind-control device for maximum stat gains based on safe moxie and your ZLib "threshold" setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats. Returns true unless KoLmafia is unable to do so, even though the script thinks it should be capable (still returns true if you can't currently access an mcd-changing device).

{{HideLink|best_fam}}{{Function|
name=best_fam|
return_type=familiar|
parameter1={{Param|string|type}}|
p1desc={{pspan|type}} is the type of familiar ability to check for|
}}
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your ZLib "is_100_run" setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

== Kmail Functions ==

{{HideLink|load_kmail}}{{Function|
name=load_kmail|
return_type=void|
parameter1={{Param|string|calledby}}|
p1desc={{pspan|calledby}} is optional and allows you to specify the name of the script calling this function, which will be submitted when the script visits api.php. The default value is "ZLib-powered-script".|
}}
This function parses your kmail inbox in a single server hit and loads it into the global variable "mail", which is of type kmessage[int]. A kmessage is a record type, with the following fields:
{{CodeSample|
code=
<syntaxhighlight>
record kmessage {
int id; // message id
string type; // possible values observed thus far: normal, giftshop
int fromid; // sender's playerid (0 for npc's)
int azunixtime; // KoL server's unix timestamp
string message; // message (not including items/meat)
int[item] items; // items included in the message
int meat; // meat included in the message
string fromname; // sender's playername
string localtime; // your local time according to your KoL account, human-readable string
};
</syntaxhighlight>}}

Thus, after calling this function your inbox is very easy to work with. You can foreach over each message if you like, accessing the fields for details.

{{HideLink|process_kmail}}{{Function|
name=process_kmail|
return_type=void|
parameter1={{Param|string|functionname}}|
p1desc={{pspan|functionname}} specifies the name of a function designed to parse kmail.|
}}
If you liked load_kmail(), you'll like this even better. First off, this function loads your kmail into the mail variable if you haven't already done so. Next, it calls a function named {{pspan|functionname}} on each kmail message. The function must be at top level, accept a single kmessage parameter, and return a boolean. For each kmail in your inbox, if the called function returns true, that message will be deleted once all messages have been processed.

Here's a simple example which will delete all messages from your lovely Pen Pal:
{{CodeSample|
code=
<syntaxhighlight>
boolean no_penpal(kmessage m) {
if (m.fromname == "Your Pen Pal") return true;
return false;
}
process_kmail("no_penpal");
</syntaxhighlight>}}

{{HideLink|send_gift}}{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=send_gift|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is a map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message|
}}
Sends a gift to a player. Able to split large amounts of items. Returns true if the package is sent and false if not. See kmail() below.

{{HideLink|kmail}}{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|string|recipient}}|
parameter2={{Param|string|message}}|
parameter3={{Param|int|meat}}|
parameter4={{Param|int [item]|goodies|ag=t}}|
parameter5={{Param|string|inside_note}}|
p1desc={{pspan|recipient}} is the player to send to|
p2desc={{pspan|message}} is the outside message|
p3desc={{pspan|meat}} is the amount of meat to send|
p4desc={{pspan|goodies}} is an optional map of items & amounts to send|
p5desc={{pspan|inside_note}} is an optional inside message if sent as a gift|
}}
{{Function|
name=kmail|
return_type=boolean|
parameter1={{Param|kmessage|km}}|
p1desc={{pspan|km}} allows you to send a kmail supplied in kmessage format. The only thing unusual here is that the "fromname" field will be used as the recipient. The other fields will be used appropriately to call the above kmail function.|
}}
Sends a kmail to player {{pspan|recipient}}, returning true if the kmail is successfully sent. Handles splitting the {{pspan|message}} into multiple messages if the number of item types in {{pspan|goodies}} is too large. Returns the result of send_gift() if the intended {{pspan|recipient}} is unable to receive the {{pspan|message}} due to being in HC or somesuch. Note that you can also specify the {{pspan|inside_note}} to be used inside gifts in that case. Use "\n" to specify a new line in the {{pspan|message}}.

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]

Batfactors

2013-10-08T05:21:33Z

Zarqon: /* Special */

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|nohit
|This monster never hits.
|-
|nomiss
|This monster never misses (e.g. gremlins).
|-
|nostun
|The monster is completely immune to stuns and staggers of any duration.
|-
|nomultistun
|The monster is immune to multi-round stunners, such as Entangling Noodles.
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|noitems (X)
|You cannot use items in combat with this monster. If a value is specified, it should be a float representing the monster's chance of blocking item use.
|-
|noskills (X)
|As with noitems above, but for skills.
|-
|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).
|-
|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.
|}

Batfactors

2013-10-08T05:20:46Z

Zarqon: underwater keyword

{{TOCright}}{{DISPLAYTITLE:batfactors (batfactors.txt)}}
== 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:

<syntaxhighlight>
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;
</syntaxhighlight>

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.

{| class="wikitable"
!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.
|-
|monster
|arbitrary index
|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.
|-
|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. 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. 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.

{| class="wikitable"
|+Examples
|-
|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 hot,cold,spooky,sleaze,stench
|deals 2 each of hot, cold, spooky, sleaze, and stench damage (2 prismatic damage)
|}

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

{| class="wikitable"
|+Examples
|-
|<nowiki>3 hot|7 spooky</nowiki>
|deals 3 hot damage and 7 spooky damage
|-
|<nowiki>50 hot,cold|4 hot</nowiki>
|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:

{| class="wikitable"
!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.
|-
|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 <nowiki>Mus|Mys|Mox</nowiki>.
|-
|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).
|-
|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.

{| class="wikitable"
!Keyword
!Presence Indicates
|-
|once
|The action can only be used once per combat.
|-
|endscombat
|The action automatically ends combat.
|-
|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.
|-
|underwater
|This item or skill is only valid underwater.
|}

== 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 meaningless since ASH has no to_int(monster). Instead, the ufname field is used, and must be the name of a monster.

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, so you only need to include this information if the monster has exceptional resistances. These resistances will overwrite the existing resistances on a per-element basis.

The pdmg field is unused.

Finally, the special field contains an entirely new set of keywords, which are only for use in the monster category:

{| class="wikitable"
!Keyword
!Value/Indicates
|-
|nohit
|This monster never hits.
|-
|nomiss
|This monster never misses (e.g. gremlins).
|-
|nostun
|The monster is completely immune to stuns and staggers of any duration.
|-
|nomultistun
|The monster is immune to multi-round stunners, such as Entangling Noodles.
|-
|seal
|The monster is a seal and can only be damaged by clubs.
|-
|noitems (X)
|You cannot use items in combat with this monster. If a value is specified, it should be a float representing the monster's chance of blocking item use.
|-
|noskills (X)
|As with noitems above, but for skills.
|-
|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).
|-
|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.
|}