From Kolmafia
Revision as of 01:44, 29 November 2010 by imported>Heeheehee (Fixed misspelling of "function".)
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

About Zarqon's Useful Function Library

Behold, a single function library containing most of zarqon's most useful functions, which will be used by most of his scripts. He grew tired of tweaking a function that was in multiple scripts and making sure he had changed them all. It would be nice, he thought in his customary italics, to have it in just one place.

In choosing which functions to include, he have tried to select only those functions which are a) super useful, or 2) needed by another of the included functions. It's a bit less efficient in terms of individual scripts, but in terms of repeated code across a family of scripts it is far simpler.



string excise(string source ,string start ,string end )

  • The original source string
  • start after this string
  • end before this string

This function returns a portion of the source string, from after the first occurrence of start to just before the first occurrence of end. If either start or end are missing, it will return an empty string. You can also supply either start or end as blank strings to specify the actual start or end of the source string.


string normalized(string mixvar ,string type )

  • mixvar is the string to normalize
  • type is the datatype to normalize to

Returns mixvar, normalized to the specified mafia type, which can be any primitive type or ASH datatype constant. For example, normalized("badger", "familiar") would return "Astral Badger".


string rnum(int n )

string rnum(float n )

string rnum(float n ,int place )

  • n is a number
  • place is the number of decimal places to round to

Returns your number n as a human-readable string. For ints, this means it adds commas where appropriate. For floats, it also rounds to the nearest place after the decimal. Default 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().


void set_avg(float to_add ,string which_prop )

  • to_add is the data point to add
  • 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 script three times with the values 2, 4, and 6 for to_add would result in the property 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.


float get_avg(string which_prop )

  • which_prop is the property to access

Returns an average value set by set_avg().


vfloat eval(string expression ,float [string]  values )

  • expression is the base expression
  • values is a map of values to replace

By Jason Harper. Evaluates expression as a math expression, and allows you to substitute values for variables, as described in much greater detail here. A brief version of this documentation is also included in ZLib. (NB: This section needs more infoz.)

boolean vprint(string message, string color, int level) boolean vprint(string message, int level) Wrapper for print() and abort(), prints message depending on vars["verbosity"] setting. It has a boolean return value so it can replace { print(message); return t/f; } if level == 0: abort with message if level > 0: prints message if verbosity >= level, returns true if level < 0: prints message if verbosity >= abs(level), returns false More detailed explanation here.

boolean vprint_html(string message, int level) Same as above, but wraps print_html().

int abs(int n) float abs(float n) Returns the absolute value of n.

float minmax(float a, float min, float max) Returns a, but no less than min and no more than max.

string check_version(string soft, string prop, string thisver, int thread)

Server-friendly once-daily version-checking. (Also hyphen-friendly.) If the user hasn't checked yet today, visits the specified thread in this forum to find the current version of your script. The thread must include "soft version" for the version info to be successfully parsed. Optionally, you may include "[requires revision XXXX]" in the post if you want to indicate a required minimum revision of mafia. If a new version is available, alerts the user in large text and provides an update link, then waits for a sufficiently annoying interval in case the user wishes to abort operation to go update the script. The return value is a blank string unless an update is found, in which case it is a

containing the update message. This allows this function to work equally well for relay scripts. The current version is stored to a daily property, standardized to "_version_"+prop. Example:


check_version("Hardcore Checklist","checklist","1.2.7",1045);

boolean load_current_map(string fname, aggregate dest) Allows scripts to automatically update data files. Loads a map named fname.txt, either from disk or from the Map Manager if an update is available. (Yes, this means you shouldn't include ".txt" in the parameter.) The first time you try to load a given map on a given day, it checks if your version is current. If so, it merely loads it from disk. If not, it overwrites your local map with the map stored on the Map Manager.

int setvar(string varname, mixed dfault) Allows you to define a per-character script setting to be used across all scripts that use ZLib. The first time the script is run, the variable will be set to dfault. To reference this setting, use vars[varname] in any script that includes ZLib, keeping in mind that this will always be a string. Detailed information posted here.

int have_item(string tolookup) 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.

float has_goal(item whatsit) Returns the chance that an item is or results in a goal. If is_goal(item) == true or it's a bounty item, returns 1.0. Otherwise, returns the chance that you would get a goal from using the item. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58. Many thanks to aqualectrix for creating and sharing the container items results map.

float has_goal(monster m) Making use of the above function, returns the percent chance that encountering a 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.

float has_goal(location l) 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.

boolean obtain(int n, string cond, location locale) Attempts to get n (-existing) of cond, either by purchasing (if you have the mafia preference set), pulling from Hangk's, or adventuring at locale. It also works with choiceadvs.

boolean use_upto(int n, item doodad, boolean purchase) Gets (if purchase is true) and uses n doodads if possible. Otherwise, uses as many as you have up to n.

boolean resist(element req, boolean reallydoit) Returns whether you are able to resist a given element, or if reallydoit is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot), and returns its success.

int my_defstat() Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

int get_safemox(location wear) Using mafia's location/monster data, returns the safe moxie of a given zone.

boolean auto_mcd(int safemox) boolean auto_mcd(monster mob) boolean auto_mcd(location place) If your automcd setting is true, automatically adjusts your mind-control device for maximum stat gains based on safemox (or the safe moxie for place or mob) and your threshold setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats.

familiar best_fam(string ftype) Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your 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).

boolean send_gift(string to, string message, int meat, int[item] goodies, string insidenote) boolean send_gift(string to, string message, int meat, int[item] goodies) Self-explanatory, really. Sends a gift to a player, able to split large amounts of items, useful return value.

boolean kmail(string to, string message, int meat, int[item] goodies, string insidenote) boolean kmail(string to, string message, int meat, int[item] goodies) boolean kmail(string to, string message, int meat) Sends a kmail to a player, returning true if the kmail is successfully sent. Handles splitting the message into multiple messages if the number of item types is too large. Returns the result of send_gift() if the intended recipient is unable to receive the message due to being in HC or somesuch. Note that you can also specify the message to be used inside gifts in that case. Use "\n" to specify a new line in the message.

Making use of Zlib

To include this library in your script, simply add the following towards the top of your script:

import "zlib.ash";

Then all these functions will be available in your script. Have fun!

More Information

See the thread for ZLib on the mafia forum here.