Miscellaneous ASH Features

2010-05-08T11:57:37Z

75.97.122.27: /* Additional Script Uses */ - Added chatbotScript information

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

==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.
*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)'''
:Halp!

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

{{RFI|Some scripts still need more information: Stares pointedly at the plantingScript and chatbotScript.}}

Kolmafia - User contributions [en]

Miscellaneous ASH Features