Miscellaneous ASH Features

Special Features of ASH Scripting

These features are not exactly ASH commands, but they are used to improve script usage.

Special Syntax Functions

script

Defines a script's proper name. Mostly for use by a subsequent notify command in case the user saves the script with a custom name.

notify

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

since

Used to inform KoLmafia of the minimum build necessary to support the script's functionality so it can abort execution with a meaningful error message.

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

There are a wide variety of error messages. For help when things go wrong, please see the page on ASH Errors.

Relay Override Scripts

A relay override script is a script that modifies a web page in the relay browser. It is only in the relay browser that the effects of this scripts can be seen. The purpose of this is to alter a KoL page to improve functionality or appearance.

Detailed information is at Relay Override Script.

User Interface Script

A User Interface script is a script that creates a web page viewable in the relay browser. It is only in the relay browser that this special page can be seen. The purpose of this is to extend KoLmafia abilities or present information to the user.

Detailed information is at User Interface Script.

Consult Scripts

Consult scripts are used to script combat. They can be used in automated adventuring or in the relay browser.

Detailed information is at Consult Scripts.

Additional Script Uses

In addition to regular scripts, override scripts, UI 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).

After Adventure (afterAdventureScript)

• Executed just after mafia has finished an adventure.
• The afterAdventureScript setting is executed like a CLI command. If it is the name of an ASH script, that script does not require any special main() declaration.
• By default this only works for automated adventuring. If you wish it to fire when you're using the relay browser then turn it on in General -> Preferences -> - Relay Browser or set the property relayRunsAfterAdventureScript to true.

Before Adventure (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.
• The betweenBattleScript setting is executed like a CLI command. If it is the name of an ASH script, that script does not require any special main() declaration.
• By default this only works for automated adventuring. If you wish it to fire when you're using the relay browser then turn it on in General -> Preferences -> - Relay Browser or set the property relayRunsBeforeBattleScript to true.
• Example: Zarqon's Best Between Battle

Before PvP Script (beforePVPScript)

• This will be executed before every PvP attack initiated through the relay browser or CLI command.
• If you want buffs maintained during PvP (and nothing else) you can do that with:

  set beforePVPScript = mood execute

Breaking the Prism (kingLiberatedScript)

This will be executed after you break the Prism at the top of the Naughty Sorceress' Lair. This trigger is designed so that a character can be automatically prepared for aftercore. The kingLiberatedScript setting is executed like a CLI command. If it is the name of an ASH script, that script does not require any special main() declaration.

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 or an event is received
  • When an event is received the message is stripped of HTML, the channel is "Events" and the sender is an empty string.
• Requires a special main declaration which can have an optional third parameter:

  void main(string sender, string message)

  void main(string sender, string message, string channel)

  • 'sender' is the name of the player who sent the message
  • 'message' is the message that was sent
  • 'channel' is "/clan" for clan messages, "Events" for chat notifications (e.g. "New message received from Bale."), and the empty string for private messages

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. The loginScript setting is executed like a CLI command. If it is the name of an ASH script, that script does not require any 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.
• The plantingScript has to be the name of an ASH file without the extension (if the plantingScript setting is "plant", KoLMafia will call "plant.ash").
• Example: Sandiman's mushroom planting script.

Post-Ascension (postAscensionScript)

Executed at once when your character starts a new ascension. (Example: Bales's newLife). The postAscensionScript setting is executed like a CLI command. If it is the name of an ASH script, that script does not require any special main() declaration.

Pre-Ascension (preAscensionScript)

Same as the Post-Ascension, but 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

Familiar (familiarScript)

• Executed after changing familiars but before automatically changing familiar equipment.
• Requires a special main() declaration: boolean main(). Returning true will cause normal familiar equipment switching to be skipped, while false will lead to it running after the script returns.

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.