KoLmafia Guide: Running ASH Scripts

KoLmafia has the capability to execute scripts which can perform just about any KoL action. Mafia scripting uses an .ash extension and is simply a text file that contains a bunch of Mafia commands with some programming language constructs as needed. You can browse, download, and execute scripts that other people have written to help automate specific functions or expand Mafia capabilities.

This poses a bit of a security risk, obviously. Mafia is all open-source and examined by many people and is relatively trustworthy. Some random dude's script.... not so much. Feel free to skip this lesson if this makes you nervous. Note that scripts can be extremely helpful though, so it is worth learning about them.

In this lesson, we are going to find a simple script, download it, store it, then execute it.

1. First, we need to find a script we want to execute. For this lesson, point your browser to the KoLmafia forum. This mafia forum has a compendium of various scripts that you can look through in the future. For now, in this forum thread, scroll to the last entry and find the most updated Tattoo.ash attachment.
2. Click and download the Tattoos.ash attachment. You might have to join the KoLmafia forum to do the download. It is not a bad idea to do so anyways, so go ahead and do it. Or you can cut&paste from the bottom of this page into a Tattoos.ash text file.
3. Go find the downloaded Tattoos.ash on your computer.
4. Open the script using Notepad or similar text browser. Take a look. This is just so you can see what a script looks like, and also for your own peace of mind.
5. Do a Find, and look for "buy", "sell", "notify", and "send" text. This is a quick security check. Notify is a one-time mailing to the developer of a script which just lets them know you use their script. It makes the script writers happy, I guess. Send/csend can actually mail people Meat or Items so ensure that nothing funny is going on there. Buy/Sell deals with item manipulation. You want to make sure a script is not gonna go sell all your stuff or buy expensive things. Even the best intended script can bankrupt you.
6. Move the Tattoos.ash script to where your KoL executable lives. Remember in our first lesson we put KoLmafia in a folder. Since then, Mafia created several sub-folders where it stores its settings and stuff. In particular, a sub-directory called 'Scripts' should be present. Move Tattoos.ash into the scripts subdirectory. (For users on non-Windows, refer to Mafia directories for OS-specific directory locations.)
7. At the top, click Scripts and 'Refresh Menu'. Go to Scripts again and you will see 'Tattoo.ash' in the list. You could click it to execute. Do not do this right now though.
8. Back in Mafia, click the Graphical CLI tab.
9. At the very bottom of the screen there is a text entry field. Type Tattoos.ash and hit enter. (or Tattoos will suffice)
10. The Tattoos.ash will then be executed. I am assuming that you finished the Artist quest as it is one of the first ones you received. If so, the script will equip any outfit that you don't have a trophy for already then visit the Tattoo Artist. If you have not done the artist quest this ascension, I have no idea what the script does.

In any case, you will see exactly what the script does since you are already in the CLI tab.

Anyways, this script is pretty cool. Normally it takes a good deal of work to determine when you have acquired a 'new' outfit that you have not received a tattoo for. Assuming you happen to know you have a new outfit, you now have to equip it, visit the Tattoo shop, then put your original equipment back on. This script does this all for you! It searches every single outfit you possess, sees if you have the tattoo and if not, it gets it for you. It also tells you which outfits you are lacking for unreceived tattoos. Pretty cool huh?

Tattoo script

## Original script from: http://kolmafia.us/index.php/topic,527.msg2569.html#msg2569 [19 October 2006]
## Updated by Hippymon 13 November 2007
### Updated by Raven434 - 2009-02-13 
### There are 49 outfit based tattoos now, up from Hippymon's last update of 38.
record tatdata{
   string gear;
   string Img;
};
tatdata[int] Tat;
void load_table(){
##data obtained from http://kol.coldfront.net/thekolwiki/index.php/Outfits_by_number
### - there is no #13 listed in the outfits_by_number page
   Tat[ 1].Img = "bugbear.gif";     Tat[1].gear = "Bugbear Costume";
   Tat[ 2].Img = "hippy.gif";       Tat[2].gear = "Filthy Hippy Disguise";
   Tat[ 3].Img = "fratboy.gif";     Tat[3].gear = "Frat Boy Ensemble";
   Tat[ 4].Img = "haremgirl.gif";   Tat[4].gear = "Knob Goblin Harem Girl Disguise";
   Tat[ 5].Img = "eliteguard.gif";  Tat[5].gear = "Knob Goblin Elite Guard Uniform";
   Tat[ 6].Img = "ninja.gif";       Tat[6].gear = "Hot and Cold Running Ninja Suit";
   Tat[ 7].Img = "coldgear.gif";    Tat[7].gear = "eXtreme-Cold Weather gear";
   Tat[ 8].Img = "miner.gif";       Tat[8].gear = "Mining Gear";
   Tat[ 9].Img = "pirate.gif";      Tat[9].gear = "Swashbuckling Getup";
   Tat[ 10].Img = "Clowntat.gif";   Tat[10].gear = "Terrifying Clown Suit";   
   Tat[ 11].Img = "pressietat.gif"; Tat[11].gear = "Crimbo Duds";
   Tat[ 12].Img = "startat.gif";    Tat[12].gear = "Star Garb";
                                    Tat[13].gear = "#13 is a placeholder in the table.";
   Tat[ 14].Img = "losertat.gif";   Tat[14].gear = "Furry Suit";
   Tat[ 15].Img = "swordtat.gif";   Tat[15].gear = "8-Bit Finery";
   Tat[ 16].Img = "elbereth.gif";   Tat[16].gear = "Yendorian Finery";
   Tat[ 17].Img = "canadiatat.gif"; Tat[17].gear = "OK Lumberjack Outfit";
   Tat[ 18].Img = "radiotat.gif";   Tat[18].gear = "Radio Free Regalia";
   Tat[ 19].Img = "bowtat.gif";     Tat[19].gear = "Bow Tux";
   Tat[ 20].Img = "clocktat.gif";   Tat[20].gear = "Clockwork Apparatus";
   Tat[ 21].Img = "gnaugatat.gif";  Tat[21].gear = "Gnauga Hides";
   Tat[ 22].Img = "hourtat.gif";    Tat[22].gear = "Time Trappings";
   Tat[ 23].Img = "cola1tat.gif";   Tat[23].gear = "Cloaca-Cola Uniform";
   Tat[ 24].Img = "cola2tat.gif";   Tat[24].gear = "Dyspepsi-Cola Uniform";
   Tat[ 25].Img = "wreathtat.gif";  Tat[25].gear = "Arboreal Raiment";
   Tat[ 26].Img = "eggtat.gif";     Tat[26].gear = "Grass Guise";
   Tat[ 27].Img = "jfishtat.gif";   Tat[27].gear = "Encephalic Ensemble";
   Tat[ 28].Img = "recyctat.gif";   Tat[28].gear = "Glad Bag Glad Rags";
   Tat[ 29].Img = "armortat.gif";   Tat[29].gear = "Antique Arms And Armor";
   Tat[ 30].Img = "toweltat.gif";   Tat[30].gear = "Terrycloth Tackle";
   Tat[ 31].Img = "tropictat.gif";  Tat[31].gear = "Tropical Crimbo Duds";
   Tat[ 32].Img = "warhiptat.gif";  Tat[32].gear = "War Hippy Fatigues";
   Tat[ 33].Img = "warfrattat.gif"; Tat[33].gear = "Frat Warrior Fatigues";
   Tat[ 34].Img = "meattat.gif";    Tat[34].gear = "Bounty-Hunting Rig";
   Tat[ 35].Img = "blacktat.gif";   Tat[35].gear = "Black Armaments";
   Tat[ 36].Img = "palmtat.gif";    Tat[36].gear = "Palmist Paraphernalia";
   Tat[ 37].Img = "ducttat.gif";    Tat[37].gear = "Tapered Threads";
   Tat[ 38].Img = "Orbisontat.gif"; Tat[38].gear = "Roy Orbison Disguise";
   Tat[ 39].Img = "Zompirtat.gif";  Tat[39].gear = "Cursed Zombie Pirate Costume";
   Tat[ 40].Img = "Halotat.gif";    Tat[40].gear = "Crimborg Assault Armor";
   Tat[ 41].Img = "Elvtat.gif";     Tat[41].gear = "El Vibrato Relics";
   Tat[ 42].Img = "Hothobotat.gif"; Tat[42].gear = "Pyretic Panhandler Paraphernalia";
   Tat[ 43].Img = "Colhobotat.gif"; Tat[43].gear = "Hyperborean Hobo Habiliments";
   Tat[ 44].Img = "Stehobotat.gif"; Tat[44].gear = "Vile Vagrant Vestments";
   Tat[ 45].Img = "Spohobotat.gif"; Tat[45].gear = "Dire Drifter Duds";
   Tat[ 46].Img = "Slehobotat.gif"; Tat[46].gear = "Tawdry Tramp Togs";
   Tat[ 47].Img = "Hodgmantat.gif"; Tat[47].gear = "Hodgman's Regal Frippery";
   Tat[ 48].Img = "Arbordaytat.gif";Tat[48].gear = "Arrrbor Day Apparrrrrel";
   Tat[ 49].Img = "Dnatat.gif";     Tat[49].gear = "Mutant Couture";
}

void get_tats(int a){
   if(have_outfit(Tat[a].gear)){
      if(!contains_text(visit_url("account_tattoos.php"), Tat[a].Img)){
         cli_execute("unequip weapon");
         outfit(Tat[a].gear);
         visit_url("town_wrong.php?place=artist");
      }
   }
   else print(Tat[a].gear + " is incomplete."); 
}

void get_tats_main(){
   int a = 1;
   while(a < 49){
      get_tats(a);
      a = a + 1;
   }
}

void main(){
   load_table();
   get_tats_main();
}

print("*** Check your Display Case and / or your Colossal Closet for possible missing outfit pieces. ***");
print("__________________________________________________________________________");

Bonus Lessons

Bonus 1) Browse the KoLmafia scripts forum briefly. You can see that there are some pretty cool scripts available, such as ones that automate several annoying aspects of quests for you. You might note that some scripts have prerequisites. One script in particular, ZLib, was created solely as a programming library for other script-writers and is widely used.

Bonus 2) I just started doing the Slime Tube and it sure is a pain. I found a cool slime.ash program which would outfit you, fight the slime, then rinse off when the Covered In Slime effect would kill you. However, it would make me take up to 99% of my HPs in Slime, then waste tons of healing aids to get me back to max. I modified it to auto-rinse after taking 500 damage from a single Covered in Slime effect. This let me kill slime without needing any healing effects at all.

The point is that it is very do-able to download someone else's script then hack it to make it do what you want it to do... or to remove undesired behavior. (notifys, use of consumables, buying things from the mall, etc)

BOTTOM LINE: Learning how to safely execute other people's scripts can be extremely helpful. Just about anything you want to do, someone else has wanted to do it also, and probably has a script for it.

Continue to Lesson 14: Useful Commands