Kolmafia - User contributions [en]

Zlib

2013-12-04T14:28:24Z

PsyMar: /* Adventuring Functions */ the third parameter of obtain is "location place", this is named place and is of type location, not vice-versa (as the comments below the function previously indicated)

{{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|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]]

Ash Functions

2013-06-30T21:31:01Z

PsyMar: /* d */ redlink to dad_sea_monkee_weakness

{{TOCright}}
Master list of all ASH functions. All functions as of r8144 are listed; this list is intended to be kept current, but it is possible that some functions added since the above revision may be missing. (Please feel free to add in any you notice.)
===a===
{{Flink|void|abort|{{opt|string}}}}
{{Flink|void|add_item_condition|int|item}}
{{Flink|boolean|adv1|location|int|string}}
{{Flink|boolean|adventure|int|location|{{opt|string}}}}
{{Flink|float [monster]|appearance_rates|location|{{opt|boolean}}}}
{{Flink|buffer|append|buffer|string}}
{{Flink|buffer|append_replacement|matcher|buffer|string}}
{{Flink|buffer|append_tail|matcher|buffer}}
{{Flink|buffer|attack}}
{{Flink|boolean|autosell|int|item}}
{{Flink|int|autosell_price|item}}
{{Flink|int|available_amount|item}}
===b===
{{Flink|boolean|batch_close}}
{{Flink|void|batch_open}}
{{Flink|boolean|black_market_available}}
{{Flink|boolean|boolean_modifier|string|{{opt|string}}}}
{{Flink|boolean|boolean_modifier|item|string}}
{{Flink|int|buffed_hit_stat}}
{{Flink|boolean|buy|int|item}}
{{Flink|int|buy|int|item|int}}
{{Flink|boolean|buy|coinmaster|int|item}}
{{Flink|int|buy_price|coinmaster|item}}
{{Flink|boolean|buys_item|coinmaster|item}}
===c===
{{Flink|boolean|can_drink}}
{{Flink|boolean|can_eat}}
{{Flink|boolean|can_equip|item}}
{{Flink|boolean|can_interact}}
{{flink|boolean|canadia_available}}
{{Flink|int|ceil|float}}
{{Flink|boolean|chamber}}
{{Flink|boolean|change_mcd|int}}
{{Flink|string|char_at|string|int}}
{{Flink|void|chat_clan|string|{{opt|string}}}}
{{Flink|void|chat_macro|string}}
{{Flink|void|chat_notify|string|string}}
{{Flink|void|chat_private|string|string}}
{{Flink|class|class_modifier|string|string}}
{{Flink|class|class_modifier|item|string}}
{{Flink|void|clear|aggregate}}
{{Flink|boolean|cli_execute|string}}
{{Flink|int|closet_amount|item}}
{{Flink|int|combat_mana_cost_modifier}}
{{Flink|float|combat_rate_modifier}}
{{Flink|boolean|contains_text|string|string}}
{{Flink|void|council}}
{{Flink|int|count|aggregate}}
{{Flink|boolean|craft|string|int|item|item}}
{{Flink|int|creatable_amount|item}}
{{Flink|boolean|create|int|item}}
{{Flink|matcher|create_matcher|string|string}}
{{Flink|stat|current_hit_stat}}
{{Flink|int|current_mcd}}

===d===
{{Flink|element|dad_sea_monkee_weakness|int}}
{{Flink|item|daily_special}}
{{Flink|float|damage_absorption_percent}}
{{Flink|int|damage_reduction}}
{{Flink|buffer|delete|buffer|int|int}}
{{Flink|void|disable|string}}
{{flink|boolean|dispensary_available}}
{{Flink|int|display_amount|item}}
{{Flink|boolean|drink|int|item}}

===e===
{{Flink|boolean|eat|int|item}}
{{Flink|boolean|eatsilent|int|item}}
{{Flink|effect|effect_modifier|string|string}}
{{Flink|effect|effect_modifier|item|string}}
{{Flink|float|elemental_resistance|element}}
{{Flink|float|elemental_resistance|{{opt|monster}}}}
{{Flink|boolean|empty_closet}}
{{Flink|void|enable|string}}
{{Flink|int|end|matcher|{{opt|int}}}}
{{Flink|boolean|enthrone_familiar|familiar}}
{{Flink|string|entity_decode|string}}
{{Flink|string|entity_encode|string}}
{{Flink|boolean|entryway}}
{{Flink|boolean|equip|{{opt|slot}}|item}}
{{Flink|int|equipped_amount|item}}
{{Flink|item|equipped_item|slot}}
{{Flink|int|expected_damage|{{opt|monster}}}}
{{Flink|float|experience_bonus}}
{{Flink|float|expression_eval}}
{{Flink|int [item]|extract_items|string}}
{{Flink|int|extract_meat|string}}

===f===
{{Flink|item|familiar_equipment|familiar}}
{{Flink|item|familiar_equipped_equipment|familiar}}
{{Flink|int|familiar_weight|familiar}}
{{Flink|boolean|file_to_map|string|aggregate|{{opt|boolean}}}}
{{Flink|boolean|find|matcher}}
{{Flink|int|floor|float}}
{{Flink|string|form_field|string}}
{{Flink|string [string]|form_fields}}
{{Flink|string|format_date_time|string|string|string}}
{{Flink|boolean|friars_available}}
{{Flink|int|fullness_limit}}

===g===
{{Flink|boolean|galaktik_cures_discounted}}
{{Flink|int|gameday_to_int}}
{{Flink|string|gameday_to_string}}
{{Flink|int|gametime_to_int}}
{{Flink|int|get_auto_attack}}
{{Flink|int [item]|get_campground}}
{{Flink|string|get_ccs_action|int}}
{{Flink|int|get_clan_id}}
{{Flink|string|get_clan_name}}
{{Flink|string|get_counters|string|int|int}}
{{Flink|string [int]|get_custom_outfits}}
{{Flink|item|get_dwelling|}}
{{Flink|string [int]|get_goals}}
{{Flink|int [item]|get_ingredients|item}}
{{Flink|int [item]|get_inventory}}
{{Flink|monster [int]|get_monsters|location}}
{{Flink|string [int]|get_moods}}
{{Flink|string [int]|get_outfits}}
{{Flink|string|get_path}}
{{Flink|string|get_path_full}}
{{Flink|string|get_path_variables}}
{{Flink|string|get_player_id|string}}
{{Flink|int|get_power|item}}
{{Flink|string|get_property|string}}
{{Flink|int [item]|get_related|item|string}}
{{Flink|int|get_revision}}
{{Flink|int [item]|get_shop}}
{{Flink|string|get_version}}
{{flink|boolean|gnomads_available}}
{{flink|boolean|goal_exists|string}}
{{Flink|string|group|matcher|{{opt|int}}}}
{{Flink|int|group_count|matcher}}
{{Flink|string [int, int]|group_string|string|string}}
{{Flink|item|guardians}}
{{Flink|boolean|guild_store_available}}

===h===
{{Flink|boolean|have_bartender}}
{{Flink|boolean|have_chef}}
{{Flink|boolean|have_display}}
{{Flink|int|have_effect|effect}}
{{Flink|boolean|have_equipped|item}}
{{Flink|boolean|have_familiar|familiar}}
{{Flink|boolean|have_mushroom_plot}}
{{Flink|boolean|have_outfit|string}}
{{Flink|boolean|have_shop}}
{{Flink|boolean|have_skill|skill}}
{{Flink|boolean|hedgemaze}}
{{Flink|boolean|hermit|int|item}}
{{flink|boolean|hidden_temple_unlocked}}
{{Flink|boolean|hippy_stone_broken}}
{{Flink|boolean|hippy_store_available}}
{{Flink|float|historical_age|item}}
{{Flink|int|historical_price|item}}

===i===
{{Flink|monster|image_to_monster|strict_string}}
{{Flink|boolean|in_bad_moon}}
{{Flink|boolean|in_hardcore}}
{{Flink|boolean|in_moxie_sign}}
{{Flink|boolean|in_muscle_sign}}
{{Flink|boolean|in_mysticality_sign}}
{{Flink|string|inaccessible_reason|coinmaster|}}
{{Flink|int|index_of|string|string|{{opt|int}}}}
{{Flink|int|inebriety_limit}}
{{Flink|float|initiative_modifier}}
{{Flink|buffer|insert|buffer|int|string}}
{{Flink|boolean|is_accessible|coinmaster}}
{{Flink|boolean|is_coinmaster_item|item}}
{{Flink|boolean|is_discardable|item}}
{{Flink|boolean|is_displayable|item}}
{{Flink|boolean|is_giftable|item}}
{{Flink|boolean|is_goal|item}}
{{Flink|boolean|is_integer|string}}
{{Flink|boolean|is_npc_item|item}}
{{Flink|boolean|is_online|string}}
{{Flink|boolean|is_tradeable|item}}
{{Flink|boolean|is_trendy|any}}
{{Flink|boolean|is_wearing_outfit|string}}
{{Flink|int|item_amount|item}}
{{Flink|float|item_drop_modifier}}
{{Flink|int [item]|item_drops|{{opt|monster}}}}
{{Flink|record [int]|item_drops_array|{{opt|monster}}}}
{{Flink|string|item_type|item}}

===k===
{{flink|boolean|knoll_available}}
===l===
{{Flink|int|last_index_of|string|string|{{opt|int}}}}
{{Flink|string|last_item_message}}
{{Flink|monster|last_monster}}
{{Flink|string|last_skill_message}}
{{Flink|int|length|string}}
{{Flink|buffer|load_html|string}}
{{Flink|void|lock_familiar_equipment|boolean}}
{{Flink|void|logprint|string}}
===m===
{{Flink|string|make_url|string|boolean|boolean}}
{{Flink|int|mall_price|item}}
{{Flink|int|mana_cost_modifier}}
{{Flink|boolean|map_to_file|aggregate|string|{{opt|boolean}}}}
{{Flink|float|max|float|float}}
{{Flink|int|max|int|int}}
{{Flink|boolean|maximize|string|boolean}}
{{Flink|boolean|maximize|string|int|int|boolean}}
{{Flink|record [int]|maximize|string|int|int|boolean|boolean}}
{{Flink|int|meat_drop|{{opt|monster}}}}
{{Flink|float|meat_drop_modifier}}
{{Flink|float|min|float|float}}
{{Flink|int|min|int|int}}
{{Flink|item|minstrel_instrument}}
{{Flink|int|minstrel_level}}
{{Flink|boolean|minstrel_quest}}
{{Flink|int|mmg_bet_amount|int}}
{{Flink|string|mmg_bet_owner|int}}
{{Flink|int|mmg_bet_owner_id|int}}
{{Flink|string|mmg_bet_taker}}
{{Flink|string|mmg_bet_taker_id}}
{{Flink|int|mmg_bet_winnings}}
{{Flink|int|mmg_make_bet|int|boolean}}
{{Flink|int [int]|mmg_my_bets}}
{{Flink|int [int]|mmg_offered_bets}}
{{Flink|boolean|mmg_retract_bet|int}}
{{Flink|void|mmg_search|int|int}}
{{Flink|int|mmg_take_bet|int|boolean}}
{{Flink|void|mmg_visit}}
{{Flink|int|mmg_wait_event|int}}
{{Flink|float|modifier_eval|string}}
{{Flink|int|monster_attack|{{opt|monster}}}}
{{Flink|int|monster_defense|{{opt|monster}}}}
{{Flink|element|monster_element|{{opt|monster}}}}
{{Flink|float|monster_eval|string}}
{{Flink|int|monster_hp|{{opt|monster}}}}
{{Flink|int|monster_level_adjustment}}
{{Flink|phylum|monster_phylum|{{opt|monster}}}}
{{Flink|int|moon_light}}
{{Flink|int|moon_phase}}
{{Flink|int|mp_cost|skill}}
{{Flink|int|my_adventures}}
{{Flink|int|my_ascensions}}
{{Flink|int|my_basestat|stat}}
{{Flink|int|my_buffedstat|stat}}
{{Flink|class|my_class}}
{{Flink|int|my_closet_meat}}
{{Flink|string|my_companion}}
{{Flink|int|my_daycount|}}
{{Flink|familiar|my_effective_familiar}}
{{Flink|int [effect]|my_effects}}
{{Flink|familiar|my_enthroned_familiar}}
{{Flink|familiar|my_familiar}}
{{Flink|int|my_fullness}}
{{Flink|string|my_hash}}
{{Flink|int|my_hp}}
{{Flink|string|my_id}}
{{Flink|int|my_inebriety}}
{{Flink|int|my_level}}
{{Flink|location|my_location}}
{{Flink|int|my_maxhp}}
{{Flink|int|my_maxmp}}
{{Flink|int|my_meat}}
{{Flink|int|my_mp}}
{{Flink|string|my_name}}
{{flink|string|my_path}}
{{Flink|stat|my_primestat}}
{{flink|string|my_sign}}
{{Flink|int|my_spleen_use}}
{{Flink|int|my_turncount}}

===n===
{{Flink|float|now_to_string|string}}
{{Flink|int|npc_price|item}}
{{Flink|float|numeric_modifier|string|{{opt|string}}}}
{{Flink|float|numeric_modifier|item|string}}
{{Flink|float|numeric_modifier|effect|string}}
{{Flink|float|numeric_modifier|skill|string}}
{{Flink|float|numeric_modifier|familiar|string|int|item}}

===o===
{{Flink|boolean|outfit|string}}
{{Flink|item [int]|outfit_pieces|string}}
{{Flink|boolean|overdrink|int|item}}

===p===
{{Flink|void|print|string|{{opt|string}}}}
{{Flink|void|print_html|string}}
{{Flink|int|pulls_remaining}}
{{Flink|boolean|put_closet|int|{{opt|item}}}}
{{Flink|boolean|put_display|int|item}}
{{Flink|boolean|put_shop|int|int|{{opt|int}}|item}}
{{Flink|boolean|put_stash|int|item}}
{{Flink|int|pvp_attacks_left}}
===r===
{{Flink|int|random|int}}
{{Flink|int|raw_damage_absorption}}
{{Flink|boolean|refresh_stash}}
{{Flink|boolean|refresh_status}}
{{Flink|void|remove_item_condition|int|item}}
{{Flink|boolean|replace|buffer|int|int|string}}
{{Flink|string|replace_all|matcher|string}}
{{Flink|string|replace_first|matcher|string}}
{{Flink|buffer|replace_string|buffer|string|string}}
{{Flink|buffer|replace_string|string|string|string}}
{{Flink|matcher|reset|matcher|{{opt|string}}}}
{{Flink|boolean|restore_hp|int}}
{{Flink|boolean|restore_mp|int}}
{{Flink|boolean|retrieve_item|int|item}}
{{Flink|int|round|float}}
{{Flink|buffer|run_combat}}
{{Flink|buffer|runaway}}

===s===
{{Flink|boolean|sell|coinmaster|int|item}}
{{Flink|int|sell_price|coinmaster|item}}
{{Flink|boolean|sells_item|coinmaster|item}}
{{Flink|string [int]|session_logs|{{opt|string}}|int}}
{{Flink|void|set_auto_attack|int}}
{{Flink|void|set_length|buffer|int}}
{{Flink|void|set_location|location}}
{{Flink|void|set_property|string|string}}
{{Flink|int|shop_amount|item}}
{{Flink|int|spleen_limit}}
{{Flink|string [int]|split_string|string|{{opt|string}}}}
{{Flink|float|square_root|float}}
{{Flink|int|start|matcher|{{opt|int}}}}
{{Flink|int|stash_amount|item}}
{{Flink|stat|stat_bonus_today}}
{{Flink|stat|stat_bonus_tomorrow}}
{{Flink|stat|stat_modifier|effect|string}}
{{Flink|buffer|steal}}
{{Flink|int|stills_available}}
{{Flink|int|storage_amount|item}}
{{Flink|string|string_modifier|string}}
{{Flink|string|string_modifier|string|string}}
{{Flink|string|substring|string|int|{{opt|int}}}}

===t===
{{Flink|boolean|take_closet|int|{{opt|item}}}}
{{Flink|boolean|take_display|int|item}}
{{Flink|boolean|take_shop|item|{{opt|boolean}}}}
{{Flink|boolean|take_stash|int|item}}
{{Flink|boolean|take_storage|int|item}}
{{Flink|int|tavern|{{opt|string}}}}
{{Flink|buffer|throw_item|item}}
{{Flink|buffer|throw_items|item|item}}
{{Flink|buffer|time_to_string}}
{{Flink|boolean|to_boolean|any}}
{{Flink|class|to_class|string}}
{{Flink|coinmaster|to_coinmaster|string}}
{{Flink|effect|to_effect|int}}
{{Flink|effect|to_effect|string}}
{{Flink|effect|to_effect|skill}}
{{Flink|element|to_element|string}}
{{Flink|familiar|to_familiar|int}}
{{Flink|familiar|to_familiar|string}}
{{Flink|float|to_float|any}}
{{Flink|int|to_int|any}}
{{Flink|item|to_item|string}}
{{Flink|item|to_item|int}}
{{Flink|item|to_item|string|int}}
{{Flink|string|to_json|null}}
{{Flink|location|to_location|string}}
{{Flink|location|to_location|int}}
{{Flink|string|to_lower_case|string}}
{{Flink|monster|to_monster|string}}
{{Flink|phylum|to_phylum|string}}
{{Flink|string|to_plural|item}}
{{Flink|skill|to_skill|int}}
{{Flink|skill|to_skill|string}}
{{Flink|skill|to_skill|effect}}
{{Flink|slot|to_slot|item}}
{{Flink|stat|to_stat|string}}
{{Flink|string|to_string|any}}
{{Flink|string|to_upper_case|string}}
{{Flink|string|to_url|location}}
{{Flink|string|today_to_string}}
{{Flink|int|truncate|float}}
{{Flink|int|turns_per_cast|skill}}
{{Flink|int|turns_played}}

===u===
{{Flink|string|url_decode|string}}
{{Flink|string|url_encode|string}}
{{Flink|boolean|use|int|item}}
{{Flink|boolean|use_familiar|familiar}}
{{Flink|boolean|use_skill|int|skill|{{opt|string}}}}
{{Flink|buffer|use_skill|skill}}
{{Flink|boolean|user_confirm|string}}
{{Flink|boolean|user_confirm|string|int|boolean}}

===v===
{{Flink|boolean|visit|coinmaster}}
{{Flink|buffer|visit_url|string}}
{{Flink|buffer|visit_url|string|boolean}}
{{Flink|buffer|visit_url|string|boolean|boolean}}
===w===
{{Flink|void|wait|int}}
{{Flink|void|waitq|int}}
{{Flink|int|weapon_hands|item}}
{{Flink|stat|weapon_type|item}}
{{Flink|int|weight_adjustment}}
{{Flink|boolean|white_citadel_available}}
{{Flink|boolean [string]|who_clan}}
{{Flink|boolean|will_usually_dodge}}
{{Flink|boolean|will_usually_miss}}
{{Flink|void|write|string}}
{{Flink|void|writeln|string}}

Data Structures

2013-06-30T21:16:59Z

PsyMar: /* Assignments */ fix comments to reflect code

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates my_pricelist with new_pricelist */

my_pricelist = new_pricelist;
</syntaxhighlight>}}

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
</syntaxhighlight>}}

If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills my_map[ "slice1" ] with slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738 and http://kolmafia.us/showthread.php?10729

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}

<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used. But please note that when you sort a map, you change the values that correspond to the index. To sort on a map, you would want to use a multidimensional maps, but note that you can only sort along a single dimension at a time when doing this. Simply put... "sort" is only useful in cases where your data exists entirely in the values of the map; the keys can have no meaning beyond simply being distinct.

The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

To find out how many things you have, you might do:
{{CodeSample|code=<syntaxhighlight>
item [int] whatGot;
int ctr =0;

foreach it in get_inventory() {
whatGot[ctr] = it;
ctr+=1;
}

sort whatGot by item_amount(value);

foreach x, it in whatGot
print(item_amount(it) + ' of ' + it);
</syntaxhighlight>}}
Note that this use of an optional feature of foreach. The second variable in the foreach is the value of whatGot[x].

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(copy-pasted from Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Starting with SVN revision 1311 of KoLmafia, ASH now supports a new kind of structured data: the record. Here is a little example of how you declare a record and variables of the new type you've created by doing so.

{{CodeSample|code=<syntaxhighlight>
record my_type {
int ifield;
string sfield;
record {
int first;
int second;
} rfield;
int [int, int] mfield;
};

my_type rvar;
my_type [int] mrvar;
</syntaxhighlight>}}

What I've done with the above is declare a new data type which I've named "my_type". Having declared the new type, I can use it (almost) anywhere that I can use a built-in type name. I declared a variable, "rvar", of that type, and I defined a map, "mrvar", which maps keys of type integer to values of type my_type.

The new type, "my_type" is a "composite" type. It contains four fields. "ifield" is an integer. "sfield" is a string. "rfield" is another composite field: an anonymous record containing two integers named "first" and "second". Finally, "mfield" is a map from [int, int] to int.

As you can see, a record can combine data of all the types ASH supports: primitive, aggregate, and composite.

Having defined the new data type and several variables using it, here are some examples of how to access the fields.

{{CodeSample|code=<syntaxhighlight>
rvar.ifield = 10;
rvar.sfield = "secret";
rvar.rfield.first = 1000;
rvar.rfield.second = 2000;
rvar.mfield[ 2, 3 ] = 12;

mrvar[ 1 ] = rvar;

foreach key in mrvar
foreach key1, key2 in mrvar[key].mfield
print( "val = " + mrvar[key].mfield[key1,key2] );
</syntaxhighlight>}}

As you can see, if you have a variable that is a record, you access the fields of the record by following the variable name with ".<field name>". The resulting value will be of whatever type you declared in the definition of the record. If the value is a map, you can give a list of keys within [], just like any other map. If the value is another record, you can access the fields of the nested record by using another ".<field name>".

If you are familiar with Pascal "records" or C/C++ "structs", this should all be comfortably familiar.

Finally, if you create a map whose values is a record, the file_to_map and map_to_file built-in ASH functions will Do The Right Thing; they will efficiently and reliably save and restore your data.

[[Category:Scripting]]

Custom Combat Script

2013-06-10T10:24:19Z

PsyMar: example script calculated several things wrong; immaculate seasoning does not override gazpacho's, for example. Also, saucespheres aren't needed for splash, but being a sauceror is

{{TOCright}}
== Basic CCS ==
A Custom Combat Script (CCS) is a way of instructing mafia how to handle combat, round by round. For example, a simple CCS would be to tell mafia to pickpocket on round 1, then cast entangling noodles on round 2 and finally on rounds 3+ to use shieldbutt. If it is unable to carry out one of those steps, then that step will be skipped. For instance, if the character failed to get initiative, then pickpocket will be skipped and the character will go straight to entangling noodles. That CCS would look like this:

<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ]<br />
try to steal an item<br />
skill entangling noodles<br />
skill shieldbutt<br />
</div>

If you wanted to treat different monsters differently, that can be accommodated also. For instance, the following CCS will attempt to cast Transcendent Olfaction upon Black Knights while treating all other monsters differently. If the character currently has "On the Trail" then that line will be skipped.

<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ Black Knight ]<br />
try to steal an item<br />
skill transcendent olfaction<br />
skill entangling noodles<br />
skill shieldbutt<br />

[ default ]<br />
try to steal an item<br />
skill entangling noodles<br />
skill shieldbutt<br />
</div>

Note that when you use a CCS, your CLI will report "character executes a macro!" because the CCS is converted into a macro to save on page loads

=== Available Commands ===
* attack
* skill
* item, use
* try to steal an item, pickpocket
* summon pastamancer ghost
* jiggle chefstaff
* combo {followed by one of the following}
** Disco Concentration, Disco Nirvana, Disco Inferno, Disco Bleeding, Disco Blindness
** Rave Knockout, Rave Bleeding, Rave Concentration, Rave Steal, Rave Nirvana, Rave Stats
** [http://kolmafia.us/showthread.php?5709-Add-rave-combo-learning-to-quot-special-action-quot&p=42107&viewfull=1#post42107 random rave]
* abort
* abort after
* section [section name]
* special
* delevel
* skip
* note
* twiddle

== Macros in CCS ==
Macros may be used in a Custom Combat Script in addition to the basic commands. Any line in quotes and any macro command used in a CCS will be made into part of the macro which KoLmafia is passing to KoL. You can find an primer on all KoL's macros at {{kolwiki|Combat Macros}}.

Also there is a section in the CCS called "global prefix" which will be part of every combat macro KoLmafia generates, regardless of the monster encountered.

=== Example of CCS Macro ===
Here's an example of a CCS that generates a macro which will cause KoL to wait for a hobo monkey to steal meat from your enemy before launching attacks.
<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ]<br />
sub monkey_stasis<br />
:while !match "climbs up and sits on your shoulder" && !pastround 20 && !hppercentbelow 20
::call stasis_item
:endwhile
endsub<br />
call monkey_stasis<br />
attack

[ global prefix ]<br />
scrollwhendone<br />
"abort missed 5"<br />
"abort pastround 27"<br />
sub stasis_item<br />
:if hascombatitem facsimile dictionary
::item facsimile dictionary
::goto _endstasisitem
:endif
:if hascombatitem seal tooth
::item seal tooth
::goto _endstasisitem
:endif
:if hascombatitem spices
::item spices
::goto _endstasisitem
:endif
:if hascombatitem spectre scepter
::item spectre scepter
::goto _endstasisitem
:endif
:if hascombatitem dictionary
::item dictionary
::goto _endstasisitem
:endif
:if hascombatitem fat stacks of cash
::item fat stacks of cash
::goto _endstasisitem
:endif
:"abort "No infinite use items detected!" "
:mark _endstasisitem
endsub<br />
sub stasis<br />
:while !pastround 20 && !hppercentbelow 20 && mppercentbelow 99
::call stasis_item
:endwhile
endsub
</div>

=== Concerns for macros in CCS ===
*A macro's abort command needs to be encased in quotes because abort is also a legal CCS command. That's why all aborts in the previous example were quoted.

*If a comment is the last line in a CCS, that will be used as your finishing attack even though it does nothing. Never conclude a CCS with a macro comment or it will abort to the mini-browser with a warning from KoL that you executed 37 commands in a row without taking an action.

== Consult Scripts ==
While a CCS may seem reasonably flexible, sometimes you will want to do something too complicated to express in that format. For instance if you want your character to take different actions based on your characters current stats or current monster level, a consult script can automatically figure it out. There are few limits to what a consult script can enable. The downside to using a consult script is that KoLmafia will not be able to generate a combat macro to pass to KoL. As a result multi-round combat will take somewhat longer.

A consult script is called by using the "consult" command in your CCS, as follows:

<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ]<br />
consult myscript.ash<br />
attack<br />
</div>

The main() function in the ASH script being consulted must accept three parameters:

void main(int round, monster mob, string combat)

These values will be supplied by mafia when the consult script is called.

=== Example of a Consult Script ===
This example will attempt to maximize use of a Sauceror's spells as a Sauceror by making use of sauce splash effects when they can be used.
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
// Save this as SauceSplash.ash
boolean sauceSplash() {
if(!my_class() == $class[Sauceror])
return false;
int normal = numeric_modifier("spell damage");
if(normal >= 25)
return true;
int cold = numeric_modifier("cold spell damage");
int hot = numeric_modifier("hot spell damage");

#deal with monsters weak to cold
if(((((monster_element() == $element[stench]) || (monster_element() == $element[sleaze]))
&& have_skill($skill[Immaculate Seasoning]))
|| have_equipped($item[Gazpacho's Glacial Grimoire]))
&& cold + normal >= 25)
return true;
#deal with monsters weak to hot
else if((((((monster_element() == $element[cold]) || (monster_element() == $element[spooky]))
&& have_skill($skill[Immaculate Seasoning]))
|| have_equipped($item[Codex of Capsaicin Conjuration])
|| have_equipped($item[Ol' Scratch's manacles])
|| have_equipped($item[Ol' Scratch's ash can]))
&& hot + normal >= 25)
#deal with monsters weak to neither (hot/non-aligned)
else if(have_skill($skill[Immaculate Seasoning])
&& cold != hot && max(cold, hot) + normal >= 25)
return true;
else return false;
}

void main(int initround, monster foe, string page) {
if(have_effect($effect[Burning Soul]) || have_effect($effect[Soul Freeze]) || !sauceSplash())
use_skill($skill[Saucegeyser]);
else
use_skill($skill[Wave of Sauce]);
}
</syntaxhighlight></div>

This consult script can then be integrated into a CCS like this:
<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ]<br />
consult SauceSplash.ash<br />
attack<br />
</div>

=== Parts of a Combat Consultation Script ===
As you can see in the above example, a consultation script is called with three parameters.
*The first parameter is the round of combat that the script is called. Sometimes it is important to keep track of the round. This is particularly important to keep from losing the fight by going over 30 rounds.
*The second parameter is the monster that you are fighting. This is important because it enables you to take different actions for different monsters.
*The third parameter is the text of the page. This is important because it enables you to examine every detail of the fight as it is taking place. It can be analyzed for potential actions, damage that you deal to a monster and all other events.

All possible actions you can take in a round of combat are listed under [[In-combat Consulting]].

=== Resolution of a Combat Consultation Script ===
The consult script can automate as many, or as few rounds of combat as desired to achieve its goal. When it finishes executing, if the monster is not yet dead, then the CCS will continue combat from the current round. Note that the current round is not always the next line in a script. For instance, if the consult script is called at round 1 and executes three actions, then it will return to the CCS at round 4. This is why most CCSs containing consult script prefer to have only a line after the consult script, usually a simple method of killing a monster.

=== Macros in Consult Scripts ===
It is possible for a consult script to submit a macro. As a simple example, if your consult script wants to submit a macro that simply attacks the monster until the combat ends...

<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
string macro = "attack; repeat"
visit_url("fight.php?action=macro&macrotext=" + url_encode(macro) ,true,true);
</syntaxhighlight></div>

Between macro commands you need to insert either /n or a semi-colon as in the above example. Your submitted macro can be as complicated as you wish.

== Employ Scripts ==
<div style="padding: 1em; border: solid 1px red; color: red; font-weight: bold;">Please note! This section is speculative; Employ Scripts have not yet been implemented.</div>
An employ script is a like a consultation script, with benefits. While a consultation script operates turn-by-turn, an employ script operates only at the beginning of the combat and generates a combat macro.

Employ scripts do not yet exist in KolMafia at this time, but they are a goal that jasonharper is working towards as he [http://kolmafia.us/showthread.php?4098-Dynamic-Combat-in-the-Age-of-Macros describes on the mafia forum].

It is currently proposed that they will have the following format:

'''string main( string opponent, string pageText, string macroSoFar, string parameter )'''

* opponent is the name of the monster being fought, just as in a consult script or combat filter function.
* pageText is the raw HTML of the initial combat page. This isn't necessarily going to be useful (since it's a one-time snapshot), however you may want to examine the Skills popup to see what conditionally-available skills are actually available.
* macroSoFar is the current text of the macro being built - a mafia-generated header with some useful subroutines defined, followed by macro translations of all the prior lines in the CCS.
* parameter contains any extra text from the CCS line; it could be used to customize the behavior of the script, more conveniently than using a "note" line with a consult script. It also serves the less obvious purpose of making the parameter count something other than 3, so that mistakenly attempting to employ a consult script, or consult an employ script, will fail before any code runs.
* The return value entirely replaces the macro being built. It would probably be an error for this to be any shorter than the original value of macroSoFar.

The simplest thing an employ script could do is to append some commands to macroSoFar, and return that. Other possibilities include:
* It could look back through the previously-generated macro commands to decide what to do. For example, it could refrain from adding a "pickpocket" action if that has already been done
* If it wanted to set up a global abort condition, active throughout the combat, it could insert the command at the beginning of the macro.
* There will be a subroutine called "mafiaround" defined in the header, and called before every combat action to handle things like automatic antidote use. The script could insert commands into that subroutine, for example to implement an eye color check for using He-Boulder major rays.
* There will likely be other defined subroutines for the script to call or modify.

[[Category:Scripting]]