Miscellaneous ASH Features

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.
• This only works for automated adventuring. The script will not fire if you're using the relay browser.
• Example: Zarqon's 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 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 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() 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: Sandiman's mushroom planting script.

Post-Ascension (postAscensionScript)

Executed at once when your character starts a new ascension. (Example: Bales's 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 Universal Recovery

A little CLI help

Three CLI commands are of great use to ASH scripters:

• ashref allows one to get a list of ASH functions
• ash or ashq allows one to run ASH directly on the CLI.
• ashwiki allows you to search this wiki by launching a web browser.

Useful forum threads

This thread, started by holatuwol, is a tidy compilation of various undocumented features in KoLmafia.