Kolmafia - User contributions [en]

Help:To Do List

2011-12-03T09:39:35Z

Jasonharper: /* Missing Stuff */

{{TOCright}}

== "To Do" List ==

This is a list of stuff that is missing from the wiki or else needs major work. Please help!

If you need tips for editing the wiki, find that here: [[Help:Editing]].

*CLI Commands are usually only added to the [[CLI Reference]]. Only very complicated commands require their own page.

*ASH commands need to be listed on their category page as well as on the [[Ash Functions]] list.
**It is not necessary to always create a code sample, although it is preferred.
**If you don't add a code sample, please remember to add '''needscode=yes|''' to the page.

== Missing Stuff ==
r10025: Added "choice" CLI command, to resolve manual or unsupported choiceadventures
Added "choice" CLI command, to resolve manual or unsupported choice
adventures without having to visit the relay browser - which might be
inconvenient if you're already in the CLI, and don't need to see the full
adventure text to decide which option you want. With no parameter, "choice"
just lists the options. With a numeric parameter, it picks that option.
With any other parameter, it picks the first option containing that text (in
either the actual button text, or mafia's spoiler text).

r10033: a new command 'graygui' (or 'greygui' if you prefer that spelling)
has been added to the CLI, which will print out all the entry points for all
the stuff that still has a known open request sequence.

I would like to list all valid adventuring conditions somewhere: (Is this all of them?)
* {{pspan|X item}} will be fulfilled when you have X of item.
* {{pspan|+X item}} will be fulfilled when you have X more of the item than you previously possessed.
* {{pspan|X choiceadv}} will be fulfilled when you encounter X choice adventures.
* {{pspan|X autostop}} will be fulfilled when you encounter X autostop adventures.
* {{pspan|X pirate insult}} will be fulfilled when you have learned X pirate insults.
* {{pspan|X arena flyer ml}} will be fulfilled when you have flyered X ML worth of monsters.
* {{pspan|X any itemtype}} will be fulfilled when you have X items that all have a partial match to itemtype, such as {{pspan|8 any paper strip}} or {{pspan|14 any fish meat}}.
* {{pspan|level X}} will be fulfilled when your character is level X. This is useful for automated power leveling.
* {{pspan|X muscle}}, {{pspan|X mysticality}} and {{pspan|X moxie}} will be fulfilled when the specified stat is at X.
* Special conditions exist for several locations.
** {{pspan|outfit}} is only valid in the Cobb's Knob Harem, Cobb's Knob Treasury, Frat House, Hippy Camp, Pirate Cove, Itznotyerzitz Mine, and eXtreme Slope.
** {{pspan|castle map items}} is only valid in the Giant's Castle.

If you leave off the quantity X, then it is assumed to be 1.
Remainder of possible conditions:
* '''X meat'''
* '''X health/mana'''
* '''X% health/mana'''
* '''X anything but Y''' (opposite of '''any''')
* any/anything but can take multiple item names separated by | or /.
* '''outfit''' can be preceded by the name of certain outfits, or the location where one normally drops, to specify a non-default outfit. I'm not sure if there's any place where that's actually useful.
* '''castle map items''' is technically valid everywhere; it's only non-stupid in the Giant's Castle.
--[[User:Jasonharper|Jasonharper]] 04:39, 3 December 2011 (EST)

There's also a "location" command, which allows new zones to work like normal with the rest of mafia.

location 274 Lollipop Forest

Be careful, if you add the same location twice it can make a mess.
Luckily, locations added this way are not remembered, so you can quit and restart if you mess it up.

== Needs Major Work ==

[[Proxy Records]] is only slightly better than a placeholder.

In r10047, the adventure tab interface was altered. Fix SinginSally's guide on pages...

http://wiki.kolmafia.us/index.php?title=KoLmafia_Guide:_Attack_Script
http://wiki.kolmafia.us/index.php?title=KoLmafia_Guide:_Custom_Combat_Script
http://wiki.kolmafia.us/index.php?title=KoLmafia_Guide:_Goal-Oriented_Adventuring

== Needs Code Samples ==

There is a list of all pages that require code samples: [[:Category:Needs_Code_Sample|Category:Needs Code Sample]]

Information on how to create a code sample: [[Template:CodeSample]]

Miscellaneous ASH Features

2010-10-17T18:41:37Z

Jasonharper: /* Additional Script Uses */ negative remaining turns on a counterScript

{{TOCright}}
==Special Syntax Functions==

'''[[notify]]'''

Used to send a simple kmail to the script's author, letting them know you use their script.

'''[[import]]'''

Used to load an external script into your current one.

'''[[call]]'''

Enables the script writer to invoke a function whose name is known at runtime.

'''[[new]]'''

Constructor function used to populate a record.

==Comments==

Adding '''[[Comments]]''' to your code can make it much easier to maintain, and helps other users understand what's going on.

==Errors==

For help when things go wrong, please see the page on [[ASH Errors]].

==Additional Script Uses==

In addition to regular scripts, relay override scripts, and consult scripts, mafia has a few other hooks for adding event-driven scripts. These situations are listed below, along with the preference that you can set a script name to (in parentheses).

'''Between Battle (betweenBattleScript)'''
*Executed whenever mafia is about to enter a combat. That means before every adventure if auto-adventuring, or before using an item that could lead to combat such as black pudding or drum machine.
*Does not require any special main() declaration.
*Example: Zarqon's [http://kolmafia.us/showthread.php?t=1240 Best Between Battle]

'''Buy (buyScript)'''
*Will execute whenever mafia needs to determine if it is to purchase or create an item.
*Requires a special main declaration boolean main(item itm, int qty, int ingredientLevel, boolean defaultBuy). These values will be supplied by mafia when the script is automatically called. A return value of true will instruct mafia to purchase the item and false will cause it to create the item possibly leading to other buy/create decisions.
**''itm'' and ''qty'' specify the item under consideration.
**''ingredientLevel'' indicates what's already available:
***0 = none of the ingredients
***1 = some of them
***2 = enough to create at least one of the requested item
**defaultBuy indicates what KoLmafia would have done otherwise; returning this value is the safest thing your script could do. It will normally be true if ingredientLevel is 0, false if 2. The default at level 1 depends on the item, and is subject to change - normally, anything made with star charts, pixels, the Malus, or multi-use are bought, anything else is created.
*Example: Bale's [http://kolmafia.us/showthread.php?p=18313#post18313 potionBuy].

'''Chatbot (chatbotScript)'''
*Will execute whenever a private message is received
*Requires a special main declaration void main(string sender, string message)
**'sender' is the name of the player who sent the message
**'message' is the message that was sent

'''Counters (counterScript)'''
*Will execute whenever a counter will expire as a result of an intended use of adventures.
*Requires a special main declaration: boolean main(string name, int remain). These values will be supplied by mafia when the script is automatically called and the return value will determine whether mafia continues operation (true) or aborts (false).
**''name'' will be the name of the counter that is about to expire.
**''remain'' is the number of turns remaining before the counter expires. Remain will usually be 0, but may be higher if you are about to multi-create items, adventure underwater, or take a vacation. It may be negative if the counter was informational (one that doesn't abort adventuring), and it actually expired in the middle of an action that used multiple turns at once.
*Example: Bale's [http://kolmafia.us/showthread.php?t=2519 CounterChecker].

'''Login (loginScript)'''
:This script is immediately executed once your character is logged in. Requires no special main() declaration.

'''Logout (logoutScript)'''
:Same as the loginScript, but runs on logout. Note that an [[abort|abort()]] in the script won't stop a logout unless the logout was called in (specific ways, please list).

'''Planting (plantingScript)'''
*This script can be used to manage the mushroom fields, which are available when under a muscle zodiac sign. It runs after logging in, if you have a mushroom field. Main function takes no arguments. Generally should take into account current [[moon phase]] so that it can be started in the middle of a cycle.
*Example: [http://kolmafia.us/showthread.php?563-Modified-mushroom-script-to-produce-3rd-4th-gen-crop&p=7507&viewfull=1#post7507 Sandiman's mushroom planting script].

'''Post-Ascension (postAscensionScript)'''
:Executed at once when your character starts a new ascension. (Example: Bales's [http://kolmafia.us/showthread.php?t=2769 newLife])

'''Pre-Ascension (preAscensionScript)'''
:Executed right before entering Valhalla.

'''Recovery (recoveryScript)'''
*Executed whenever mafia would recover your HP / MP.
*Requires a special main() declaration: boolean main(string type, int amount). These values will be supplied when mafia automatically calls the script, and the return value will instruct mafia if it should attempt to use mafia's default healing after the script concludes.
**''type'' is either "HP" or "MP".
**''amount'' is the desired amount of restoration needed or 0 to use mafia's default recovery level and target.
*Example: Bale's [http://kolmafia.us/showthread.php?t=1780 Universal Recovery]

==A little CLI help==

Two CLI commands are of great use to ASH scripters:
* [[ashref]] allows one to get a list of ASH functions
* [[ash (CLI)|ash]] or [[ash (CLI)|ashq]] allows one to run ASH directly on the CLI.

==Useful forum threads==
[http://kolmafia.us/showthread.php?523-Did-you-know...-It-s-a-secret-feature.&p=2968&viewfull=1#post2968 This thread], started by holatuwol, is a tidy compilation of various undocumented features in KoLmafia.

[[Category:Scripting]]

User talk:PhilmASTErpLus

2010-07-27T05:49:33Z

Jasonharper: /* ASH For Beginners */ new section

"aggregate" and "map" are NOT synonyms. "aggregate" is an abstract type; the three concrete implementations of that type are maps, arrays, and plural typed constants (which require a separate implementation because they need to be immutable). --[[User:Jasonharper|Jasonharper]] 04:36, 22 June 2010 (UTC)
:Uh-huh. Sorry about that editing rampage, should I go and revert them? Or how about alternatives? --[[User:PhilmASTErpLus|PhilmASTErpLus]] 04:39, 22 June 2010 (UTC)

I was not aware of this either; we'll need to see where that means we need to make changes. --[[User:StDoodle|StDoodle (#1059825)]] 05:07, 22 June 2010 (UTC)

Regarding your recent user page update -- the ideal place to put such information, I think, is probably [[file_to_map]]. Also, there should probably be a little blurb on that page mentioning that you don't need those files in your data directory (they're built into the jars), but having them present will override the built-in mapfiles. --[[User:Heeheehee|Heeheehee]] 23:58, 1 July 2010 (UTC)

Browsing through the function pages, I found this: {{f|to_string}} (see the source for template details) --[[User:Heeheehee|Heeheehee]] 19:03, 4 July 2010 (UTC)

== [[ASH For Beginners]] ==

Your recent edit is completely wrong; I would have reverted it, except that the reason field wasn't big enough to explain just how it was wrong.

ALL values in ASH are passed and assigned in a completely uniform manner, regardless of type. That manner could either be referred to as "call by value" or "call by reference"; the two concepts aren't distinct here, since all ASH values are references to some object. No copying is ever done, except as part of an implicit type conversion.

You appear to be confusing the concepts of call type and mutability. There's no difference in how (for example) a map and an int value are passed; the observed differences in behavior are entirely due to the fact that there are ways to modify the contents of a map (with it still remaining the same map), yet no ways of modifying the value of an integer. The closest you can come is to produce a new integer value, and assign it to the same variable that formerly held the old value; it is the variable that is changing, not the value. --[[User:Jasonharper|Jasonharper]] 05:49, 27 July 2010 (UTC)

Talk:Control Structures

2010-06-22T16:26:22Z

Jasonharper:

Ok, old version no longer needed. A couple cleanup requests:
* add return
* change looping to flow control OR add a separate section for continue, break & return
* the above 3 should each have a lv3 heading
--[[User:StDoodle|StDoodle (#1059825)]] 18:57, 18 April 2010 (UTC)

Never mind; the stuff, I fixed it. --[[User:StDoodle|StDoodle (#1059825)]] 19:21, 18 April 2010 (UTC) (Though further info for break, continue & return might be nice).

I was not aware of that use of switch statements, thanks! --[[User:StDoodle|StDoodle (#1059825)]] 13:55, 3 May 2010 (UTC)

*That use of switch statements was one of the things zarqon and I pushed for when we were cajoling veracity to add it as a mafia feature. It is so much more readable to use a single switch statement than 6 "else if" statements. --[[User:Bale|Bale]] 23:33, 3 May 2010 (UTC)

Er, that is to say, I knew how to use them with a top-level variable, but not that you could omit that and use a sep. expression each time... and I could swear I tried to use expressions that way (apparently you can't do both at once!). :P --[[User:StDoodle|StDoodle (#1059825)]] 02:29, 4 May 2010 (UTC)

I'm wondering if a more explicit example is necessary. What I'm talking about is:

{{
CodeSample|
code=
<syntaxhighlight>
switch {
case x < 0 && x == x % 2:
print(x+" is negative and even");
break;
case x < 0:
print(x+" is negative and odd");
break;
case x == 0:
print("x is zero");
break;
case x == x % 2 && x < 10:
print(x+" is a positive one digit even number");
break;
case x != x % 2
print(x+" is an odd number");
break;
default:
print(x+" is greater than 9");
}
</syntaxhighlight>}}
Do you think an example like that would be helpful? --[[User:Bale|Bale]] 03:19, 4 May 2010 (UTC)

That looks good; I'd add in one line with a different variable though, just to make the differentiation in use clear. Such as an initial check for y > 9000 or something. Then again, I pretty much figured it out from what's on the page, so I'm not sure it's necessary. Perhaps three samples are in order: a simple switch with a generic variable to test, your example, and a "This won't work" example that tries to mix the two. --[[User:StDoodle|StDoodle (#1059825)]] 13:51, 4 May 2010 (UTC)

Regarding foreach and sorting: since it sorts by index, not by value, that should be mentioned somewhere in that blurb. --[[User:Heeheehee|Heeheehee]] 12:10, 22 June 2010 (UTC)
* foreach DOES NOT SORT - it uses whatever ordering is provided by the aggregate you're iterating over. For maps and arrays, the objects themselves maintain the keys in sorted order. For plural typed constants, the ordering is however the elements were originally listed, which is completely arbitrary (and can even include duplicate keys).

User talk:PhilmASTErpLus

2010-06-22T04:36:06Z

Jasonharper: Created page with '"aggregate" and "map" are NOT synonyms. "aggregate" is an abstract type; the three concrete implementations of that type are maps, arrays, and plural typed constants (which requ…'

Item drops array

2010-04-05T12:02:43Z

Jasonharper: return type

{{
#vardefine:name|item_drops_array}}{{
#vardefine:return_type|record [int]}}{{
#vardefine:aggregate|yes}}{{

FunctionPage|
name={{#var:name}}|
function_category=Item Management|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}
}}|
function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
parameter1={{Param|monster|m}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}
}}|

function_description=Returns an array of records with three fields:
<syntaxhighlight>
record {
item drop;
int rate;
string type;
}
</syntaxhighlight>

Since this is the first function to return a record, it cannot be stored to a variable, and thus the only way to access the data is by iterating over the elements in the array.|

code1={{CodeSample|
title=Code Samples|
description=Prints all information Mafia has regarding the item drops of a certain monster.|
code=
<syntaxhighlight>
void drops(monster mob){
print("Monster: " + mob);
foreach index, rec in item_drops_array(mob)
print("item: "+rec.drop+", drop rate: "+rec.rate+", type: "+rec.type);
}
</syntaxhighlight>
}}|

see_also={{SeeAlso|meat_drop|item_drops}}|
special=The zero-parameter form returns the last monster encountered (the current one, if used in combat).
}}

Disable

2010-03-25T08:36:32Z

Jasonharper: return values

{{
#vardefine:name|disable}}{{
#vardefine:return_type|void}}{{

FunctionPage|

name={{#var:name}}|
function_category=Miscellaneous|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|func}}|
p1desc={{pspan|func}} is the name of the function you wish to disable.
}}|

function_description=This function allows you to disable commands and/or functions by name. String {{pspan|func}} specifies the name of a CLI command or ASH function that you do not wish to be carried out. Note these include custom ASH functions (that you name yourself), but not aliases.

Mafia has an internal array of function names which are disabled. At the start of each session, this array starts empty. Disable adds names to this array and mafia will not allow functions to be called that are named after any on the disabled list (with the exception of disable and enable). This is useful for debugging scripts, as you can quickly disable functions from the top of a script without digging through the code. In addition, when a disabled function is called, mafia will print a line informing you of this fact, while not acting on it.

Important considerations:
#Mafia cannot differentiate between scripts that call functions of the same name. If function "foo" is disabled from script one, it will still be disabled when you run script two, unless you enable "foo" or restart mafia.
#Remember that CLI commands will be disabled if they have the same name (or can be disabled deliberately with this function).
#A disabled function still returns a value - the default value for its declared return type (false, 0, "", $item[none], an empty map, etc.). If a disabled function is incorporated into a condition (eg. "if(disabled_function())" ), then mafia will not just skip the entire conditional - execution will continue as normal, based on that default value.
#Using "all" as the string parameter will disable all ASH and CLI functions with the exception of enable and disable. Therefore, to re-enable all functions, you must type "enable all" into the CLI - ASH enable("all") would technically work, but at that point you'd have no way of invoking a script that contains it.
#disable() and enable() cannot be individually disabled using disable(), either.
 |

code1={{CodeSample|
title=Code Samples|
description=This mini scriptlet generates a map that is outputted to a data file. In testing you might not want to do this every time, so you can disable map_to_file().|
code=
<syntaxhighlight>
disable("map_to_file");
</syntaxhighlight>
}}|

see_also={{SeeAlso|enable}}|
}}

Visit url

2010-03-24T03:48:42Z

Jasonharper: 0-arg version and relay script details

{{
#vardefine:name|visit_url}}{{
#vardefine:return_type|buffer}}{{

FunctionPage|
name={{#var:name}}|
function_category=String Handling Routines|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|page}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|page}}|
parameter2={{Param|boolean|use_POST}}|
p1desc={{Pspan|page}} is the page to visit|
p2desc={{Pspan|use_POST}} is true for a POST request and false for a GET request|
}}|

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

function_description=Returns the HTML from the visited page (not just what is displayed when visiting the page, but all markup) by performing a POST request if {{pspan|use_POST}} is omitted or true, or a GET request if false. Note that for addresses inside of KoL, it is only necessary to supply the page name for {{pspan|page}}, and KoLmafia will populate the rest of the url. However, pages outside of KoL require the full url to be supplied for {{pspan|page}}.

The version with no parameters is only meaningful in a relay override script; it retrieves the server page that your script is overriding. All three versions behave slightly differently in a relay script; they retrieve a version of the page with any KoLmafia decorations added, rather than the raw page from the server.|

improvecode=yes|

code1={{CodeSample|
title=Code Samples|
description=Visits your private character sheet.|
code=
<syntaxhighlight>
visit_url( "charsheet.php" );
</syntaxhighlight>}}|

code2={{CodeSample|
description=Visits google.|
code=
<syntaxhighlight>
visit_url( "http://www.google.com/");
</syntaxhighlight>}}|

code3={{CodeSample|
description=Given a player ID, parse a player's profile for his name.|
code=
<syntaxhighlight>
string getPlayerName( int playerID ) {
string playerName;

// use visit_url() to store the player profile's HTML in a string
string playerProfile = visit_url("/showplayer.php?who=" + playerID);
if ( contains_text(playerProfile, "<td>Sorry, this player could not be found.</td>") ) {
print("Player " + playerID + "does not exist.","red");
return "";
}
// find player name in the string returned by visit_url()
matcher match_name = create_matcher( "([^<]+) \$#" + playerID + "\$ ", playerProfile );
if ( match_name.find() ) {
playerName = match_name.group(1);
}
else {
print("Problem occured while parsing for player name","red");
return "";
}

return playerName;
}
</syntaxhighlight>}}|

special=Note that this function returns an empty string if the page does not exist or if the request times-out.
}}

Modifiers

2010-03-19T04:50:40Z

Jasonharper: Modified!

{{TOCright}}
Here is a comprehensive list of modifiers calculated by KoLMafia. Note that these are also available as ASH functions -- the first form, which takes one parameter, information about your character's current state; the second form, which takes two parameters, information about the [string|item|effect|skill|familiar] in question.

To view this list of modifiers as it pertains to your character, use the CLI command "modref".

A list of the functions used to access these modifiers can be found at [[Modifier Functions]].

==Numeric Modifiers==
Note that although some of these functions have an ASH derivative that may be easier to use, the two-parameter form is still relevant and rather useful when obtaining information about a particular [string|item|effect|skill|familiar], rather than your current state.

When not logged in, these all return 0 for the 1-parameter form of [[numeric_modifier|numeric_modifier()]].
{| class="wikitable" border="1"
|-
! Modifier Name
! Related ASH function / Notes
|-
| Familiar Weight
| [[weight_adjustment| weight_adjustment()]]
|-
| Monster Level
| [[monster_level_adjustment| monster_level_adjustment()]]
|-
| Combat Rate
| [[combat_rate_modifier| combat_rate_modifier()]]
|-
| Initiative
| [[initiative_modifier| initiative_modifier()]]
|-
| Experience
| [[experience_bonus| experience_bonus()]]
|-
| Item Drop
| [[item_drop_modifier| item_drop_modifier()]]
|-
| Meat Drop
| [[meat_drop_modifier| meat_drop_modifier()]]
|-
| Damage Absorption
| [[raw_damage_absorption| raw_damage_absorption()]]
|-
| Damage Reduction
| [[damage_reduction|damage_reduction()]]
|-
| Cold Resistance
| Similar to [[elemental_resistance|elemental_resistance( $element[cold] )]], but returns the level of resistance.
|-
| Hot Resistance
| Similar to [[elemental_resistance|elemental_resistance( $element[hot] )]], but returns the level of resistance.
|-
| Sleaze Resistance
| Similar to [[elemental_resistance|elemental_resistance( $element[sleaze] )]], but returns the level of resistance.
|-
| Spooky Resistance
| Similar to [[elemental_resistance|elemental_resistance( $element[spooky] )]], but returns the level of resistance.
|-
| Stench Resistance
| Similar to [[elemental_resistance|elemental_resistance( $element[stench] )]], but returns the level of resistance.
|-
| Mana Cost
| Similar to [[mana_cost_modifier|mana_cost_modifier()]] -- only counts up to the -3 cap.
|-
| Moxie
| Sum of all absolute moxie modifiers.
|-
| Moxie Percent
| Sum of all percentage-based moxie modifiers.
|-
| Muscle
| Sum of all absolute muscle modifiers.
|-
| Muscle Percent
| Sum of all percentage-based muscle modifiers.
|-
| Mysticality
| Sum of all absolute mysticality modifiers.
|-
| Mysticality Percent
| Sum of all percentage-based mysticality modifiers.
|-
| Maximum HP
| Sum of all absolute HP modifiers.
|-
| Maximum HP Percent
| Sum of all percentage-based HP modifiers.
|-
| Maximum MP
| Sum of all absolute MP modifiers.
|-
| Maximum MP Percent
| Sum of all percentage-based MP modifiers.
|-
| Weapon Damage
| Sum of all absolute weapon damage modifiers.
|-
| Ranged Damage
| Sum of all absolute ranged damage modifiers.
|-
| Spell Damage
| Sum of all absolute spell damage modifiers.
|-
| Spell Damage Percent
| Sum of all percentage-based spell damage modifiers.
|-
| Cold Damage
| Total cold damage.
|-
| Hot Damage
| Total hot damage.
|-
| Sleaze Damage
| Total sleaze damage.
|-
| Spooky Damage
| Total spooky damage.
|-
| Stench Damage
| Total stench damage.
|-
| Cold Spell Damage
| Total cold spell damage.
|-
| Hot Spell Damage
| Total hot spell damage.
|-
| Sleaze Spell Damage
| Total sleaze spell damage.
|-
| Spooky Spell Damage
| Total spooky spell damage.
|-
| Stench Spell Damage
| Total stench spell damage.
|-
| Critical
| Critical multiplier.
|-
| Fumble
| Fumble multiplier.
|-
| HP Regen Min
| Lower bound of all HP-regenerating effects/equipment.
|-
| HP Regen Max
| Upper bound of all HP-regenerating effects/equipment.
|-
| MP Regen Min
| Lower bound of all MP-regenerating effects/equipment.
|-
| MP Regen Max
| Upper bound of all MP-regenerating effects/equipment.
|-
| Adventures
| Bonus Rollover adventures
|-
| Familiar Weight Percent
| Percentage modifier of Familiar Weight (from Bad Moon effects; always <= 0)
|-
| Weapon Damage Percent
| Sum of all percentage-based weapon damage modifiers.
|-
| Ranged Damage Percent
| Sum of all percentage-based ranged damage modifiers.
|-
| Stackable Mana Cost
| Similar to [[mana_cost_modifier|mana_cost_modifier()]] -- all other MP cost modifiers.
|-
| Hobo Power
| Hobo Power from equipment and effects (effect, technically).
|-
| Base Resting HP
| Average HP gained from resting.
|-
| Resting HP Percent
| Percentage modifier to HP gained from resting (e.g. from Pagoda).
|-
| Bonus Resting HP
| Absolute modifier to HP gained from resting (e.g. from Gauze hammock).
|-
| Base Resting MP
| MP gained from resting.
|-
| Resting MP Percent
| Percentage modifier to HP gained from resting (e.g. Pagoda).
|-
| Bonus Resting MP
| Absolute modifier to HP gained from resting (e.g. from Beanbag chair).
|-
| Critical Hit Percent
| Percentage modifiers to critical hits (e.g. Depleted Grimacite Kneecapping stick).
|-
| PvP Fights
| Bonus PvP fights upon Rollover.
|-
| Volleyball
| Only for use with multiple parameters (e.g. Llama returns .5, metallic foil radar dish returns -1).
|-
| Sombrero
| Only for use with multiple parameters (e.g. Baby Sandworm returns 1, metallic foil radar dish returns 1).
|-
| Leprechaun
| Only for use with multiple parameters (e.g. Hobo monkey returns 1.25).
|-
| Fairy
| Only for use with multiple parameters (e.g. Hound dog returns 1.25).
|-
| Meat Drop Penalty
| Penalty to Meat Drops; result of having an Underwater location selected as your current location.
|-
| Hidden Familiar Weight
| Bonus familiar weight that does not show up on the character pane (e.g. from Temporary Teardrop Tattoo).
|-
| Item Drop Penalty
| Penalty to Item Drops; result of having an Underwater location selected as your current location.
|-
| Initiative Penalty
| Penalty to Initiative Drops; result of having an Underwater location selected as your current location.
|-
| Food Drop
| Exclusive bonus to food drops (e.g. Brother Flying Burrito's Blessing).
|-
| Booze Drop
| Exclusive bonus to food drops (e.g. Brother Smother's Blessing).
|-
| Hat Drop
| Exclusive bonus to hat drops (e.g. velcro broadsword).
|-
| Weapon Drop
| Exclusive bonus to weapon drops (e.g. velcro broadsword).
|-
| Offhand Drop
| Exclusive bonus to offhand drops (None at the moment; placeholder).
|-
| Shirt Drop
| Exclusive bonus to shirt drops (None at the moment; placeholder).
|-
| Pants Drop
| Exclusive bonus to weapon drops (e.g. Baneful Bandolier).
|-
| Accessory Drop
| Exclusive bonus to weapon drops (e.g. velcro paddle ball).
|-
| Volleyball Effectiveness
| Exclusive to the Baby Mutant Rattlesnake; evaluates an expression that factors in the current moon phase.
|-
| Sombrero Effectiveness
| None.
|-
| Leprechaun Effectiveness
| Exclusive to the Mutant Cactus Bud; evaluates an expression that factors in the current moon phase.
|-
| Fairy Effectiveness
| Exclusive to the Mutant Fire Ant; evaluates an expression that factors in the current moon phase.
|-
| Familiar Weight Cap
| (?) Maximum base weight for the current familiar.
|-
| Slime Resistance
| Similar to [[elemental_resistance|elemental_resistance( $element[slime] )]], but returns the level of resistance.
|-
| Slime Hates It
| Number of Slime Hates It active, as taken from equipment and effects.
|-
| Maximum HP Nonmultiplied
| Bonus to HP from Slimy Sinews since it is not affected by HP multipliers.
|-
| Maximum MP Nonmultiplied
| Bonus to MP from Slimy Synapses since it is not affected by MP multipliers.
|-
| Spell Critical Percent
| Increased absolute spell critical rate.
|-
| Muscle Experience
| +X Mus substats/fight
|-
| Mysticality Experience
| +X Mys substats/fight
|-
| Moxie Experience
| +X Mox substats/fight
|-
| Effect Duration
| For use with the two-parameter form, using item as the other parameter. Returns duration of effect for potions.
|}

==Derived Modifiers==
These are modifiers that are calculated based on other modifier values, rather than being a property of individual items. They can be used just like the numeric modifier names above, but are fairly useless with the one-parameter form of the function since you can easily retrieve the actual values (which may differ slightly from these predicted values, due to different rounding behavior or other errors in KoLmafia's modifier calculations). The intended usage is in the form numeric_modifier("_spec", ''name''), to determine the results of a potential equipment or effect change that has been tested by the CLI '''whatif''' command.
{| class="wikitable" border="1"
|-
! Modifier Name
! Related ASH function / Notes
|-
| Buffed Muscle
| Predicted value of [[my_buffedstat|my_buffedstat($stat[muscle])]]
|-
| Buffed Mysticality
| Predicted value of [[my_buffedstat|my_buffedstat($stat[mysticality])]]
|-
| Buffed Moxie
| Predicted value of [[my_buffedstat|my_buffedstat($stat[moxie])]]
|-
| Buffed HP Maximum
| Predicted value of [[my_maxhp|my_maxhp()]]
|-
| Buffed MP Maximum
| Predicted value of [[my_maxmp|my_maxmp()]]
|}

==Bitmap Modifiers==
Note: This does not have a corresponding ASH function. Instead, they can all be called using the [[numeric_modifier|numeric_modifier()]] function.
When not logged in, these all return 0x0 (0).
{| class="wikitable" border="1"
|-
! Modifier Name
! Notes
|-
| Clownosity
| If this is >= 4, you can "Push the nose" in the Fun House.
|-
| Brimstone
| These have many "bonuses" when you equip more of them at once.
|-
| Synergetic
| For items that have hidden bonuses when used together, such as the Secrets from the Future and the snake/wolf sword & shield.
|}

==Boolean Modifiers==
When not logged in, these all return false for the 1-parameter form of [[boolean_modifier|boolean_modifier()]].
{| class="wikitable" border="1"
|-
! Modifier Name
! Notes
|-
| Softcore Only
| For use with the parameter "item"; returns true if the item in question has the Softcore Only flag (e.g. Travoltan Trousers).
|-
| Single Equip
| For use with the parameter "item"; returns true if the item in question has the Single Equip flag (e.g. plexiglass pendant).
|-
| Never Fumble
| Returns true if the player has an effect that prevents fumbling.
|-
| Weakens Monster
| For use with the parameter "item"; returns true if the item in question delevels on hit (e.g. 7-foot dwarven mattock).
|-
| Free Pull
| For use with the parameter "item"; returns true if the item in question can be pulled from Hagnk's for free (e.g. roll of toilet paper).
|-
| Variable
| For use with the parameter "item"; returns true if the item in question has a variable effect (e.g. depleted grimacite grappling hook).
|-
| Nonstackable Watch
| For use with the parameter "item"; returns true if the item in question counts as one of the nonstackable watches (e.g. dead guy's watch).
|-
| Cold Immunity
| Returns true if Coldform is active.
|-
| Hot Immunity
| Returns true if Hotform is active.
|-
| Sleaze Immunity
| Returns true if Sleazeform is active.
|-
| Spooky Immunity
| Returns true if Spookyform is active.
|-
| Stench Immunity
| Returns true if Stenchform is active.
|-
| Cold Vulnerability
| Returns true if the player is vulnerable to Cold (e.g. from Sleazeform).
|-
| Hot Vulnerability
| Returns true if the player is vulnerable to Hot (e.g. from Spookyform).
|-
| Sleaze Vulnerability
| Returns true if the player is vulnerable to Sleaze (e.g. from Stenchform).
|-
| Spooky Vulnerability
| Returns true if the player is vulnerable to Spooky (e.g. from Coldform).
|-
| Stench Vulnerability
| Returns true if the player is vulnerable to Stench (e.g. from Hotform).
|-
| Moxie Controls MP
| Returns true if the player has a moxie magnet equipped.
|-
| Moxie May Control MP
| Returns true if the player has Travoltan Trousers equipped (but not the moxie magnet?).
|-
| Four Songs
| Returns true if the player is able to "Keep 4 songs in [his] head instead of 3" (e.g. Brimstone Beret).
|-
| Additional Song
| Returns true if the player has the bonus from the El Hebilla del Cinturón de Lopez (Accordion Thief Epic Accessory).
|-
| Adventure Underwater
| Returns true if the player has some way to breathe underwater (e.g. makeshift SCUBA gear).
|-
| Underwater Familiar
| Returns true if the player's familiar has some way to breathe underwater (e.g. das boot).
|}

==String Modifiers==
Note: These all appear in the two-parameter form.
{| class="wikitable" border="1"
|-
! Modifier Name
! Notes
|-
| Class
| Returns the class you must be to benefit from any of the enchantments on this item.
|-
| Intrinsic Effect
| Returns the intrinsic effect granted by a piece of equipment (e.g. Chapped Legs from leather chaps).
|-
| Equalize
| Returns the base stat of an equalizer potion.
|-
| Wiki Name
| Returns an empty string unless it is different, in which case the special HTML entities have been replaced. (e.g. frigid hankyu)
|-
| Modifiers
| Returns the raw text of this item's modifier data, useful for a quick view of all its enchantments.
|-
| Outfit
| Returns the name of the outfit (non-custom, folks!) that this item is part of.
|-
| Stat Tuning
| (Crimbo '06 items, like tropical paperweight?)
|-
| Familiar Tuning
| Bandersnatch fold-able equipment.
|-
| Effect
| Returns the effect that KoL associates with a potion (which may not be the potion's only effect).
|}

{{RFI|Can someone check to make sure that I didn't screw up?|Also, fill in the missing data?}}

Append tail

2010-03-12T19:09:56Z

Jasonharper: Redirected; this function is neither explainable nor usable on its own

#REDIRECT [[Append_replacement]]

Append replacement

2010-03-12T19:08:04Z

Jasonharper: Explainified!

{{
#vardefine:name|append_replacement(), append_tail}}{{
#vardefine:return_type|buffer}}{{

FunctionPage|
name={{#var:name}}|
function_category=String Handling Routines|

function1={{Function|
name=append_replacement|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|matcher|match}}|
parameter2={{Param|buffer|buff}}|
parameter3={{Param|string|replace}}|
}}|
function2={{Function|
name=append_tail|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|matcher|match}}|
parameter2={{Param|buffer|buff}}|
p1desc={{Pspan|match}} is a matcher created with the original string and search pattern|
p2desc={{Pspan|buff}} is the buffer in which the modified string is being accumulated|
p3desc={{Pspan|replace}} is the replacement text for the current match of the search pattern, with the same meanings for special characters as in [[replace_all|replace_all()]]|
}}|

function_description=These two functions are the building blocks for a regular expression-based search and replace operation. Most of the time, you can use the more straightforward [[replace_string|replace_string()]] or [[replace_all|replace_all()]] functions instead; the only time you actually need to use these functions is when the replacement text has to be generated in some special way, rather than being a constant.

To use these functions, you must have a matcher variable which has been created with the desired search pattern and original text, and a buffer variable in which the modified string will be built. append_replacement() (which is only valid immediately after [[find|find()]] has returned true for {{Pspan|match}}) will copy text into the buffer starting after the previous match (or the start of the original string) through the start of the current match, and will then append the {{Pspan|replace}} string. append_tail() (which is normally called only once, after find() returns false) will copy any remaining text into the buffer, after the final match. Both functions return {{Pspan|buff}}, for convenience.|

code1={{CodeSample|
title=Code Samples|
description=This sample will replace every 4-letter word in the input string with its uppercase version.|
code=
<syntaxhighlight>
string cap4(string input)
{
buffer b;
matcher m = create_matcher("\\b\\w{4}\\b", input);
while (m.find()) {
m.append_replacement(b, m.group().to_upper_case());
}
m.append_tail(b);
return b.to_string();
}

print(cap4("did this script work right?"));
// Output will be: did THIS script WORK right?
</syntaxhighlight>
}}|

see_also={{SeeAlso|create_matcher}}|
}}

Talk:My primestat

2010-03-12T04:55:01Z

Jasonharper: GIGO

Re the special info: This does not make sense to me. It does return $stat[moxie], but I can't really justify this -- $stat[moxie].to_int() is 3, not 0. It'd be helpful if someone could explain -why- this happens. --[[User:Heeheehee|Heeheehee]] 04:35, 12 March 2010 (UTC)
* What's there to explain? The not-logged-in value of functions that are only meaningful when logged in is pure garbage. There was no effort expended towards having them return a particular value; any value that doesn't immediately cause a crash is good enough. There is no guarantee that the garbage value will be consistent between versions of the program, or even successive calls to the function.

File to map

2010-03-11T04:43:43Z

Jasonharper: What is "has not been initialized" supposed to mean?

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

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

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|file_to_load}}|
parameter2={{Param|aggregate|map_to_fill}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|file_to_load}}|
parameter2={{Param|aggregate|map_to_fill}}|
parameter3={{Param|boolean|compact}}|
p1desc={{Pspan|file_to_load}} is the filename to load from|
p2desc={{Pspan|map_to_fill}} is the map to populate with data|
p3desc={{Pspan|compact}} is an (optional) flag; if omitted or true, records that do not contain any aggregate values are expected to be written on a single line, rather that one line per field.|
}}|

function_description=Loads data to the {{pspan|map_to_fill}} from a saved {{pspan|file_to_load}} in your KoLmafia "data" or "scripts" directory. The {{pspan|compact}} parameter is not needed unless you specified it in the [[map_to_file|map_to_file()]] call that originally generated the file, in which case the values must match. This function returns the operation's success. If {{pspan|map_to_fill}} has not been initialized, this function will abort (as oppossed to returning false).|

code1={{CodeSample|
title=Code Sample|
description=This sample loads a simple map that includes item names keyed by a number.|
code=
<syntaxhighlight>
string [int] my_list;
file_to_map( "SavedList.txt" , my_list);
for i from 0 to (count(my_list) - 1) {
print( "At index: " + i + " We find: " + my_list[i] );
}
</syntaxhighlight>|
moreinfo=
If the file "SavedList.txt" had the following:
<pre>
0 StDoodle
1 Grotfang
</pre>
Then the results would be:
<pre>
At index: 0 We find: StDoodle
At index: 1 We find: Grotfang
</pre>
}}|

see_also={{SeeAlso|map_to_file|}}|
}}

Map to file

2010-03-11T04:30:39Z

Jasonharper: Where did you come up with this stuff?

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

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

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|aggregate|map_to_save}}|
parameter2={{Param|string|file_to_save}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|aggregate|map_to_save}}|
parameter2={{Param|string|file_to_save}}|
parameter3={{Param|boolean|compact}}|
p1desc={{Pspan|map_to_save}} is the map to save data from|
p2desc={{Pspan|file_to_save}} is the filename to save to|
p3desc={{Pspan|compact}} is an (optional) flag; if omitted or true, record values are written on a single line of the file when possible, rather than one field per line|
}}|

function_description=Saves the data in the {{pspan|map_to_save}} to the {{pspan|file_to_save}} in your KoLmafia "data" directory. The {{pspan|compact}} parameter exists only for backwards compatibility; there is no need to use it in new code (but if you do use it, you must pass the same value to [[file_to_map|file_to_map()]] to successfully read any records within your map). This function returns the operation's success. If {{pspan|file_to_save}} already exists, this function will override (not append) the file's contents with the new data. It's also worth noting that, once saved, the data in {{pspan|file_to_save}} is not tied to any particular map; it can be loaded into another map or slice, as long as the datatypes are compatible.
As this & [[file_to_map|file_to_map()]] are KoLmafia's only I/O functions, they are invaluable for an ASH scripter wishing to save any script settings or information too complex to easily fit in a user preference. However, caution should be used, as a single failed operation of this function could result in the loss of all such data. For anything difficult to re-create, or too important to lose, the script author should be careful to save backups and check for function success during such operations.|

code1={{CodeSample|
title=Code Sample|
description=This sample saves a simple map of a user's responses to questions.|
code=
<syntaxhighlight>
boolean [string] answers;
answers["Chocolate"] = user_confirm( "Do you like chocolate?" );
answers["CuteKittens"] = user_confirm( "Do you like cute kittens?" );
answers["ThisGame"] = user_confirm( "Do you like KoL?" );
if (map_to_file( answers , "WhatYouLike.txt" ))
print( "Your answers were saved successfully." );
else
print( "There was a problem saving your answers." );
</syntaxhighlight>|
moreinfo=
If the user answered No, Yes, Yes to the questions, they should now have a file that contains:
<pre>
Chocolate false
CuteKittens true
ThisGame true
</pre>
}}|

see_also={{SeeAlso|file_to_map}}|
}}

Datatype Conversions

2010-03-09T00:07:31Z

Jasonharper: +historical note

== Part 10 - Datatype Conversions ==

These functions will convert 1 type of data to another.

boolean to_boolean( variable ) 
Converts the ASH-based object into boolean. 
Accepts: string, int

class to_class( variable ) 
Converts the ASH-based object into a class. 
Accepts: string


effect to_effect( variable ) 
Converts the ASH-based object into an effect. 
Accepts: string, int, skill


familiar to_familiar( variable ) 
Converts the ASH-based object into a familiar. 
Accepts: string, int


float to_float( variable ) 
Converts the ASH-based object into a float. 
Accepts: string, int, item, location, familiar, skill, effect, slot, element, monster, boolean, class, stat

int to_int( variable ) 
Converts the ASH-based object into the number that will be recognized by the KoL server. Needed when you’re building raw URLs from time to time. 
accepts: string, float, item, location, familiar, skill, effect, slot, element, monster, boolean, class, stat

item to_item( variable ) 
Converts the ASH-based object into an item. 
Accepts: string, int


location to_location( variable ) 
Converts the ASH-based object into a location. 
Accepts: string


monster to_monster( variable ) 
Converts the ASH-based object into a monster. 
Accepts: string


string to_plural( variable ) 
Converts the ASH-based object into a string of its plural. 
Accepts: item


skill to_skill( variable ) 
Converts the ASH-based object into a skill. 
Accepts: string, int, effect


slot to_slot( variable ) 
Converts the ASH-based object into a slot. 
Accepts: item


string to_string( variable ) 
Converts in-game variables to printable counterparts. The print command will cast non-string values properly now, but these are still useful for building URLs and setting properties. 
accepts: boolean, int, float, item, location, familiar, class, stat, skill, effect, slot, element, monster

== Historical note ==
ASH did not originally support polymorphic functions, so it was not possible to have (for example) a single '''to_string(any)''' function that worked on any datatype. Instead, there were separate '''int_to_string(int)''', '''item_to_string(item)''', etc. functions. You may see these used in older scripts, and in fact they still work. The rule is that if a function name is not otherwise defined anywhere, and it ends with one of the modern type conversion function names shown above, it is treated as a call to the modern function. No check is made to verify that the chopped-off portion of the old function name actually matches the type of its parameter.

Talk:Have outfit

2010-03-07T19:19:32Z

Jasonharper:

I know for a fact that exactly 0 outfits have chefstaves in them. Will check for torso in a bit on one of my alts without Torso permed. --[[User:Heeheehee|Heeheehee]] 17:52, 7 March 2010 (UTC)

As I believe was discussed in IRC, this function supposedly can check for custom outfits. If it really can't, and that's intentional, then yeah, the chefstaff part isn't an issue (at least currently). --[[User:StDoodle|StDoodle]] 19:10, 7 March 2010 (UTC)

Pro tip: anything that implies that mafia has any knowledge about the components of a custom outfit is a lie. --[[User:Jasonharper|Jasonharper]] 19:19, 7 March 2010 (UTC)

Have outfit

2010-03-07T19:17:54Z

Jasonharper: no custom outfits

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

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

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|name}}|
p1desc={{Pspan|name}} is an outfit to check for|
}}|

function_description=This function returns true if you have all parts of the outfit {{Pspan|name}} and meet all of the stat requirements to equip it. Only in-game outfits are currently supported, not custom outfits.|

needscode=yes|

see_also={{SeeAlso|outfit}}|
cli_equiv=The CLI command command "outfit" with the parameter "list" gives information on the in-game outfits you have available (but does not list custom outfits or check for whether the outfit can be equipped).|
}}
{{RFI|Does this function check for misc. requirements such as torso & chefstaff wielding ability?|The custom outfit part was already listed; but how? (It doesn't work for me, is a specific prefix required? What?)}}

Group string

2010-03-05T16:41:08Z

Jasonharper:

{{#vardefine:name|group_string}}
{{#vardefine:return_type|string [int, int]}}
{{#vardefine:aggregate|yes}}

{{FunctionPage|
name={{#var:name}}|
function_category=String Handling Routines|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|group_me}}|
parameter2={{Param|string|group_by}}|
p1desc={{Pspan|group_me}} is the string to split into groups|
p2desc={{Pspan|group_by}} is the regular expression to group by|
}}|

function_description=This function finds all (non-overlapping) matches of the regular expression {{pspan|group_by}} within the string {{pspan|group_me}}. A 2-dimensional array of matching strings is returned. The first index is the number of the match, starting with 0 for the first match. The second index is the number of the group within each match, with exactly the same meaning as the 2nd parameter to [[group|group()]]: element 0 is the entire text matched by the regular expression, element 1 is the text matched by the first set of grouping parentheses within the expression, element 2 is the second set of grouping parentheses, and so on.|

needscode=yes|

more_info= See [http://kolmafia.us/showthread.php?t=318 this thread] for details.|
}}

{{RFI|The regex isn't too hard to parse, but the results are.|For results, I always see [int,0] and [int,1] keys; huh?}}

Retrieve item

2010-03-05T16:18:14Z

Jasonharper: order of operations

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

{{FunctionPage|
name={{#var:name}}|
function_category=Item Management|
second_category=Adventuring|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|int|qty}}|
parameter2={{Param|item|get}}|
p1desc={{Pspan|qty}} is the quantity to acquire|
p2desc={{Pspan|get}} is the item to acquire|
}}|

function_description=Uses KoLmafia's internal logic to gather the items in the least destructive manner. Returns true if items are acquired as specified and false if not.|

needscode=yes|

see_also={{SeeAlso|buy}}|
cli_equiv=The CLI command "acquire" works similarly.|
special=Unlike a few other ASH commands, retrieve_item() will still return false on attempts to acquire items that are not possible to get (such as a sparkly engagement ring).
}}
<h2>Order of operations</h2>
This is the current order in which retrieval options are tried, as of about r8200. Note that this is an extremely condensed summary of several hundred lines of internal code, and that the details are subject to change
* items already in inventory
* items currently equipped
* items equipped on a non-current familiar
* retrieval of worthless items by using 31337 scrolls or sewering
* untinkering a dictionary to get the bridge
* items in closet, if enabled
* free pulls from Hagnk's
* items in storage, if no longer under ronin/HC restrictions (note that all of the item is pulled, not just the amount requested)
* items in the clan stash, if enabled
* item creation, up to the quantity creatable from ingredients on hand (this can be overriden by a buyScript)
* trading worthless items to the Hermit
* trading yeti furs to the Tr4pz0r
* NPC purchase (if enabled), or Mall purchase (if enabled, and no ingredients on hand)
* budgeted pulls from storage
* item creation, unless buying the item is enabled and appears to be cheaper than the cost of acquiring all the ingredients
* one final attempt at Mall purchase, if enabled and everything else has failed
{{RFI|Are there exceptions to the info listed under Special?}}

User talk:Jasonharper

2010-03-05T15:21:23Z

Jasonharper:

Thanks for the help you've been giving lately, it's greatly appreciated!

Thought I'd check on something also; is it okay to quote or near-quote revision notes when I don't know how a function works, as I did with [[batch_close]]()? Should I give credit, as I did on that page, or is it implicit that the ultimate source of information may be said logs? Whatever you & V are most comfortable with is fine by me, but if I can save the clutter of including such attributions on a page, it wouldn't hurt.

It would probably also be nice to have a prominently linked-to "Without these mafia devs we wouldn't be here" type of page, I'd think.

Any other thoughts / comments are appreciated.

Thanks! --[[User:StDoodle|StDoodle]] 14:54, 5 March 2010 (UTC)
* As the revision notes are frequently the only documentation you're going to have for a new function, certainly they should be fair game for inclusion here. I agree that attribution of such notes would just be clutter. --[[User:Jasonharper|Jasonharper]] 15:21, 5 March 2010 (UTC)

Autosell price

2010-03-05T13:39:06Z

Jasonharper: Explanation of negative values

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

{{FunctionPage|
name={{#var:name}}|
function_category=Item Management|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|it}}|
p1desc={{pspan|it}} is the item to check the price of|
}}|

function_description=Returns the autosell price of item {{pspan|it}}, or a value <= 0 if the item cannot be autosold. The value will be presented as a negative number in a few unusual cases where an item can't be autosold, but does have a defined value detectable by other means: a Mall minimum price other than 100, or a price in one of the sign restaurants. The laser-broiled pear is an example of a non-autosellable item with a value detectable both ways.|

needscode=yes|

see_also={{SeeAlso|autosell}}|
}}
{{RFI|Is there something I'm not thinking of, as the old description said non-autosell items returned a negative value? Tested items included quest keys, macguffin diary & useless powder (all returned 0)}}

Talk:Batch close

2010-03-05T11:58:58Z

Jasonharper: Bad example!

This is a really bad example of how to use batches:
* The batchable commands are all executed conditionally, so the order in which the first instance of each one is unpredictable, and therefore the order in which the batched commands are executed is unpredictable. If both autosellable and mallsellable items were processed prior to the first item that had a nonzero closet amount, the batch of take_closet()s will be executed LAST. This really needs to be done in at least two separate batches - the autosell and mallsell can be safely done in the same batch, since at most one will be done for any given item.
* There are extraneous server-hitting commands inside the batch, for no reason whatsoever. If cli_execute() became batchable (unlikely, but not entirely impossible), the script would malfunction because the inventory counts inside the main loop wouldn't reflect the outfit change. visit_url() is safe in a batch only because it has an individually significant return value.
* In any case, an example that the user CAN'T SAFELY TRY FOR THEMSELVES does not strike me as being particularly educational.
--[[User:Jasonharper|Jasonharper]] 11:58, 5 March 2010 (UTC)

Adv1

2010-03-03T13:01:25Z

Jasonharper: no CLI equivalent

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

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

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|location|place}}|
parameter2={{Param|int|turnsUsed}}|
parameter3={{Param|string|filterFunc}}|
p1desc={{Pspan|place}} is the adventuring location.|
p2desc={{Pspan|turnsUsed}} overrides the normal number of adventures that are expected to be consumed at this location, or -1 can be passed to use the default. Specifically, 0 will prevent any counters from triggering - of course, if an adventure actually is consumed, any counters that you kept from triggering will be lost.|
p3desc={{Pspan|filterFunc}} is the name of a combat filter function defined elsewhere in your script, with the same behavior as in the 3-paramater version of [[adventure]](). An empty string can be passed to use your battle action or CCS as normal.}}|

function_description=This will adventure exactly once in the specified {{pspan|place}} (even if it took no turns), although it will follow chained choice adventures for as long as you have preset options.

This function does not have to make use of its return value, but if you wish to do so, it will return true if all adventures were used, and false if it is unable to do so for any reason (not enough adventures, location unavailable, etc.).|

code1={{CodeSample|
title=Code Sample|
description=Adventures 1 time at the Slime Tube. If an adventure takes no turns, possibly because the Gall Bladder was already squeezed, that adventure will still count. Counters will trigger as normal.|
code=
<syntaxhighlight>
adv1($location[slime tube], -1, "");
</syntaxhighlight>}}|

see_also={{SeeAlso|adventure}}|
cli_equiv=None - "adv" will always try adventuring again if an adventure took no turns.|
}}

Data Structures

2010-02-28T08:25:45Z

Jasonharper: I'm a zodiacidal maniac!

= 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 an aggregate - another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional aggregates actually operates: 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".

== Assignments ==

If you use a map on the left side of an assignment, you set the whole map at once to the new value. 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. If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

== Declarations ==

The syntax for declaring the data type of a map:

<data type> [ <key type>, ... ]

== References ==

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

<variablename>[ <key expression>, ... ]

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:

boolean [string, string] props;

might be used to hold "properties" associated with names.

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;

references:

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

== Contains ==

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

<aggregate reference expression> contains <key expression>

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).

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

== Remove ==

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

remove <aggregate reference>

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:

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"] );

yields:

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]

== Deletion ==

clear (theMap) will remove all entries

== Sort ==

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

The syntax is:
sort aggregate by keyExpr;
aggregate 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 (even multidimensional maps, but note that you can only sort along a single dimension at a time). The reference must not be enclosed in parentheses, as that would look like a call to a function named sort() - which is still perfectly valid, "sort" has not become a reserved word.

keyExpr 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: 'index' and 'value', holding the details of that entry. The value of the keyExpr is used as the sort key; typically it would be an int or string, 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 "sort ... by value", but many useful things can be done with the use of a more complex keyExpr - 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 "by autosell_price(value)". An array of weapon items could be sorted "by -get_power(value)" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "by value.fieldName", 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.

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

== 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.

record my_type {
int ifield;
string sfield;
record {
int first;
int second;
} rfield;
int [int, int] mfield;
};

my_type rvar;
my_type [int] mrvar;

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.

rvar.ifield = 10;
rvar.sfield = "secret";
rvar.rfield.first = 1000;
rvar.sfield.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] );

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.

Datatype Conversions

2010-02-28T08:13:37Z

Jasonharper: Zodiac is datatype forbidden!

== Part 10 - Datatype Conversions ==

These functions will convert 1 type of data to another.

boolean to_boolean( variable ) 
Converts the ASH-based object into boolean. 
Accepts: string, int

class to_class( variable ) 
Converts the ASH-based object into a class. 
Accepts: string


effect to_effect( variable ) 
Converts the ASH-based object into an effect. 
Accepts: string, int, skill


familiar to_familiar( variable ) 
Converts the ASH-based object into a familiar. 
Accepts: string, int


float to_float( variable ) 
Converts the ASH-based object into a float. 
Accepts: string, int, item, location, familiar, skill, effect, slot, element, monster, boolean, class, stat

int to_int( variable ) 
Converts the ASH-based object into the number that will be recognized by the KoL server. Needed when you’re building raw URLs from time to time. 
accepts: string, float, item, location, familiar, skill, effect, slot, element, monster, boolean, class, stat

item to_item( variable ) 
Converts the ASH-based object into an item. 
Accepts: string, int


location to_location( variable ) 
Converts the ASH-based object into a location. 
Accepts: string


monster to_monster( variable ) 
Converts the ASH-based object into a monster. 
Accepts: string


skill to_skill( variable ) 
Converts the ASH-based object into a skill. 
Accepts: string, int, effect


slot to_slot( variable ) 
Converts the ASH-based object into a slot. 
Accepts: item


string to_string( variable ) 
Converts in-game variables to printable counterparts. The print command will cast non-string values properly now, but these are still useful for building URLs and setting properties. 
accepts: boolean, int, float, item, location, familiar, class, stat, skill, effect, slot, element, monster