Difference between pages "Talk:Data Structures" and "KoLmafia Guide: Preface"

From Kolmafia
(Difference between pages)
Jump to navigation Jump to search
 
m (Whoops necro edit. Sorry)
Tag: Undo
 
Line 1: Line 1:
−
==To Do==
+
== How I Teach & Requirements ==
−
We really should consider moving things like Veracity's guide to Maps either to the wiki or to GitHub.
 
−
--[[User:Mcroft|Mcroft]] ([[User talk:Mcroft|talk]]) 21:40, 4 July 2023 (UTC)
 
−
==Records==
 
−
I thought that the Records section would've been helpful in figuring out multidimensional maps -- maybe not; Veracity might've gone a bit too far with that example (which I understand, as she was trying to cover all her bases with one single unifying example). --[[User:Heeheehee|Heeheehee]] 06:42, 10 March 2010 (UTC)
 
  
−
==An attempt at explaining maps==
+
I have only played KoL for 3 months. (well, more like 7 now!) I am hoping this means that I will not take stuff for-granted like year-long players. I can actually address more advanced stuff now that I know how clan dungeons work, the Sea, and so forth. ;-)
−
(by [[User:Grotfang|Grotfang]])
 
  
−
A map consists of two types of component.
+
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.
−
* The key
 
−
* The value
 
−
A normal map (without using a record) can have multiple keys, but only one value. A map is formed by specifying a normal datatype for the value and including a key, then giving the map a name:
 
  
−
<pre>datatype [key] name;</pre>
+
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.
  
−
Eg.
 
−
<pre>string [int] message;</pre>
 
  
−
This in itself is a useful feature, but there are many situations where you may wish to associate two values. For example, in the message map above, I may wish to specify both a message and a name to send it to. There are two ways I could deal with this problem. The first would be to create a second map with a corresponding key. I could then assume that message[key] should be send to recipient[key]. While this works, it is inefficient and untidy, as well as inflexible.
+
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.
  
−
Mafia supports the ability to customise maps using record. Record tells mafia what each entry in a map means, thereby enabling us to have more than one value to the map. The best way to visualise maps is to see a row on a page:
+
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.
  
−
<pre>key  value</pre>
+
== What About Greasemonkey? ==
  
−
We can extend our keys already by specifying multiples:
+
Greasemonkey is another scripting tool that can be used for Kingdom of Loathing.  Please skip this section if you don't know or care about Greasemonkey.
  
−
<pre>value [key1 , key2] name;</pre>
 
  
−
Produces:
+
I tried Greasemonkey scripts. They are nice, but have four major disadvantages:
  
−
<pre>key1  key2  value</pre>
+
* CodeRot - Many scripts are outdated and their functionality continues to break due to new content, changes, etc.
  
−
What record lets us do is add more values:
+
* 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.
  
−
<pre>key  value1  value2</pre>
+
* 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.
  
−
Each line in a record is the next value and has to include the datatype of that value. Before we specified the value's datatype when we named the map (since there was only one value to assign a datatype to). Now we have to make a record of ALL the datatypes that will come up, and then when we make our map we will use the record name in place of a single datatype:
+
* 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.
  
−
<pre>record kmailer{
 
−
  string message;
 
−
  string recipient;
 
−
}
 
−
kmailer [int] my_messages;</pre>
 
  
−
The example above creates the following map:
+
I decided to try KoLmafia which has these advantages:
  
−
<pre>key  value1    value2
+
* More Secure - It comes from ONE open-source website and its base version includes plenty of functionality. This makes it much safer to use out of the box.
−
int  message  recipient</pre>
 
  
−
So far, so simple. The next bit is where it gets interesting. We can no longer assign a value to the map as a whole. Without a record, we can do the following:
+
* 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...)
  
−
<pre>string [int] message;
+
* 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.
−
message[1] = "Hi there!";</pre>
 
  
−
This makes the string "Hi there!" our value for key = 1:
+
* Consolidated Updates - All KoLmafia work occurs at its GitHub 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.
  
−
<pre>key  value
+
* 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.
−
1  Hi there!</pre>
 
  
−
With a record, we can no longer assign a value to a key alone; we have more than one value and we need to specify which one it is we want to assign something to. So using the record above, to assign a message we would have to do the following:
+
== Links ==
  
−
<pre>record kmailer{
+
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.
−
  string message;
 
−
  string recipient;
 
−
}
 
−
kmailer [int] my_messages;
 
−
my_messages[1].message = "Hi there!";
 
−
my_messages[1].recipient = "Grotfang";</pre>
 
  
−
Both values are assigned to our "1" key, but we must specify the value we are assigning. The following details what is going on in the map:
+
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!
  
−
<pre>key  value1  value2
+
*KoLmafia on GitHub: https://github.com/kolmafia/kolmafia<br />
−
int  message  recipient
+
*KoLmafia forum: http://kolmafia.us/<br />
−
1  Hi there!  Grotfang</pre>
+
*KolMafia Wiki: http://wiki.kolmafia.us/index.php?title=Main_Page<br />
 +
*A Previously Existing Guide: http://forums.kingdomofloathing.com/vb/showthread.php?t=140340<br />
 +
*List of CLI Commands http://kolmafia.sourceforge.net/scripting.html<br />
 +
*List of all KoLmafia global variables (more for scripting): http://wiki.kolmafia.us/index.php?title=List_of_KoLmafia_Properties<br />
  
−
===Multiple Keys===
 
  
−
This is more complex. Maps with single keys are easy to understand how they will return - specify the map and key and you return the value (you need to specify which value you want if you use a record, but the principle is the same).
+
== Getting Started ==
  
−
More than one key is where maps get truly interesting. To all extents and purposes, multiple keys tend to be a way to categorise data into groups and subgroups. The return values get more complicated, though.
+
We are now officially starting your KoLmafia lessons!
  
−
Whenever you add a value to a map, all keys MUST be specified. However, when you are retrieving data this is not the case. This works best with an example:
+
# Download the latest build from [https://ci.kolmafia.us KoLmafia's Build Server]
 +
# 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.
 +
# Move the file somewhere handy. Note that KoLmafia can be downloaded as an executable. However, it does '''not install''' per se.  Instead, I like to say that it 'roots'.  When executed, '''will create quite a few subfolders''' to store its settings. 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. . You just run the file to run KoLmafia. No further setup is needed.
 +
# 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.
 +
# 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.
 +
# 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! ;-)
 +
# Note that is possible that KoLmafia '''may pop up an events logger window'''.  This occurrs if you were attacked, received a message, or whatever other event type stuff might happen.  Just close that small window if you encounter it.
  
−
<pre>string [string , string] my_map;
 
−
my_map["a","b"] = "ab";
 
−
print(my_map["a","b"]);</pre>
 
  
−
This returns:
 
  
−
<pre>ab</pre>
+
'''Continue''' to [[KoLmafia Guide: Basics (Relay Browser)|Lesson 1: Basics (Relay Browser)]]
  
−
The map setup is:
+
[[Category:KoLmafia Guide]][[Category:New User Help]]
−
 
 
−
<pre>key1  key2  value
 
−
a      b      ab</pre>
 
−
 
 
−
As you might expect. Here we specified a map with two keys and one value. We assigned a value "ab" to the combination of key1 ("a") and key2 ("b"). When we retrieved the value for that combination, we got "ab". So far, so unsurprising.
 
−
 
 
−
However, the natural question arises, what if we try to retrieve a value while only specifying one of the keys? The answer is that we need to change our perspective of the map to what I suggested earlier - that of groups and sub-groups.
 
−
 
 
−
The way I visualise this is to imaging key1 represents a group and key2 is a subgroup. If two map entries have the same key1, then you should perceive them as having some commonality. What happens when you retrieve using key1 only is that you return a map of all the map entries that have the specified value of key1. This means (as you are returning an aggregate) you need to specify a new map for the values to be placed in. The following example illustrates this:
 
−
 
 
−
<pre>string [string , string] my_map;
 
−
my_map["a","b"] = "ab";
 
−
my_map["b","c"] = "bc";
 
−
my_map["b","d"] = "bd";
 
−
my_map["c","d"] = "cd";
 
−
my_map["e","f"] = "ef";
 
−
 
 
−
string [string] my_map2 = my_map["b"];
 
−
 
 
−
foreach x in my_map2 {
 
−
  print( my_map2[x] );
 
−
}</pre>
 
−
 
 
−
The output is:
 
−
 
 
−
<pre>bc
 
−
bd</pre>
 
−
 
 
−
The setup for my_map is:
 
−
 
 
−
<pre>key1  key2  value
 
−
a      b      ab
 
−
b      c      bc
 
−
b      d      bd
 
−
c      d      cd
 
−
e      f      ef</pre>
 
−
 
 
−
The setup for my_map2 (containing only entries that have "b" as key1) is:
 
−
 
 
−
<pre>key  value
 
−
c      bc
 
−
d      bd</pre>
 
−
 
 
−
As you can see, my_map["a","b"], which has "b" as key2 is NOT included in the aggregate return. The more keys, the more level of control you have, but you cannot return (I don't think) a map of key1 that shares key2. It's a one-way structure. Of course, you could work around this with a new map that had the keys in reverse.
 

Latest revision as of 18:33, 8 August 2023

How I Teach & Requirements

I have only played KoL for 3 months. (well, more like 7 now!) I am hoping this means that I will not take stuff for-granted like year-long players. I can actually address more advanced stuff now that I know how clan dungeons work, the Sea, and so forth. ;-)

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.

What About Greasemonkey?

Greasemonkey is another scripting tool that can be used for Kingdom of Loathing. Please skip this section if you don't know or care about Greasemonkey.


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

  • CodeRot - Many scripts are outdated and their functionality continues to break due to new content, changes, etc.
  • 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.
  • 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.
  • 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:

  • More Secure - It comes from ONE open-source website and its base version includes plenty of functionality. This makes it much safer to use out of the box.
  • 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...)
  • 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.
  • Consolidated Updates - All KoLmafia work occurs at its GitHub 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.
  • 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.

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!


Getting Started

We are now officially starting your KoLmafia lessons!

  1. Download the latest build from KoLmafia's Build Server
  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 can be downloaded as an executable. However, it does not install per se. Instead, I like to say that it 'roots'. When executed, will create quite a few subfolders to store its settings. 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. . You just run the file to run KoLmafia. No further setup is needed.
  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.
  6. 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! ;-)
  7. Note that is possible that KoLmafia may pop up an events logger window. This occurrs if you were attacked, received a message, or whatever other event type stuff might happen. Just close that small window if you encounter it.


Continue to Lesson 1: Basics (Relay Browser)

Retrieved from "https://wiki.kolmafia.us/index.php?title=Talk:Data_Structures&oldid=9224"