KoL Scripting Resources

Introduction

Why script KoL?

When the Kingdom of Loathing (KoL) was first created, it was designed to be a game you could play during your coffee break. Each day you have 40 adventures, and you can spend them fighting Knob Goblins or Fiendish Cans of Asparagus or crafting advanced cocktails. At this point, however, KoL has evolved into a game of enormous scope. You may have thousands of turns to play in a day. You may have hundreds of resources to use. For many players, it is impractical to try to do everything by hand.

If you’re reading this, you probably already use KoLMafia. It’s a fantastic tool to help play turns quickly and efficiently. With scripts written in ASH or JavaScript, you can have KoLMafia make gameplay decisions for you and execute them: you can automate adventuring, inventory management, and even KMails. Hell, you’ve probably already used some scripts – autoscend and garbage collector are two popular scripts that we here at LASS produce, and there are dozens of other scripts that help automate play, simplify resources, and make the game a better experience for everyone.

But everyone’s specific needs and goals are different. It’s likely that there’s something you want to do in KoL that isn’t currently supported by a script. Maybe you have a great idea for improving an existing script, or maybe you need to automate a task that no one has a public script that does. Whatever you need to do in this game, there’s probably a way to make it better through scripting.

What are the tools and resources available for scripting KoL?

There are a number of useful resources you should leverage as you start learning about scripting in KoL:

ASH & Javascript

These are the two primary ways you’ll be scripting in KoLMafia. What are they?

The two languages are similar, but have some different syntax quirks. To demonstrate, here are some basic, one-line KoL tasks that you might do in ASH or JS:

Syntax ASH Javascript
Look up an item $item[squirming slime larva] Item.get("squirming slime larva")
Restore MP restore_mp(69) restoreMp(69)
Buy a Big Rock buy(1, $item[big rock]) buy(1, Item.get("big rock"))

To test any of these, you can simply run them in the GCLI. For example:

image

These are all relatively similar, but differences in syntax and structure become more pronounced as scripts get more complicated. Here are two examples of a more complex task: returning all one-handed weapons that you have, sorted by familiar weight.

In Javascript, this would look like:

Item.all()
  .filter((item) => availableAmount(item) > 0 && weaponHands(item) === 1)
  .sort(
    (a, b) =>
      numericModifier(b, "Familiar Weight") -
      numericModifier(a, "Familiar Weight"),
  );

In ASH, the same task would look like this:

item[int] weapons_by_fam_lbs;		//our desired output
int count;			        //how many items meet our criteria? will be used as the key

//first we want to go through all items and list those who meet our requirement
foreach it in $items[]	//go through all items one by one
{
	//skip an item if it fails our criteria
	if(available_amount(it) == 0 || weapon_hands(it) != 1) continue;
	weapons_by_fam_lbs[count] = it;
	count++;
}
//next we sort and print our list
sort weapons_by_fam_lbs by numeric_modifier(value,"Familiar Weight");
foreach it in weapons_by_fam_lbs {print(weapons_by_fam_lbs[it]);}

Both ASH and JS have their own use cases and value in the KoL scripting world.