Map Guide

A Noob's Guide to Maps

Maps are probably one of the hardest ASH concepts to understand. Hopefully this little guide will make them more understandable.

Introduction: The Beginnings
First, when talking about maps and keys, we are not talking about items in Kingdom of Loathing (something I originally thought when I first read about them), but rather they refer to a concept of storing data or information in an ASH script.

A map is made up of two parts, its key(s) and their respective values. A map can have any amount of keys, but only 1 value. Also, keys will always be unique from one another. To understand this, lets take the simplest type of map, a map with 1 key each giving a value and lets use the following analogy of keys and doors.

Example 1: The Basics

You have a blue key, it opens door #1, and inside you find a healing potion.
You have a green key, it opens door #2, and inside you find 10 gold.
You have a red key, it opens door #3, and inside you find a healing potion.

The example above could be condensed to:

[Blue Key] = Healing potion;
[Green Key] = 10 gold;
[Red Key] = Healing potion;

Converting this into ASH, it would look like:

//Example 1
//First Define the Map
string[string] Door;
//Assigning the map
Door["Blue Key"] = "Healing Potion";
Door["Green Key"] = "10 gold";
Door["Red Key"] = "Healing Potion";
//Output
print("The Door that uses the Blue Key gives you "+Door["Blue Key"], "blue");

This will print, "The Door that uses the Blue Key gives you Healing Potion".

Example 2: Unique Keys:
Remember that keys must be unique to what they are assigned too. For instance, you can not have a blue key give a Healing Potion and 10 Gold.

//Example 2
//First Define the Map
string[string] Door;
//Assigning the map
Door["Blue Key"] = "Healing Potion";
Door["Green Key"] = "10 gold";
Door["Red Key"] = "Healing Potion";
Door["Blue Key"] = "10 gold";
//Output
print("The Door that uses the Blue Key gives you "+Door["Blue Key"], "blue");

This will print, "The Door that uses the Blue Key gives you 10 gold".

The new loot item overrides the previous item it used to give. In this respect, Keys must always be unique. If you wanted the Blue Key to offer different loot types than just Healing Potions, you would have to give the Blue Key another attribute, like shape or number. The next example will have colored, numbered keys.

Example 3: Multiple Keys

You have a blue, #1 key, it opens door #1, and inside you find a healing potion.
You have a green, #1 key, it opens door #2, and inside you find 10 gold.
You have a red, #1 key, it opens door #3, and inside you find a healing potion.
You have a blue, #2 key, it opens door #4, and inside you find a machine gun.

The example above could be condensed to:

[Blue Key][#1] = Healing potion;
[Green Key][#1] = 10 gold;
[Red Key][#1] = Healing potion;
[Blue Key][#2] = Machine Gun;

Converting this into ASH, it would look like:

//Example 3
//First Define the Map
string[string][int] Door;
//Assigning the map
Door["Blue Key"][1] = "Healing Potion";
Door["Green Key"][1] = "10 gold";
Door["Red Key"][1] = "Healing Potion";
Door["Blue Key"][2] = "Machine Gun";
//Output
print("The Door that uses the Blue Key #1 gives you "+Door["Blue Key"][1]+" and Blue Key #2 gives you "+Door["Blue Key"][2], "blue");

This will print, "The Door that uses the Blue Key #1 gives you Healing Potion and Blue Key #2 gives you Machine Gun".

Example 4: Handling Large Maps
Maps can be very large, containing hundreds, thousands, or even more keys all leading to different values (or loot). Thankfully, these massive maps can be accessed with ease by using iteration (for loops). The general syntax is "foreach key in map, do_stuff(key)".

You have blue keys, #1-10, they all give Healing Potions except #2 which gives Machine Gun.
You have red keys, #1-10, they all give gold equal to 10 times their number.
You have green keys, #1-10, they all give healing potions except 5 which gives an Akii.

The example above could be condensed to:

[Blue Key][#1] = Healing potion;
[Blue Key][#2] = Machine Gun;
[Blue Key][#3-10] = Healing potion;
[Green Key][#1-10] = 10 gold*Number;
[Red Key][#1-4] = Healing potion;
[Red Key][#5] = Akii;
[Red Key][#6-10] = Healing potion;

Converting this into ASH, it would look like:

//Example 4
//First Define the Map
string[string][int] Door;
//Assigning Large Map Using For Loop
for x from 1 to 10
   Door["Blue Key"][x] = "Healing Potion";
Door["Blue Key"][2] = "Machine Gun";

for x from 1 to 10
   Door["Green Key"][x] = to_string(x*10)+" gold";

for x from 1 to 10
   Door["Red Key"][x] = "Healing Potion";
Door["Red Key"][5] = "Akii";

//Output -- Use "foreach X in map" to look at the various keys and their values.
foreach color_key, number in Door {
   if (number == 1)
      print("");
   print(color_key+" #"+number+" gives loot of "+Door[color_key][number]+".", "blue");
}

It gives the output:

Blue Key #1 gives loot of Healing Potion.
Blue Key #2 gives loot of Machine Gun.
Blue Key #3 gives loot of Healing Potion.
Blue Key #4 gives loot of Healing Potion.
Blue Key #5 gives loot of Healing Potion.
Blue Key #6 gives loot of Healing Potion.
Blue Key #7 gives loot of Healing Potion.
Blue Key #8 gives loot of Healing Potion.
Blue Key #9 gives loot of Healing Potion.
Blue Key #10 gives loot of Healing Potion.

Green Key #1 gives loot of 10 gold.
Green Key #2 gives loot of 20 gold.
Green Key #3 gives loot of 30 gold.
Green Key #4 gives loot of 40 gold.
Green Key #5 gives loot of 50 gold.
Green Key #6 gives loot of 60 gold.
Green Key #7 gives loot of 70 gold.
Green Key #8 gives loot of 80 gold.
Green Key #9 gives loot of 90 gold.
Green Key #10 gives loot of 100 gold.

Red Key #1 gives loot of Healing Potion.
Red Key #2 gives loot of Healing Potion.
Red Key #3 gives loot of Healing Potion.
Red Key #4 gives loot of Healing Potion.
Red Key #5 gives loot of Akii.
Red Key #6 gives loot of Healing Potion.
Red Key #7 gives loot of Healing Potion.
Red Key #8 gives loot of Healing Potion.
Red Key #9 gives loot of Healing Potion.
Red Key #10 gives loot of Healing Potion.

Conclusion: The End of Being a Noob
Maps are useful tools for storing and accessing information. They are broken into two components, keys and values. They can have multiple keys of the various data types KoLMafia provides, but they only give one value. The keys of a map must be unique, this means it would be a bad idea to assign a key that might be repeated. For example, it would bad practice to assign a single key map of [int] to the mall price of items, as some items could have the same price.

Lastly, maps are generally very large in size and must be iterated through using for loops. For example, using a map with a single key, one could iterate through all the key values by typing "foreach key in map, do_stuff(key)". Note: That the word "key" can be replaced with anything. Other common examples might include: it, item, value, thing, number, etc. For example, suppose you had a map where the keys were different items, you could iterate through it to find their mall price by doing "foreach it in item_map, print(mall_price(it));"

Thanks for reading and hopefully this has cleared up any confusion regarding Maps.