KolMafia Guide for Noobs.

KolMafia Guide for Noobs - Upd Feb6,2010.

INTRODUCTION:
-------------

Although a few KoLMafia guides exist already, they are either out-of-date, too brief, or too complex. They work, but are typically for more advanced players that catch the lingo and references. My guide is by a noob, to be on the level of noobs. It is (hopefully) easy to understand, pretty verbose, and up to date (at time of writing anyways in Jan 2010).

Note that there are some light SPOILERS in this guide for illustration purposes.


This guide is for those players that are interested in using a great third-party tool to enrich their Kingdom of Loathing experience significantly. Mafia is a java program that acts as a go-between for you to the KoL server. It has its own frame that contains a lot of functionality. In addition, you will use a normal browser window to play like normal. Mafia helps you in many ways:

1) Mafia allows you to use a 'Relay Browser' which is practically identical to the normal playing environment. The only noticeable difference is that Mafia adds bonus information and reminders that are very helpful when playing. This is by far my favorite feature because you do not have to try to learn a brand new interface to use and learn Mafia.

2) Provides some alternative interfaces to do certain functions that you may or may not like better than the built-in interface. At the very least, you can easily say... look up a mall price on something in Mafia without having to redirect your browser to the mall and then back to your inventory or adventuring location.

3) Automation. KolMafia allows you to intelligently automate actions, from small scale to larger scale. As an example, you can easily set up a 'script' combat button that will then do exactly what you want it to do; Maybe a Disco Bandit always wants to Pickpocket if possible, followed up by a Disco Dance, then auto-attack the rest of the way. Or an owner of a certain familiar wants to extend each fight to maximize Meat/Mana/HP,etc gains. Instead of doing this manually for each fight, you click ONE button which does the entire sequence!

4) Reduction of lag. Mafia works as an interface directly to KoL. What this means is that when you automate actions, no browser refresh is needed. This is really helpful, as a 12 round auto-combat using the Script button can be done in about three browser refreshes.

5) Collating of information. KolMafia keeps track of all stat gains, meat found, items found, and an entire log of everything that has happened in the game. The info is logged automatically and effortlessly if you want it.

6) Ability to call player written scripts which do various stuff. For example, one of them will help you equip outfits to get new Tattoos. These require more trust, but I will show you how to examine scripts and see what they do.

Remember... Automation is only ONE aspect of KolMafia! I generally avoid too much of something 'playing for me' myself, and it is entirely possible to use and love KolMafia with NO automation whatsoever!

Unless you are outright opposed to the concept of KolMafia or Greasemonkey, I'd strongly urge you to read this guide and give it a try. By the end of the first Lesson, you will know enough to decide for yourself.


HOW I TEACH/ REQUIREMENTS
-------------------------

I have only played KoL for 3 months. I am hoping this means that I will not take stuff for-granted like year-long players. It also means I will not address details that I simply don't know about or haven't explored much yet (Clan Dungeons, Basement Dive, etc.).

I assume that you have played KoL for at least a few weeks before reading this guide. This is simply so I can reference examples while teaching. This is not a strict requirement though... it just means that you might not catch some of my examples.

Finally, you need to be able to PLAY while reading this guide! Learning while trying to break a speed ascension record or something is probably not the best way to go. 50 turns should be enough to get through most of the lessons.


My main goal is to start out playing KoL using KoLMafia's 'Relay Browser', which is basically identical to normal browser play. Then, each short lesson will progressively give you a new 'trick' that you can use. This lets you learn at your own pace.

Continue working through the guide by doing 'Lessons' until you have learned as much as you want. The lessons are roughly in the order of importance, or more honestly, the order in which I figured the stuff out. :) There is tons of stuff that I probably won't cover, but by the time you are done with the lessons, you will have the hang of it.
 
Last edited:
WHAT ABOUT GREASEMONKEY (skip if you don't care)
------------------------------------------------

I tried Greasemonkey scripts. They are nice, but have four major disadvantages:

1) CodeRot - Many scripts are outdated and their functionality continues to break due to new content, changes, etc.

2) Out of Date - A script is typically written by the author who uses it, posts it, then it is forgotten. People quit KoL all the time for varying reasons. Hence, scripts are very likely to be outdated by the time you find them.

3) Version Overload - On the other hand, there can be too many versions of a popular script, all written by different people who baselined off of someone else's version and so forth. Certain versions incorporate particular fixes and updates, but might be lacking updates and rewrites by someone else. It can be difficult to find the latest, most correct version of a particular script.

3) Security Issues - Greasemonkey by itself doesn't do anything. All functionality comes from the actual scripts, which coupled with many versions/updates and the fact that scripts are scattered all over the internet makes executing them more of a security risk.


I decided to try KoLMafia which has these advantages:

1) More Secure - It comes from ONE sourceforge open-source website and its base version includes plenty of functionality. This makes it much safer to use out of the box.

2) Easier to Install - No digging around and searching forums for hours to find the right script. (At least not until you have mastered Mafia and go looking for Mafia-specific scripts...)

3) Easier to Customize - Not much of an issue at first, but writing a new Greasemonkey script is relatively hard. Modifying KoLMafia behavior can be a lot easier for certain aspects.

4) Consolidated Updates - All KoLMafia work occurs at its sourceforge website. Versions are numbered and under version-control. This means you can easily find the most up-to-date version and no intermediate fixes were skipped.

5) Easier to Figure Out - While the documentation for KoLMafia is not amazing, you will have a lot more luck finding help documents (like this one!) for Mafia, as opposed to documentation for random Greasemonkey scripts.


GETTING STARTED/HELPFUL LINKS:
------------------------------

You need to have this post handy, WHILE PLAYING! I will guide you through each lesson, but you have to be reading it while using KoLMafia for it to really make any sense. Printing it or having it on a second monitor is helpful.

First, here's a list of various websites that I may refer to during the guide. You do NOT need to worry about them now!

KolMafia's website: http://kolmafia.sourceforge.net/
KolMafia forum: http://kolmafia.us/
KolMafia Wiki: http://wiki.kolmafia.us/index.php?title=Main_Page
Existing Guide: http://forums.kingdomofloathing.com/vb/showthread.php?t=140340
List of CLI Cmds http://kolmafia.sourceforge.net/scripting.html


1) Go to KolMafia's website (listed above).
The download link is not really obvious; it's a small link at the top left somewhere. Click it to go to https://sourceforge.net/project/showfiles.php?group_id=126572

2) By default it picks the appropriate package for you. All you need is YOUR system's file. As a windows user, I download the 3 Meg executable. Mac users download theirs. Linux, etc. If all else fails, use the java Jar file.

3) Move the file somewhere handy. NOTE that KolMafia WILL CREATE subfolders. Therefore, I extremely highly recommend placing it in its own folder. Once moved, make a link to it on your desktop so you can easily execute it. NO INSTALLATION IS NEEDED. You just run the file to run KoLMafia. No setup is needed. Once KoLMafia does execute, it will set itself up behind the scenes by creating subdirectories and config files.

4) If the file doesn't run, you need the 1.6 or better Java Runtime Environment. This is not particularly hard and many will likely already have it. The KolMafia website given above, has a 'Getting Started' section that you can refer to in case of such issues.

5) When you first run it, TWO windows pop up. Ignore the complicated looking frame, and look at the one with the login fields. Type in your login info (make sure you don't have KoL running elsewhere obviously), then click the LOGIN button. Ignore the RELAY button for now. Keep the other options unchecked, including breakfast. We will discuss this stuff later.

5) The Login frame goes away and now you have the main box, which I will call the KolMafia Frame. I don't have a place to store an up to date picture, but the whole thing is kind-of intimidating. You are probably ready to quit, but STICK IN THERE! We will make this easy by doing things step-by-step. I'm a noob, remember? I got your back! ;-)
 
Last edited:
LESSON ONE: BASIC OPERATION (Relay Browser)
--------------------------------------------

Now we are going to play using KoLMafia in the easiest manner possible.
Here is a shot of the main frame:
View attachment 2629

NOTE: It is possible that KolMafia may pop up an events logger. This is if you were attacked, received a message, or whatever other status type stuff might happen. Just close that small window if you encounter it.

1) On the Mafia Frame, click the RELAY BROWSER icon. It is second one over from the top left and looks like a little treasure map with an X marks the spot. Or, under the Main MenuBar click 'General', then click 'Relay Browser'.

1.1) This opens your default browser to KoL and looks just like what you are used to when you login to KoL.

1.2) It might use the wrong browser by default. For example, Internet Exploder instead of Firefox or Chrome that you might prefer. If this happens, do this:

a) Click General from the top menubar.
b) Click Preferences
c) Click the Browser Tab.
d) In the Browser textbar, click the [...] button to browse and find the executable for the desired browser. OR, try typing in the name of the browser and KoLMafia will try to find it for you.

2) Do you have any greasemonkey scripts? You can STILL USE a lot of them in this relay browser. I don't really recommend using any invasive ones since we are trying to migrate away from them and focus on Mafia. Go ahead and disable all Greasemonkey scripts for now. Just keep in mind that you can still use them if you want functionality that Mafia cannot easily duplicate. For example, there is a GM script that tries to calculate your total meat value that I still use. A Raid Manager is also a great one once you start doing Clan Dungeons.

3) Completely ignore the Mafia Frame. Play like normal for a while (at least 20 turns), using the Relay Browser. It is practically identical to standard play. Try to play in a zone with some non-combat choice encounters.


NOTICING SOME OF THE COOL MAFIA STUFF:

While using the Relay Browser, you will start noticing some cool stuff that it does automatically to help you out. Here is a short list of stuff to note/try:


1) If you encountered a non-combat adventure with choices, you have seen the first cool Mafia thing. It gives you a short description of what happens when you select that particular choice. For example, if you were in the Sleazy Back Alley and encounted the Hobo non-combat adventure, for the choice, 'Look Under the Hobo', Mafia modifies it and appends ' - get a Mad Train Wine' on the button for that choice. This is super cool and really lowers the Wikipedia usage or guesswork.

2) When you fight a foe, it gives you a quick display about that monster's level, hit points, what it drops, meat drop rate, and so forth. This is really helpful information and is much easier than looking up stuff in the Wiki, or playing blind.

3) There is a hidden counter that gives you a semi-rare encounter periodically. It is normally tracked by eating a fortune cookie or two, then logic-ing out what the magic number is. Then keeping track of how many turns are left until the encounter.
If you have no idea what I am talking about, go to the KoL Wiki and look up 'semi-rare'.

With Mafia, when you eat a Fortune Cookie, it notes the 3 numbers given. It knows which numbers are out of bounds, based on your Ascention Path (Oxycore, Standard, BadMoon, etc) and can sometimes determine the Semi-Rare countdown number based on one cookie. In any case, all valid numbers are added to your buff entries as 'Fortune Cookie(XXX)' counters.

Eating a second cookie will get rid of ambiguity if there are multiple valid Fortune Cookie counters.

The counter counts down as you adventure. When it is gone and you try to adventure, it will stop you. It reminds you that the counter is up and what your last semi-rare was (so you don't try to do the same one again, which negates it).

After the semi-rare, two buffs appear which are a minimum and maximum cookie counter. This makes it a lot more likely that Mafia can figure out the right counter number with only one cookie.

4) Your Last Adventure link now has a history which shows your last FIVE adventure locations. Any of them are clickable. This is very convenient, especially when you make short-term detours such as doing a semi-rare.

5) If you use Action Bars (an interface choice in your KoL Account Preferences), you might notice a "Script" button at the top-left when in a fight. We will learn how to use this later in the tutorial to automatically perform a series of combat actions.
If you use the standard text-based stuff in a fight, you will see additional hotkey-able clickable buttons along the top with certain actions. Normally to use a combat skill, you have to select your combat skill to use from a drop-down. Mafia knows what class you are, what skills you know and makes appropriate buttons for you to save time.

6) You will notice that Mafia helps you out some with quests. For example, it auto-fills in answers to certain puzzles, remembers which Dungeon of Doom potions do what, and misc other stuff.

7) You MIGHT even notice that Mafia does some stuff automatically whether you like it or not! For example, if you get beaten-up, Mafia might use an item to remove that condition automatically. This can be a source of irritation, but we will learn to handle it.

BOTTOM LINE: You can play KoL just like normal and get a lot of handy bonus information very easily.



LESSON TWO: THE KOL-MAFIA JAVA INTERFACE
----------------------------------------
This lesson is a quick one just to standardize my terminology. You dont have to remember all this. The ONLY goal is so you have an idea where I am referring to if I say "Click the Main MenuBar" for example.

Bring up the KolMafia main frame if minimized. I will refer to the following conventions when discussing various parts of it.

a) Main MenuBar - This appears at the top of the screen and has "General Tools People Travel Quests Scripts Window Help" categories. When you click on a category, various sub-categories appear as dropdowns.

b) Top Icons - These are the 20 or so icons at the top of the kolmafia screen. Clicking them generally takes you to various sub-frames for specific tasks.

c) Character Display - At the left hand side shows all your character information.

d) Top Tabs - These are "Adventure Graphical CLI Purchaces Gear Changer Skill Caster". These tabs are clickable to show different functionality.

e) StatusBar - When the ADVENTURE tab is active, this is the big horizontal bar in the middle of the frame that shows the status of the current or last action taken.

f) Bottom Tabs - In certain modes, other tabs are active and show different capabilities. When the Adventure tab is active, you will see bottom tabs showing "Overview Choice Advs HP/MP Usage Mood Setup Custom Combat".


BOTTOM LINE: Now you know what my terminology means.
 
Last edited:
LESSON THREE: STATS-CHECKING
----------------------------

The goal of this lesson is to understand the relationship between the relay browser and the Mafia Frame. The Mafia Frame stays in-sync with the relay browser automatically. This means anything done in the relay browser is captured in Mafia. There is no refresh necessary. Now that you've adventured for a while, go to the Mafia Frame. Click the 'Adventure' Top Tab if it is not already up. Notice the following:

1) The Adventure location dropdown is automatically set to where you adventured last, indicated by the highlighted area.

2) Two panels are in the bottom middle of the screen. The 'Location Details' on the right side shows you all possible encounters for the zone you were last in with drops, percentages and other info. This panel is based on information from the game itself and is roughly equivalent to a compacted wikipedia entry on a zone. It changes based on which zone you have selected in the Adventure dropdown. This is a quick and easy way to determine if this zone is a bit out of your league, or if it is really too easy for you to fully benefit. Advanced players use this info to boost Monster Level for more challenge and benefits since it calculates how often you will hit or evade based on your Muscle/Moxie.

The 'Session Results' panel on the bottom left is a running total of the results of your adventures used so far. This gives you a general idea of how much meat, substats, and items that you have received in your last X number of adventures. To reset this panel, click the 'Tools' Main MenuBar, then 'Clear Results'. (don't do this yet though)

3) Click the Graphical CGI Top Tab. This is misnamed somewhat, as what it REALLY displays is important stats that Mafia has extracted from the graphical interface while you've been playing. It effectively acts as a Log of your activity. You can see all the adventures and fights that you have done this session. This is an important tab to remember, as I was very leery of Mafia at first. Mostly because it did a bunch of stuff and I had no idea what the heck it was doing! This log keeps track of EVERY action that mafia performs. Note that you can type 'clear' into the textbox at the bottom to clear the log. ('Clear Results' does not seem to do the trick)

4) Notice the Mafia Frame has all your stats, including some extra ones like your Monster Level Modifier, Combat Encounter Percentage Modification, Initiative Modifier, Experience Booster Mod, Meat Find and Item Find modifiers. The only thing lacking is a Semi-Rare counter, which is found on the Relay Browser instead.

5) Right-Click the area in mafia that has all your stats. Feast your eyes on all the cool additional info that mafia calculates for you, such as Damage Absorbtion, all your resistances, bonus damage, and all kinds of cool stuff.

Bonus) In the Adventure Top Tab's two panels, you can right click and do various operations. For example, hopefully you found a usable item in your last 20ish adventures. Right-click the item. This pulls up a menu where you can Consume(use) the item, sell it, get a wiki-description, and other options. This is really handy instead of having to dig through your inventory, find it, then deal with the item appropriately.


BOTTOM LINE: The KolMafia frame keeps track of stuff you do in the relay browser (normal play).



LESSON FOUR: MANUALLY USING AN ATTACK SCRIPT:
--------------------------------------------

Now we are going to fight a foe using a Mafia script instead of our standard method. It is very easy!

1) In the Mafia frame with the Adventure Top Tab active, on the far right there is a pulldown that is labeled 'Action:'. It defaults to 'Attack with Weapon'. Not surprisingly, when auto-combat is activated the script will keep attacking until the combat is over. By clicking this pulldown, you can choose several other options, based on what your character has available. For example, you can have it spam Thrust-Smack, or cast a spell, or whatever.
For now, either stick with weapon-attack, or casting a low MP offensive spell.

You can click in the bar below that lableled 'Special:' to set up any special beginning-of-fight actions. For example, as a Moxie-Class, an option is for Mafia to automatically pickpocket all non-bosses if you win initiative. If you are a moxie-class, pick this option. A Myst-class can autocast Noodles. When selected, a corresponding symbol shows up in the Special Box.

Here is a screenshot of my custom combat script:
View attachment 2632


2) In your relay browser, go fight something easy but takes a few rounds to kill. If you use Combat Action Bars, click the 'Script' button. If you don't use action bars, Mafia adds several buttons for easier combat and the 'Script' will be one of them.

3) The script will execute, which will pickpocket if possible (if you are a Moxie class, noodle if Myst,etc.), and then spam the default action until the fight is over. Cool huh? No more clicking the Attack button 6 times every fight! If you run out of mana, it will try to recover mana or default to a weapon attack. (more on this later).

You will notice the fight will go a lot faster too in that it will appear to 'skip rounds'. This is because KoLMafia can send commands and receive results back faster than your browser will refresh. Hence a 12 round fight may only take 3 or 4 refreshes. This speeds up fighting significantly.

BOTTOM LINE: You can save clicks and lag by using the Script button to fight easy battles for you.




LESSON FIVE: MANUALLY USING A CUSTOM COMBAT SCRIPT:
---------------------------------------------------

Autoattacking is fine and all, but in many cases you want something a bit more sophisticated. For my example, I am a level 15 Disco Bandit, fighting the Giants in the Cloud Castle with plenty of MP regen. I want to use my Disco Bandit combo skill which makes the fight easier AND gives me a 1 turn +30% meat buff.

1) As an example, this is what I would do: (don't actually do anything for this step) In the Mafia Frame, I click the 'Custom Combat' Bottom Tab when in the Adventure TopTab. I see a script called "Default", and it has several lines: A [Default] folder, followed by a 1: Special Action, and 2: Attack With Weapon. This indicates the following:
When encountering a [default] monster, on round 1: it will Use any special action indicated under the Special box, as described in the last lesson. This includes Pickpocketing, or whatever.
On Round 2, it will Attack with Weapon. On round 3 and beyond, it repeats the last action commanded, which in this case is Attack with Weapon.


2) We are gonna make our own script now! Click the NEW button at the bottom-right. Give it a name. This script is now selected instead of the "Default" custom script.

Note that we have the exact same 'default code' we saw in step 1. Note that [default] does NOT refer to the name of the script. It is simply a header referring to the series of actions it performs against a default monster. In advanced scripts you can put in a [monster name] with special actions taken against just that monster. This would be great for casting an elemental spell against a physical-resistant foe for example. For now, don't worry about it.

3) Click EDIT and modify our script. For my example, My script I described earlier would look like:
[default]
1: steal
2: skill disco dance of doom
3: skill disco dance II: electric boogaloo
4: attack

When you hit OK, it will interpret what you typed. For example, the keyword 'steal' turns into 'try to steal an item'.
This script will pickpocket if applicable, do my 2 disco skills, then attack with weapon until end of combat.
A more flexible script would be to Use Special Action as the round 1 action. This would allow me to choose whether to pickpocket or not, based on what is in my Special box.


For you, make the following script depending on your class:
line 1 - [default] (leave this line alone)
line 2 - 1: special action (leave this line alone too)
line 3 - add 2: skill <insert skill name here>
line 4 - 3: attack. (leave this line alone)

So really, all you did is add line 3 and renumber line 4 from 2: attack to 3: attack.

The only trick is to find the exact name of the desired skill. Pick one of your low-level skills like Thrust-Smack, or a spell, or whatever. Use your Relay Browser and click your top-left character profile to get the exact name. Type it in, Hit OK. The 'attack' command will turn into 'attack with weapon'. Note that the last entry is what the script will keep repeating until the combat is over.

For Reference, the HELP button will give you a list of the script commands. 'steal' is for pickpocketing, 'skill X' will perform the skill, X, you specify. 'item X' uses an item. There are several others to explore later.


4) Make sure the main KolMafia Frame's 'Action:' pulldown shows 'custom combat script' as the active one, as opposed to 'attack with weapon'.

Next, make sure that your named script is selected, as opposed to Default.

5) Time to test it! Go fight something in the Relay Browser and click the Script button at top-left. Watch and see what it does. Did it work? Actually this might be a bit tricky to determine since Scripted attacks tend to skip browser refreshes. Instead, click the 'Graphical CLI' tab and see EXACTLY what your character did.

Bonus) Modify your script and add a 20: abort. This will instruct the script to abort as the 20th action (not necessarily the 20th round). It will pop up a mini-browser and you will finish the fight manually. This is a good catch-all safety feature in case you are fighting a physical immune with no elemental damage, or using a low-power 'disguise outfit' or trying to wield a melee weapon as a moxie-class, or whatever else went wrong.


BOTTOM LINE: Combat Scripts are very flexible and can help you take advantage of stuff you might normally be too lazy to do regularly such as Disco combos, Turtle Tamer Chains, Noodle Summons, and other repetitive things.
 
Last edited:
LESSON SIX: AUTO-ADVENTURING
-----------------------------

Now we are going to let Mafia adventure for us! We have our customized combat script prepared and are ready to go! (You might want to modify it to remove the level 0 test-skill that we did in the lesson).

1) Lets pick a location. Pick one that is pretty easy such as Sleazy Back Alley. Making sure the 'Adventure' TopTab is active, you need to find and select the location. This can be irritating because there is so much crap! There are so many locations that are obsolete (Crimbo 2006 for example) that clog up the works. Fortunately the text-bar right above the locations box is a FILTER! Type in Sleazy for example and it will filter the results so you can find the Sleazy back alley.
Anyways, pick an easy location to adventure for testing purposes then make sure it is selected as indicated by highlight.

2) Next to the text-filter box on the right is a small entry textbox with a little up and down adjustment arrows. This is where you specify the maximum number of adventures to go on. It is a good idea to type in a limiting number. Otherwise, Mafia will use ALL your remaining adventures if not aborted. Put in 10.

3) Clear the display by selecting Tools from the Main MenuBar, then 'Clear Results'. We want a fresh panel to see the results of our adventuring!

4) Make sure the 'Goals' dropdown is greyed out. If not, uncheck the little box to its right.

5) One more thing... click the 'Choice Advs' tab once your zone is selected. You will see a Zone and Item tab that relates mostly to that particular zone. This lets you auto-select what Mafia will do when it encounters a particular adventure. For the Sleazy Alley, you will see 5 different pulldowns. Each one corresponds to 5 non-combat adventures in that zone. It comes with intelligent defaults, but you can customize it as you wish.

6) Now, click BEGIN! The big progress bar in the middle will start incrementing as you adventure. You can see your HPs/MPs going up and down and your experience increases, and your substat gains and loot acquired.

7) The progress bar will indicate when it is done. In general for Mafia, a blackened bar will be displayed when a task is done and Mafia is idle. Sometimes there is lag in KoL, so this gives you an idea when a task is actually done.

8) After starting it, click the Graphical CGI tab which logs our adventures. The log shows you exactly what happened (or is happening) for those 10 adventures. This is important to see that your combat script is doing what it is supposed to. (pickpocketing, etc) Technically we have already tested this, but it is worthwhile to check.

9) Once it is done, click back to the Adventure tab and you can see a summary of those 10 adventures. It shows all Meat, Loot, and Substats gained in that bottom-left tab.

10) IMPORTANT! REFRESH YOUR BROWSER! Mafia synchs with the browser, but the browser does NOT auto-refresh when you do stuff in the Mafia Frame! Keep this in mind. Hence, the Adventures Remaining and other info will not be current. Once you do an adventure or something that would refresh the info, the browser will catch up.

Note that refreshing the browser will KICK YOU OUT OF CHAT. No biggie, but you will lose chat history this way. A way to avoid this is to either use Mafia's built in chat interface, OR instead of refreshing the browser, the status-window on the left has a refresh link at the very bottom.

Bonus) Note that you can also click the 'Stop Now' or 'Stop After' buttons on the Adventure tab to stop adventuring. I recommend the Stop-After which will finish the current adventure. If you 'Stop Now', a mini-browser pops up for you to manually finish the current encounter if you happen to have stopped it mid-fight.


BOTTOM LINE: Mafia can REALLY speed up the 'grind' aspect with careful usage of auto-adventure. This is one of my favorite features.


LESSON SEVEN: MANAGING AUTOMATIC HP/MP RECOVERY
-----------------------------------------------

These zones were easy and you should not have lost any significant HP/MP. This will not always be the case.

Mafia can (and WILL!) automatically recover HPs and MPs in-between encounters. You probably don't want Mafia running off buying stuff to heal you or using precious semi-rare consumables. Therefore, we need to get Mafia under control.

1) Click the 'HP/MP Usage' tab in Mafia Frame when the Adventure tab is active. It will give you a painfully detailed listing of whether it will automatically use HP/MP recovery in between adventures.

2) I personally do not want Mafia to recover MP and health automatically. I recommend the following settings:
a) Stop Automation - This setting won't matter since we will not be auto-recovering health.
b) Restore your Health - The first dropdown is how low your HPs drop before Mafia attempts to recover health. The second one indicates how much health it will try to restore. Set both to 'Do not recover health'.
c) Mana Burning - This setting is kind of nice for auto-casting Librams, but set it to 'Do not rebalance buffs' for now.
d) Restore your Mana - Set to 'Do not auto-recover mana'.
e) Uncheck all boxes for various restores.

BOTTOM LINE: You can decide whether to have KolMafia auto-recover health and mana for you. I prefer to retain manual control over it. I am also very conservative and favor HP/MP familiars and gear, so it is up to you.


LESSON EIGHT: GOAL-ORIENTED AUTOADVENTURING:
--------------------------------------------

For this lesson, we are going to complete a Bounty Hunter contract with KolMafia.

1) Go to the Hunter like normal, pick a reasonable bounty that is fairly easy to do, in a zone you can access. Check your equipment, etc.

1a) Alternatively, you can click the 'Travel' from the main menubar, and click 'Visit the Hunter'. Then choose your bounty. That might be a bit quicker.

2) Go to the Mafia Frame. Make sure your custom combat script is good to go, unless you just want auto-attack or auto-spell. Change the Adventure number to 60, just to have a constraint. (A bounty takes 40 typically). Make sure you have 60 adventures left. Eat/Drink/etc to do this.

3) Look at the zone selection box. When you first select a bounty it automatically selects the appropriate zone for you.

4) Click the Checkbox under your combat script that says GOALS. It un-greys a dropdown box. If the box is greyed out, this means NO goal oriented adventuring will occur. Mafia should automatically have the right bounty items selected for you.

5) In the dropdown box for Goals, you ought to see something like '5 raver giant skins' or whatever that corresponds to your bounty goal. Make sure this is selected, un-greyed, and looks right.

6) Clear your session with the main menubar, Tools, 'Clear All Results'. I like to do this for each session of adventures.

7) Tell it to BEGIN! It will start adventuring and automatically update you on your goal progress. You will see the Goals box start dropping to '4 Raver Giant skins' or whatever. It will also STOP ADVENTURING when its goal is done, which will likely be before the 60 turns you constrained it to. You will notice that it even turns in your bounty for you when its done! If it was unable to complete its Goal, it will inform you when it hits its constraint.

8) Warning: Once the goals are completed, it will reset back to the '5 raver giant skins' or whatever goal. Basically it looks like before you started adventuring. This is just an annoying thing Mafia does to facilitate doing multiple sets of goals. Obviously you cannot do so with Bounty Hunting (1/day), so you will just uncheck the Goals checkbox and be done.


Bonus) The Goals-Oriented feature is really great for bounty and also questing. Normally to do the pirate quest for example, you have to remember which 3 items you are looking for, fight, loot, use, and keep up with when you get one of the 3 items, and then remember when you have them all. Instead, with KolMafia, you can simply use the pulldown menu that corresponds to that goal and tell it to go! It will go until it finds all 3 goal-items.

This feature is possible because KolMafia has many built-in goals that correspond with automate-able adventure constraints. It knows that you are on the Pirate quest, at a certain part of it. Therefore, it knows that you need X,Y, and Z items to continue. Hence, it pops up as a goal. Once you have these items or are done with the quest, this goal is not an option anymore.


BOTTOM LINE: Goal-oriented adventuring is even smarter than auto-adventuring and can be very useful.
 
Last edited:
LESSON 9: SETTING KOLMAFIA PREFERENCES:
---------------------------------------

This lesson is important to keep Mafia from doing stuff you don't want it to. In the latest 13.9 version, the developer has set much more conservative defaults so this is not as necessary. Still, lets go through the major options.

1) Under the main menubar under General, click Preferences. This pops up a tabbed browser with tons and tons of preferences and options.

2) You probably took one look at all of it, said 'Oh @&%$!' and closed it. It's all good... Re-open them. :)

3) Make sure we are on the General tab of the options:

4) The first interesting option is "Auto-Remove malignant status effects". You might want Mafia to not use restoratives to remove bad conditions. On the other hand, a newer player might keep this, since they don't know what restores which condition anyways...

5) I recommend Protect against accidental ten-leaf clover. This warns you when you are about to enter a zone which would use a ten-leaf clover. As a noob, I've wasted many clovers in this way before Mafia came along.

6) I recommend allowing mafia to buy from NPC stores. This gives you a lot more flexibility when creating drinks and food since Mafia will know that they can buy fruits and other components from the NPC as necessary.

7) I would keep Buy from the Mall turned off. You MIGHT want to turn this on for short periods, such as when creating a bartender/chef in a box. Note that Mafia will never buy anything worth more than 20,000 meat which provides a safety feature.

8) Your clan probably has a karma limit and several rules. Hence, uncheck Taking items from clan stash, as this can lead to nastygrams from your clan!

9) Under the Browser tab, do NOT check the wiki option, as every item you click will pop up a full page wiki entry, constrained to a tiny 4 inch item display. Not cool. You can use the right-click menu of your account options to lookup stuff anyways.

10) Under 'Main Tabs', you can actually customize which Mafia functions appear. If you dragged Item Manager for example from the Complete List to the Startup in Tabs, then it would be accessible as a Tab instead of you having to specifically pull it up. Once you get the hang of Mafia better, you might want to add a commonly used tool to the Tabs.

11) Ignore Breakfast for now. This will be the next session.

BOTTOM LINE: It is important to know some of the key options to constrain Mafia.


LESSON 10: SETTING UP BREAKFAST
-------------------------------

Breakfast is defined as Mafia doing the repetitive stuff that you want to do every day, automatically.

1) Bring up the Preferences as before under main menubar, General, Preferences.

2) Click the Breakfast tab.

3) The first thing you see are options to execute scripts during login or logout. We will skip this, but note that it gives you the ability to automate a lot of stuff. For example, say you want to switch your gear to equipment that boosts your adventures per day, then drink a final cocktail. You could use the On Logout script to do so. In our scripting tutorial we will create such a logout script.

4) You will see two seperate sections for both Ronin-clear characters and in-ronin ones. For the most part, I'd expect you to have both of them exactly the same... EXCEPT to enable 'honor path restrictions' during the ronin period.

5) I would recommend you click all of the applicable available checkboxes. You might not want to get hermit clovers though if you are more advanced. This command buys hermit permits if needed, then visits the Hermit, gets clovers, then uses them to make them Disassembled Clovers if you have worthless trinkets with which to use them. It will NOT spend your adventures fishing around in the sewer for Worthless trinkets though.

6) You probably want to turn off Enable Auto-Recovery. I assume that even if enabled, it would follow the constraints under HP/MP recovery, discussed in a previous lesson. I'd keep it off just in case.

7) Finally, kill Mafia and restart. Check the Breakfast option. From now on, it will take care of a bunch of stuff automatically. For example, who remembers to use their Manual of Dexterity (depending on class) every day? Or pick the clan meat bush, play the stuffed game, etc. NOTE: Breakfast does NOT use the clan Chips machine! This might be a good candidate for a login script if your clan has such a machine.

8) Tab over to the Graphical CLI to see exactly what all it did during breakfast.

BOTTOM LINE: Breakfast is a great way to automatically accomplish a bunch of stuff when you login.


LESSON 11: EATING AND DRINKING WITH KOLMAFIA
--------------------------------------------

This lesson covers managing and creating food,drink,spleen with Mafia. By default, eating and drinking sucks in KoL. You have no clue what most of the items do, and their description is unhelpful. Digging through the wiki is time-consuming and irritating.
Once you get into recipes for creating food and booze, it becomes very difficult to get anything done without tons of Wiki studying.

Mafia does a lot to address this and help you automate and keep track of your consumption. In this lesson, we will attempt to make and consume some drinks.

1) We are going to make some drinks. I am assuming that you have SOME stuff in your inventory that you can use to make drinks, AND you are not almost-drunk already. Go ahead and use advanced cocktail to summon Ice Cubes, etc if you can do so. Note that breakfast will do this for you.

2) Click the Lunchbag looking icon, or from the main menubar under General, select Item Manager.

3) This is a big interface. On the left hand side, click on Booze in the long list of stuff to do, under Usables.

4) The screen is split into a top half and a bottom half. The bottom half contains a scrollpanel which has listings of booze, sorted by the quality of the beverage. Note that each drink has complete info as to stats and adventures per inebriation all spelled out. Its really awesome!

5) You will notice that each drink has a number in parenthesis for Possible and Current. The Current number is how many of that drink you really have in your inventory. Possible is how many you COULD have, by mixing, etc. When the Potential number is the same as the Actual, this means you have all of that drink that you could with your current state of inventory.

6) You can click the No Create checkbox which will then only show drinks you have in your inventory, vs showing all drinks you could conceivably make. The Per-Drunk checkbox should be active as Adventures per Drunk point are a much more useful measurement than total adventures.

7) Going through the scrollbar, find the highest drink where you have more Possible than Current. This means you can make this drink. Select it and click Enqueue. It will ask how many to enqueue. It defaults to the difference between how many you have and can have, up to how much you can actually consume. In other words, if you have 3 martinis and 2 olive/gin, then it will default to enqueing 2.

8) Now, that drink goes to the Top of your screen's panel. Notice that the tab now shows how much Drunkeness you have enqueued. You can click the Ingredients Used tab to show exactly what the drink consists of.

9) Click the Create button. It will now mix that drink for you, using a bartender-in-a-box if it can. It will AUTO_CREATE the bartender(!), if you have sufficient inventory to do so. If you changed the mafia preferences to buy from the mall, Mafia will go buy what it needs in order to assemble it in the cheapest manner possible.

10) That drink now disappears from the top box and now your Current number has gone up for that drink. It made that drink for you.

11) You will probably wanna go ahead and drink. Use any booze-booster like the Ode to Booze buff or whatever first. Then, assuming you have a max drunkenness of 15 (the default), enqueue 14 drunkness worth of your best booze. You can Consume directly if desired, but I prefer to queue it all up first.

12) The top box will populate with your booze and auto-count the intoxication, warning you if you are about to overdrink. Click Consume when ready and it will drink.

13) Exit the Inventory Manager, click the CGI Graphical tab and look at the log. See what all it really did for you behind the scenes. You might see that it bought a fruit from a hippy (by disguising if you had the suit), or a soda water from the Market. The log lets you see EXACTLY what it did, which is an important step when learning KoLMafia!

14) Bring up the Inventory Manager again. Repeat this process for Food. Then, click Spleen and go ahead and consume all the various Moxie Weeds and other junk that accumulates in your inventory. Mine as well get the free substats!
Advanced players can create and consume Wads or whatever other kind of Spleen management you guys do.

IMPORTANT NOTE: It should be noted that the Item Manager is VERY pesky about allowing you to make drinks that you cannot consume. If you are totally drunk, you will find that the Item Manager will not let you make any drinks!

Bottom Line: KolMafia really takes the guesswork/research out of eating and drinking, and is a huge help for cooking/mixing.
 
Last edited:
LESSON 12: PVP, BEATING UP PEOPLE
--------------------------------

1) Click the Flower-looking icon in the main frame. OR, main menubar under Tools you can select Flower Hunter.

2) It pops up a new window and defaults to the Attack tab. Click the Search tab instead.

3) It automatically populates the Max Rank field intelligently. For example, with a 151 Rank, it will set a Max Rank of 112. What this means is that it will look for foes that are at the lower spectrum of what you can attack. Remember, a 151 can only attack as low as a 101, not a 100.

4) Click Search with the default options. You can see that it finds a bunch of foes between Ranks 103 and 112 for you to pick on.

5) Now click the Attack Tab. It will default to using your main stat for Fighting. It defaults to Stealing a Flower. You can pick Rank or Dignity. IMPORTANT NOTE: KoLMafia was apparently written by a bunch of PvP panzies... as such you CAN NOT SOLELY USE MAFIA for stealing people's stuff!

6) All you have to do now is select a foe, then click Attack. It will pop up a window showing the results...which you will probably have to enlarge.

There are TWO other ways to use the PvP interface for Mafia....

A) If you want to just pick flowers, you can click the Search tab, click the Flowers button. WARNING: It will automatically search for low ranked foes and fight them with all your PvP attacks! It is a quick and easy way to PvP.

B) If you want to steal stuff, simply follow the above steps to search for those of appropriately low rank. Then, pop up the normal PvP interface at your campground and fight like normal. The only downside is that you cannot cut&paste the names. Hence you must type them in yourself. It still is a lot better than only having the default list of similarly ranked foes, right? Or having to manually go looking for victims...er..opponents. :) I recommend making your Browser window a bit smaller temporarily, then put the Mafia PvP window next to it, and expand the Name column. That way you don't have to go back and forth from Browser to Mafia.






LESSON 13: Running other people's Mafia 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.

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. (link at the top of the guide). This mafia forum has a compendum 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.
http://kolmafia.us/showthread.php?t=1736&highlight=tattoo

2) Click and download the Tattoos.ash attachment.

3) Go find the downloaded Tattoos.ash. 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.

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. Good for epeen value 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 meaning 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.

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 CGI 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 CGI tab.

Anyways, this script is pretty cool. Normally it takes a good deal of work to determine when you have a 'new' outfit with no tattoo for it. Then to equip it, visit the Tattoo shop, then put your original equipment back on. It also tells you which outfits you are lacking for unreceived tattoos.

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

Bonus2) 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 elses 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: There are a lot of really useful scripts people have already written which can help you out.


LESSON 14: LIST OF USEFUL TYPED-IN COMMANDS
------------------------------------------

Most people will prefer the GUI for KoL playing. However, Mafia does have a handful of useful functions that you can type in.

These are the ones that I have found to be useful. Your mileage will vary, but read through these and try em out. A FULL LIST can be found in my Links section at the top of the guide.

1) You will need to be at the 'Graphical CLI' top-level tab.

2) At the bottom of the screen is a small textbox where you may enter commands.

* help [optional command] - Gives you a list of commands. OR how to use the given command if you type it 'help burn' for example.

* clear - Clears the screen and log entries entirely.

* inv [filter] - Shows you your inventory. The cool thing is that you can add a filter. So for a list of all your wads, you would type 'inv wad' and it will come back with Twinkly Wad, Hot Wad, or whatever wads you have. I generally use the item manager and sort by alphabetical order or type instead. But this works too. For example, you ask yourself 'did I get that pirate insult book doodad?'. You don't have to know the exact name. Just type Insult and let it do the work.

* modref - This gives you a huge list of pretty much ALL conceivable character stats such as Sleaze Damage, HP Max, Regen Rate, all resistances, and so forth. Furthermore the exact text of the first column works as a 'category' which you can then feed to the next few commands.

* maximize [category] - Equips your character using your inventory to the best of its ability in order to maximize the given category! Categories are found through the 'modref' command above. So if you wanted to maximize your Sleaze Resistance, you would type 'maximize Sleaze Resistance' and watch it go! It will give you a Score for the level of the maximized level. This is extremely useful for Clan Dungeons!

* modtrace [category] - Prints out a list of all sources that modify the desired category, either positively or negatively. So if you are wondering WHY you have a Meat Drop rate of say..140%, it will break it down for you!

* modifies [category] - Shows you ALL sources that modify the given category IN THE ENTIRE GAME. Whereas the previous commands just work with what inventory you have, this command lists everything, straight from the wiki. Sometimes this command is kind of flaky.

* wiki [filter] - This command shows you the wiki entry for whatever you typed in and pops it up in a new Tab. This is a really handy shortcut.

* Various Listers - These commands give you a list of quest or ascension-specific stuff you have identified.
a) bang - Shows identified Dungeon of Doom potions. (clear, murky, etc)
b) dusty - Lists identifies Dusty Wine bottles. (pinot noir, merlot, etc)
c) insults - Lists all known pirate insults.
d) demons - Lists names of demons known for summoning.

* pvplog - shows results of PvP combat. It actually generates a spreadsheet of all battles from your messagebox. To see it, you must go to the KoLMafia Directory under the Attacks subdirectory. It is very helpful though and even figures out all your enemies stats for you! (Like how many White Canadians they have drank, etc.) This is great if there is one guy that really hacks you off. This parsed log will help you gather info on them.

* undercut - Any items in your Mall store with the default price of 999999999 will be repriced to match the lowest mall price. Note that Mafia ONLY knows the 5th cheapest price of any item in the mall. Therefore it may not actually price the item exactly right.

* reprice - ALL items in your mall store are repriced to match the lowest known mall price. As mentioned above, mafia can only know the 5th cheapest price of an item. Remember, YOU can go to the mall and read off the lowest price. Mafia can't read and is only able to 'ask' KoL what the price is by whatever interface (API) that KoL allows.

* alias - Lets you create a shortcut command. Great for buffbots. For example, "alias buffode => csend 300 meat to buffBawt" would mean that you'd simply type buffode and it would then send meat to some random buffbut which you would know would cast Ode to Booze on you.

* csend - as shown in Alias above. Sends a kmail to the target with attached meat or items.
 
Last edited:
LESSON 15: FINAL CLOSING THOUGHTS
---------------------------------

KolMafia has so much functionality, it is ridiculous. We have gone over the basics, but I want to leave some final thoughts on other neat things Mafia can do.

1) Redundant Functionality - Mafia is meant to REPLACE the normal KoL interface. In our lessons, we have used Mafia as a suppliment to the normal interface. What this means is that Mafia has a lot of duplicate functionality. For example, the Store Interface and the Equipping Manager are just about identical to what KoL already uses. Therefore, I use them interchangably. In many cases, there islittle advantage to using Mafia's version (like for equipping and inventory management), so I rarely use it.


2) The Quest main menubar has some interesting functionality. By selecting one of these, KoLMafia will automate a quest for you. For example, the 'Tavern' will automatically adventure at random tavern locations until it finds the faucet. It will then stop and leave it up to you whether to turn it off or not. Selecting 'guild' will do all your guild unlocking quests. Maze will automatically work through the sorceress hedge maze for you. 'Leaflet' completes the leaflet quest for
you, which saves a ton of time typing.


3) You can write your own .ash scripts. Several tutorials may be found at http://kolmafia.sourceforge.net/advanced.html. I personally have not found much reason to investigate this, but I can easily see scenarios occurring for it. Especially for more advanced players. For example, a player might want to drink Absenthe, do the required 3 adventures for the not-a-pipe reward, and inbetween do farming at the Castle for example. This would be tedious to do manually or even with Mafia. However, you could write a reasonably simple Absenthe.ash script that would do this for you.

I think the best way to go about script writing is to find a similar script someone has written, then go modify it to do what you specifically want it to do. In the above example, I'd find a script that adventures in certain locations and uses items. You can then steal the syntax and replace 'Absinthe' and the appropriate adventure locations, rearrange it, and have yourself a functional script.


4) The Item Manager has a lot of functionality. I like to click the General selection and see ALL my inventory on one screen. You can then use the textbox and/or checkboxes to filter as desired, use items, send to mall, get a wiki page, etc. This is really handy when you want to do a quick check if you have something or not. Its a LOT easier than searching for a specific item with the normal inventory interface (even with CTRL-F to help you find it!).
In addition, under Equipment/Pulverize, it can assist you in knowing how to pulverize equipment and even send to Wadbot to do it for you!
The Item Manager is also great for restores. You can click Usable/Restores and it filters down to items that are usable to restore HP or MP. There is even a handy 'Check Wiki' link to find out what they do!



THIS IS THE END OF THE CONVENTIONAL KOLMAFIA GUIDE!
---------------------------------------------------
If you are interested, once you have this down you might want to tackle scripting. This is writing your own scripts to do various stuff. I recommend that you at least read through the rest of this guide and it will give you an idea of what you are capable of and how difficult it will be to do so. I tried to include several very usable and easily modified scripts to get you started.
 
Last edited:
POST-LESSON 1: SCRIPTING FOR DUMMIES
------------------------------------
In this lesson, I am going to show you several scripts that I made. These are SIMPLE scripts with very limited logic and fairly well commented code. I'll go through quite a few things and show you how to do them, so that you can easily use them as a base and modify them as needed.

COOL NEW FEATURE: Go to General, Preferences, General. At the bottom there is an External Script Editor. Fill in whatever editor you want to use. (For windows, I'd go with c:\Windows\NOTEPAD.exe). Then you can easily edit a script by holding down shift and clicking it in the 'Scripts' pulldown menu!

It really is not all that difficult to steal code snippits from others and make simple scripts that can simplify your life significantly.

Another thing to note is that you create scripts INCREMENTALLY. You get the first pass of the script working... then you maybe add more complexity. Or you add an additional check. Or whatever. The bottom line is that you don't want to be overwhelmed and expect to get it all working on the first pass.

1) Our first objective is an auto-buffing script. This one takes an input (in tens of adventures for simplicity) and then casts buffs on your character. In this case, I use cheap buffs that boost item-find. This is for undersea exploration or other places where boosting item find is handy or profitable.

It is super easy to use this template to create ANY personalized buff script. You can cut&paste and replace my buffs with whatever you want to cast any buffable effect from potions/items on yourself.

Executing: Cut&Paste the code into a text file. Turn off Word-Wrap and make sure no line has a line-break. Save the file as 'itemfind.ash' for example. Now you can run it as shown in previous lessons. (You put the .ash file into KolMafia/scripts directory, refresh from the browser, then you can run it)

Learning: The entire script is below all my 'letter points'. Basically, read each letter point and then find the corresponding part of the script. It might help to browse it in 2 windows.


a) First, notice the void main statement. You should go ahead and make all your scripts start with this. Note the int numberOfTurnsInTens in parenthesis. This means when you run the script, it will pop up and ASK you to enter a value for 'numberOfTurnsInTens'. So make your variable names descriptive enough to remind you exactly what they are.
Alternatively, you can type 'itemFind.ash 5' and it will automatically set '5' for the variable numberOfTurnsInTens.
So why didn't we just ask for turns? The main reason is simplicity. You cannot buff yourself for 12 adventures anyways, so you would have to round up or down to 10 or 20 turns. This just adds extra complexity to the script which we are trying to avoid.

b) Second, lets look at the main logic structure. We use an IF statement to check and see if we have enough of the potion to use. If not, we buy the number we need. After that we should be pretty much guaranteed to have the item. So, we then use the right number of that item.

c) item_amount($item[xxx]) is a function that will tell you how many of an item you currently possess.

d) The buy( #, $item[xxx]) is what you use to buy stuff from the mall. You NEED to use this function as it specifically overrides your normal preferences. If you use the 'acquire' command, it will not buy from the mall if you have told KoLMafia not to (which we did in an earlier lesson).

e) The use(#, $item[xxx]) is pretty obvious. As mentioned above, we either have or have bought the appropriate number of the item to be used.

f) For the last item, you notice that I use a 2* in front of most logic. This is because that particular buff only lasts 5 adventures, whereas the others last 10 adventures. Therefore the easy solution is to use double the amount of the shorter duration buff item.

g) You can cut&paste a section and fill in ANY buff you want! I just picked the cost-effective ones for me.. and I have tons of Polka Pops. You can use Ermine Eyedrops, snowcones, or whatever. You could also use the same code to boost a Stat with potions for Sea fighting, Monster Level for Sliming, or whatever.

Code:
## Buffs Item Find in Turns*10.
void main( int numTenTurns )
{
  ## If we don't have enough Polka Pops, buy more.
  if ( item_amount( $item[Polka Pop] ) < numTenTurns )
  {
    buy( numTenTurns - item_amount( $item[Polka Pop] ), $item[Polka Pop] );
  }
  use( numTenTurns, $item[Polka Pop] );


  if ( item_amount( $item[Knob Goblin eyedrops] ) < numTenTurns )
  {
    buy( numTenTurns - item_amount( $item[Knob Goblin eyedrops] ), $item[Knob Goblin eyedrops] );
  }
  use( numTenTurns, $item[Knob Goblin eyedrops] );



  if ( item_amount( $item[Love song of disturbing obsession] ) < numTenTurns*2 )
  {
    buy( numTenTurns*2 - item_amount( $item[Love song of disturbing obsession] ), $item[Love song of disturbing obsession] );
  }
  use( numTenTurns*2, $item[Love song of disturbing obsession] );
}


2) Next up is an auto-selling function. In this case, it sells a bunch of stuff that I farmed from the Sea in order to make money with. I am poor, after all. You can easily adapt this script to automatically deal with certain items that you encounter on a regular basis. For example, if Castle-farming, you can mall-sell certain items, auto-sell some of them, or pulverize some.

BIG NOTE: Mafia already has the ability to designate items as 'junk', or 'sellable'. I haven't figured it out yet though... Plus this is easier and quicker for me to control.

a) First up, I figure out how many Slimy Chests I have with item_amount. I then use all of that item. NOTICE the usage of 'cli_execute("command"); I COULD have used what I did in the previous script, which is use(X,$item[Slimy chest]); This would have been simpler. But you learn more this way!

b) You will notice that I used a compound statement to execute the cli_execute command. I took 'use ' then added the number of items I had (lets say 9) , then added ' Slimy Chest'. So the command executed was 'use 9 Slimy chest', when put together. This is handy for opening container-like-items automatically.

c) The cli_execute will run ANY command you could run from the CLI Graphical Interface. You can use the links I've given you at the top of the guide to find a complete list. OR, in the CLI, type /help for a full list. Anything you can do there, you can automate in this way by cli_execute!

d) The next thing is that I want to sell my EXTRAS. What I do is figure out how many of an item I have, then if I have more than X amount, I sell the difference. Once again, I use cli_execute instead of a normal ash script command. This is good for when you want to keep a reserve of a particular item, but don't want them to pile up into the hundreds.

e) The next thing you see is where I sell all of a particular item. Due to extreme laziness, I simply script to mallsell 99 of each item that I want to ditch. It will put UP TO 99 of each into the store with no complaint. Obviously this is less precise, but it does work...and it is very quick and easy.

f) The final command is to 'undercut'. This actually DOES work after all. However Mafia can only see the FIFTH CHEAPEST PRICE. Therefore it sets the price pretty low, but rarely the true lowest price. You can skip this command it desired and just set prices yourself. That's what I wind up doing anyways.

Code:
void main()
{
  ## Use any slimy chests first.
  if ( item_amount( $item[Slimy chest] ) > 0 )
  {
     cli_execute("use " +item_amount($item[Slimy chest]) +" Slimy chest");
  }

  ## Sell Spare Seaweed
  if ( item_amount( $item[Seaweed] ) > 10 )
  {
     cli_execute("mallsell " +(item_amount($item[Seaweed]) -10) +" Seaweed");
  }

  ## Sell Spare Sand Dollar
  if ( item_amount( $item[Sand dollar] ) > 20 )
  {
     cli_execute("mallsell " +(item_amount($item[Sand dollar]) -20) +" Sand dollar");
  }

  ## The Sea Fruits
  cli_execute("mallsell 99 sea tangelo");
  cli_execute("mallsell 99 sea honeydew");
  cli_execute("mallsell 99 Sea lychee");
  cli_execute("mallsell 99 sea radish");
  cli_execute("mallsell 99 sea avocado");
  cli_execute("mallsell 99 sea carrot");
  cli_execute("mallsell 99 sea cucumber");

  ## Other Sea-Related Crap.
  cli_execute("mallsell 99 Flytrap pellet");
  cli_execute("mallsell 99 Pufferfish spine");
  cli_execute("mallsell 99 Dragonfish caviar");
  cli_execute("mallsell 99 Slab of sponge");

  ## Octopus Spade, if more than 1.
  if ( item_amount( $item[Octopus spade] ) > 1 )
  {
     cli_execute("mallsell " +(item_amount($item[Octopus spade]) -1) +" Octopus spade");
  }

  ## Straw Hat, if more than 1.
  if ( item_amount( $item[Straw hat] ) > 1 )
  {
     cli_execute("mallsell " +(item_amount($item[Straw hat]) -1) +" Straw hat");
  }

  ## Auto reprice the stuff I just added, that is at 999999999.
  cli_execute("undercut");

}
 
Last edited:
3) This script is another buff script. However, we increase the complexity by using a buffBot and we also show you how to wait for an effect to occur. This particular script is for reducing combat frequency.

a) Note the use of void main to input how many tens-of-turns to buff.

b) You've seen the code to buy a certain amount of an item before and use it.

c) Note the usage of the buffBot! You can use this with your guild's bot. I obviously have mine hardcoded based on information about that particular bot. In this case, it gives me the Sonata of Sneakiness.
Bonus) You can only have 3 songs going. So an extra step might be to first attempt to shrug off a third song that might interfere with the buff process. For example, you might get rid of an unneeded Ode to Booze.

d) As a Disco Bandit, I can use a skill to reduce my combat frequency. Note the syntax of using one of your innate skills.

e) The print("xx"); statement is great for showing information to the user in a script.

f) Finally, note the have_effect() function. It tests to see if your character has a specific buff/debuff. If so, the result is the number of turns left of having it. If not, it returns 0. In any case, you can see the easy true/false test method is to check for turns of buff greater than 1 (for true), or less than 1 (for not having the buff).

g) You also see the Repeat/Until loop going too. Note the refresh_status is necessary and is similar to clicking the refresh button in Mafia. This is needed when you are waiting for outside events to occur such as messages and other-player's buffs.

h) You can adapt the if <not status>, wait until status OK loop for your own purposes. NOTE: If the buff fails to work (say you already have 3 songs!), then you are STUCK IN AN INFINITE LOOP! Hence, I strongly suggest you remind yourself by adding a print statement beforehand, so you can 'abort' if needed.

Code:
## Lower Combat as much as possible.
void main( int numberOfTurnsInTens )
{
  ## Chunks are cheaper than Deoderant.
  if ( item_amount( $item[Chunk of rock salt] ) < numberOfTurnsInTens )
  {
    buy( numberOfTurnsInTens - item_amount( $item[Chunk of rock salt] ), $item[Chunk of rock salt] );
  }
  use( numberOfTurnsInTens, $item[Chunk of rock salt] );

  ## Sonata of Sneakiness
  cli_execute("csend 23 meat to KolaBuff");

  ##Smooth Movement
  use_skill( numberOfTurnsInTens , $skill[Smooth Movement] );

  print("Done... we're just waiting for the buff to affect us");
  print(" you can type 'abort' if its taking too long");
  if(have_effect($effect[Sonata of Sneakiness]) < 1)
   repeat {wait(5); refresh_status();}
   until (have_effect($effect[Sonata of Sneakiness]) > 1);

}


4) We are putting a lot of stuff we learned together for this next one. It is a script you would run right before logging out for the day. It automatically does all the stuff that you probably want to do before logging out. We will learn a few new things here, but you know most of it already.

a) We've seen the buffBot and Wait code already. In this case, we want to have Ode to Booze readied BEFORE we drink our nightcap!

b) For a moxie player with Superhuman Cocktail, you can improve components. You always wanna use all 10 usages per day. Note the stills_available() function. I then buy some basic booze if needed, then use create() to make the appropriate upgrade to that booze. You can change this to whatever booze/fruit improvement you wish.

c) You can see my lame PvP script. A better alternative is probably to say, "IF i have any attacks remaining, Print a warning to the user and then Abort". I figure that if I am ready to logout, I don't want to mess with PvP.

d) So I actually cobbled enough meat (thanks to Crimbo) to buy a Libram! I want to be sure to use up any remaining mana to use the Libram...especially if I have forgotten to use it at all that day!

I use a new loop, the While loop. As long as my MP is enough to cast the Love Song, then I cast it.

Bonus) A smart thing to do here is to include usage of any 'per day' MP restores. I don't actually HAVE any at the moment, but Nunnery MP regen, VIP clan key, and whatever other stuff that hasn't been used up already could be used. You would do so by adding another while loop most likely that says, "While you still have a way to restore your mana for free, do so, then Do the Libram summon loop".


f) Note how you change outfits. This requires you to have previously saved a specific custom outfit called 'TimeGainer', by equipping items that give more PvP or Adventures per day. Changing outfits is super helpful and you can use this command to great effect. Obviously, name it whatever you'd like.

g) Note my comment below the change outfits. You can simply 'maximize adv' to make Mafia auto-outfit with you to max out adventure gains. I'd save off a specific outfit instead though as I combine both PvP and adventures. But the Maximize call can be pretty handy... lets say you are making a Hobopolis script. Being able to Maximize a particular resistance can be really handy.

h) At the very end, I overdrink my nightcap cocktail. I ASSUME I am at right under maximum drunkenness. Therefore I don't do any checks. Also note that a DRINK command probably won't work. Mafia will prevent you from overdrinking unless you specifically override that preference with the Overdrink command. Note that I overdrink at the END of the script, since you are basically done once you are drunk.

i) You can always add whatever else you want for a logout script like this. Make reminders to use up your 1/day stuff, and abort the script if you have not. Maybe you want to summon a demon every day and either want to do it automatically or warn you if you have not done so. KolMafia breakfast can handle most of this stuff for you though.

j) Finally, if you wanted you could go back to the Breakfast tab and include this as your new 'logout script'. When you logout of KolMafia, it would first run this script before quitting. I prefer to run it manually, but you can certainly automate it if desired. (see our Breakfast Lesson above for details)

Code:
void main ()
{
  #### Obtain Ode to Booze for nightcap.
  ## You will want Ode first thing in the morning anyways right?
  ## Modify by sending the right meat amount to your buffBot of choice.
  cli_execute("csend 1 meat to KolaBuff");

  ## Wait for the buff to appear.
  if(have_effect($effect[Ode to Booze]) < 1)
   repeat {wait(5); refresh_status();}
   until (have_effect($effect[Ode to Booze]) > 1);


  #### Improve any spirits at the still.  If you can't do so, it ought to continue on.
  ## How many uses of the still are left?
  int stillsLeft = stills_available();

  ## If we don't have enough, go buy some of the basic booze.
  if ( item_amount( $item[bottle of sake] ) < stillsLeft)
  {
    buy( stillsLeft - item_amount( $item[bottle of sake] ), $item[bottle of sake] );
  }

  ## Now, create the upgraded Spirit:
  create(stillsLeft, $item[bottle of Pete's Sake]);


  #### Did I forget to PvP? If I forgot, I probably just wanna do it the easy way.
  cli_execute("flowers");


  ## Use my libram.
  ## MP cost increases each time, so we have to recalculate in a loop.
  while( my_mp() >= mp_cost($skill[Summon Candy Hearts]) )
  {
	use_skill(1, $skill[Summon Love Song]);
  }

  #### Need to change outfits to equip my +adventures/PvP items.
  ## Note we do this after the Libram thing so we don't lose any MP thru equipping.
  outfit("TimeGainer");

  ## NOTE: You could also do a cli_execute("maximize adv"); if you don't have a specific outfit saved.

  #### Get and drink our nightcap.
  if ( item_amount( $item[White canadian] ) == 0)
  {
    buy( 1 , $item[White canadian] );
  }

  ## The overdrink command is used, as otherwise Mafia's overdrink protection would prevent drinking.
  cli_execute("overdrink White canadian");


  #### Todo:  Check your nun usage or other 1/day stuff not covered during breakfast.
  print("Done!");
}
 
Last edited:
5) Alright, here it is! This is a real live auto-adventuring, turn-burning script. This is my simple version of an automatic SlimeTube script for beginning slime players. There are more complex ones out there, but I wanted less complexity and more control.

a) Don't freak. This script is a big one! But we will break it down.

b) Note that I put my void main() statement IN THE MIDDLE. The reason is because I introduce Subroutines. I define my OWN functions that I call. As such, these must be defined before I use them in the main method!

c) Before that, I define a MAP. This variable is used to help me figure out slime damage that will be taken. Note that it is defined OUTSIDE any function!

d) Look at slime_damage. It figures out how much raw damage we will take based on being Covered in Slime for X turns.
We use the standard 'figure out an effect', but this time we store off exactly HOW MANY TURNS of the effect I have. The Slime < 1 line is because if unslimed, you will get a new coat of Sliming.
Then, I find the Slime Factor based on the turns of slime left. Basically, I have a number between 1 and 10. I feed it to the slime_percentage MAP and it returns a decimal number. I multiply it by my MAX HPs to determine the raw damage that will be taken.

e) Look at CleanupTime. It tries to use the Chamois bucket to clean me. It returns a boolean whether it worked or not.

f) Time for the main function. I have 3 inputs. How many turns to adventure, when I should use a Chamois(based on how much damage Ill take), and how low my HPs can get before I abort.

g) First, I tweak the # of adventures to reflect reality. They might type in 500 turns, but if they only have 150 then we will modify the number accordingly. Similarly, an input of 0 means to use all remaining adventures.

h) Now I have this giant While loop. I keep doing whats inside until we run out of adventures OR have executed how ever many cycles that they wanted done.

i) First, I check current HPs before adventuring. If they are too low, we abort.

j) Next, I call my own functions. First I figure out how much slime damage I am expected to take. (NOT including resistances!). If its more than Max HPs, I abort.

k) Same deal, except I compare slime damage vs the tolerence. I like this function. If you have 1800HPs, you probably don't want to eat 1700 on slime! It wont kill you, but that is expensive to recover from.

l) Now, I check slime damage vs current HP. If for some reason your Slime damage tolerence is high, but your HPs get too low and your abort-clause is too high, you need to be cleaned so you don't get killed.

m) In all cases, I call the cleanup() method that I made myself to try to use a chamois.

n) After all those checks, I go ahead and do 1 adventure in that location. Stuff to note:
i.) It will use YOUR custom combat script to fight! Make sure it is set right.

ii.) It will use YOUR 'Adventure location Choices' for non-combat (tickle uvula, etc) adventures. Make sure the right choices are set for the slimeTube. (do this by selecting Slime Tube as your location under the 'Adventure' tab, and click the Choices tab.)

o) You see that some non-combat adventures might not actually consume an adventure. Therefore before doing the adventure I save off a temporary counter. After the adventure I compare the pre-adventure count with the post-adventure count, and that way I know whether to increment the main adventure counter or not.


Code:
 ## These indicate percent of damage taken by Covered in Slime, by turns-remaining.
 float[11] slime_percent;
 slime_percent[0] = 0;
 slime_percent[1] = 5.334167;
 slime_percent[2] = 4.001677;
 slime_percent[3] = 2.9025;
 slime_percent[4] = 2.016667;
 slime_percent[5] = 1.325;
 slime_percent[6] = .805833;
 slime_percent[7] = .4391667;
 slime_percent[8] = .200833;
 slime_percent[9] = .066667;
 slime_percent[10] = .01;

int slime_damage()
{
  int slimeTurns = have_effect($effect[Coated in Slime]);
  if (slimeTurns < 1)
  {
    slimeTurns = 10;
  }

  int slimeDmg = my_maxhp() * slime_percent[slimeTurns];
  print("Calculated slime dmg = " +slimeDmg);
  return slimeDmg;
}

boolean cleanupTime()
{
 visit_url( "clan_slimetube.php?action=chamois" );
 if ( have_effect( $effect[Coated in Slime] ) > 0 )
 {
   ## Something must have gone wrong.
   return false;
 }
 print ("Slime cleaned with Chamois");
 return true;
}

void main (int howManyTurnsToAdventure, int howManyHPsToLoseBeforeChamois,
int whatHPlevelToAbortScriptAt)
{
 ## Keep track of how many adventures we have done.
 int adventureCounter = 0;

 ## Adjust desired adventures:  If 0 OR not enough adv left, use them all.
 if( howManyTurnsToAdventure < 1 ) howManyTurnsToAdventure = my_adventures();
 if( howManyTurnsToAdventure > my_adventures() ) howManyTurnsToAdventure = my_adventures();

 ## The main loop.
 while( my_adventures() > 0 && (howManyTurnsToAdventure-adventureCounter) > 0 )
 {
   ## Check current HPs vs the script abort level.
   if (my_hp() <= whatHPlevelToAbortScriptAt)
   {
     print("Your HPs are below your whatHPlevelToAbortScriptAt");
     print("You might want to use a chamois to clean yourself!");
     abort();
   }

   ## This checks slime dmg vs your MAX HPs. (If you wanted to add auto-heal code.)
   if( slime_damage() >= my_maxhp() )
   {
     print ("Expected slime dmg is more than your MAX HP!");
     if (!cleanupTime())
     {
       abort("Couldn't clean. Check Chamois bucket");
     }
   }

   ## This checks slime dmg vs CURRENT HPs.
   ## Regardless of your tolerence, you need to stop the slime damage.
   if ( slime_damage() >= howManyHPsToLoseBeforeChamois)
   {
     print ("Expected slime dmg is more than your tolerence.");
     if (!cleanupTime())
     {
       abort("Couldn't clean. Check Chamois bucket");
     }
   }

   if ( slime_damage() >= my_hp() )
   {
     print ("Expected slime dmg is more than your current HPs");
     ## IF You want to add the ability for this script to heal yourself,
     ## This would be a great place for it.
     if (!cleanupTime())
     {
       abort("Couldn't clean. Check Chamois bucket");
     }
   }
   
   int temporaryAdvCounter = my_adventures();

   ## Use a single adventure. Note, non-combat MAY NOT use an actual adventure.
   adventure( 1 , $location[The Slime Tube] );

   ## See if that adventure actually took an adventure.
   if (temporaryAdvCounter > my_adventures())
   {
     ## Our adventures decreased. Therefore this did take an adventure.
     adventureCounter = adventureCounter + 1;
   }

   print ("Ok, done with adventure " +adventureCounter +" of " +howManyTurnsToAdventure);
 }
}
 
Last edited:
6) Other Handy Commands:

Note that you can type 'ashref' into the CLI for a COMPLETE list of all ash script commands! It is kind of cumbersome to dig through the list though. You can narrow it down by asking about a particular command. i.e. 'ashref fullness' would list all functions (like my_fullness) that match 'fullness'.

a) use_familiar(familiar);
This one is tricky! The function takes a 'Familiar' type, and will error when you feed it a string. Therefore you must combine the to_familiar with this one. It looks like this:
use_familiar(to_familiar("leprechaun"));
Be sure to use the RACE of the familiar, not your name for it.

b) my_fullness()
my_inebriety()
These return your fullness and drunkenness as 'int's.

c) my_basestat($stat[Moxie])
Returns your Moxie stat as an 'int'.
Replace with Muscle or Mysticality as needed.

d) equip(item);
Another tricky function in that it only takes an "Item". Syntax is:
equip(to_item("nameOfItem"));

e) mall_price($item[bottle of Pete's Sake]);
Returns the mall price as an 'int'.
NOTE!!! Returns the FIFTH LOWEST PRICE, not the lowest.
When you buy, it uses the lowest. But KoL only allows KoLMafia to return the 5th lowest for analysis.

f) have_skill( $skill[ Summon Candy Heart ] );
Return true or false if you have skill.

g) set_property( "customCombatScript" , "YourScriptNameHere");
Lets you set a particular custom combat script. Great for setting up stasis-lock (where you delay combat so your familiar can act during combat).

h) TODO: Figure out a general purpose method on how to do non-combat location visiting with the mini-browser and determining your URL. i.e.:
visit_url("monkeycastle.php?pwd&action=buyitem&whichitem=3997&quantity=1");



CLOSING:
---------
Hopefully this quick scripting lesson gives you the tools and confidence to make your own .ash scripts. You should be able to cut&paste quite a bit from my examples to assemble what you need. When you are trying to do stuff that I don't show, I recommend that you first check the links I gave you. All the CLI commands are easily found from /help. The ASH COMMANDS are found by typing 'ashref'. Another option is to go find a similar script and then figure out the commands they used. (Ya think I dreamed up all that slime script on my own? Uh, no. :) Finally, the people at the KolMafia forum are pretty nice. You can simply ask reasonably intelligent-sounding questions and you are likely to get fast responses.

At the very least, you will be a bit less intimidated when opening one of those monster scripts from the KolMafia Repository forum! You can kind of see what they are doing, then modify it as you see fit. Many of those scripts are excellent, but are a bit much and do stuff I don't want them doing. Heck, one of the scripts actually plays the ENTIRE FRIGGIN game for you! Just click the script button every day until you have ascended. I'm all for automating repetitive stuff, but that is way overkill for me!

Good luck, brand new KoLMafia users and scripters! Feel free to kmail me if you have questions or comments about the guide, keeping in mind that I am kind of a noob myself. :)

-- SinginSally (KoL character is the same name... (note, only 1 G in singin )
 
Last edited:

Bale

Minion
While there are a few points in this guide that could be improved, I whole heartedly endorse this product. This fills a long empty gap in helping new users to learn to use Mafia. Aprocalypse's guide on the Kol Forums is very nice, but not really as newbie friendly.

I sent a few PMs of suggestions to help improve the guide. Sorry SinginSally if you think I was clogging up your inbox. ;)
 
Bale, thanks for the advice. I havent gotten to it yet, but before I dive in, I wanted to say that I appreciate your assistance both now and in the past while I've been trying to learn!
 

Camber

Member
Shouldn't we 'Sticky' this? Or, maybe also, add it to the wiki? It is a good intro to KolMafia. I have had problems getting people started on Mafia, and this is a great reference tool.

Thanks SinginSally!
 

slyz

Developer
Great work SinginSally, I'll definitively be passing around a link to this.

Should I wait until you add Bale's suggestions to add a couple of my own?
 
Top