Difference between pages "Modifier Maximizer" and "Data Types"

From Kolmafia
(Difference between pages)
Jump to navigation Jump to search
imported>Smelltastic
 
imported>Degrassi knowles
(→‎slot: Add slots relating to cowboy boots.)
 
Line 1: Line 1:
 
{{TOCright}}
 
{{TOCright}}
 +
==Primitive Datatypes==
  
−
=Usage=
+
===void===
−
==General==
+
Can be thought of better as the absence of a datatype. No value can be assigned to '''void''' nor can a value be returned from a function of datatype '''void'''.
−
The specification of what attributes to maximize is made by a comma-separated list of keywords, each possibly preceded by a numeric weight. Commas can be omitted if the next item starts with a +, -, or digit. Using just a +, or omitting the weight entirely, is equivalent to a weight of 1. Likewise, using just a – is equivalent to a weight of -1. Non-integer weights can be used, but may not be meaningful with all keywords.
 
  
−
Numeric weights determine how much an individual keyword will be counted toward the score that Mafia assigns to each combination. For instance, "2 item drop" will force item drop to contribute four times as much as, say, ".5 meat drop" in the expression "maximize 2 item drop, .5 meat drop". The weights are simply multiplied with the corresponding modifier, so in the preceding expression, a natty blue ascot would contribute 20*.5 = 10 to your score, while a lucky rabbit's foot would contribute 2*7 + .5*7 = 17.5 to your score.
+
===boolean===
 +
A boolean value is either '''true''' or '''false'''. By default, a boolean variable is set to false.
  
−
==Numeric Modifiers==
+
===int===
−
The full name of any numeric modifier (as shown by the '''modref''' CLI command) is a valid keyword, requesting that its value be maximized. If multiple modifiers are given, their weights specify their relative importance. Negative weights mean that smaller values are more desirable for that modifier.
 
  
−
Shorter forms are allowed for many commonly used modifiers. They can be abbreviated down to just the bold letters:
+
A whole number (short for "integer"), either positive or negative (or 0).  The int used by KoLmafia is a 32-bit signed int, meaning it has a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648. The default value of a integer variable is 0.
−
<br>'''mus''', '''mys''', '''mox''', '''main'''stat, '''HP''', '''MP''', '''ML''', '''DA''', '''DR''', '''com'''bat rate, '''item''' drop, '''meat''' drop, '''exp'''erience, '''adv'''entures
 
−
<br>Also, resistance (of any type) can be abbreviated as '''res''', and damage can be abbreviated as '''dmg'''. '''all res'''istance is a shortcut for giving the same weight to all five basic elements. Likewise, '''elemental dmg''' is a shortcut for the five elemental damage types.
 
  
−
Note that many modifiers come in pairs: a base value, plus a percentage boost (such as Moxie and Moxie Percent), or a penalty value. In general, you only need to specify the base modifier, and any related modifiers will automatically be taken into account.
+
Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example:
 +
{{
 +
CodeSample|
 +
code=
 +
<syntaxhighlight>
 +
int a = 1;
 +
int b = 2;
 +
print( a / b * 2 );
 +
</syntaxhighlight>}}
 +
Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.
  
−
Finally, '''prismatic''' (dmg or res) is a derived modifier that attempts to provide a balance of all elemental types. By contrast the '''elemental''' modifier will attempt to maximize all elements, even if it means that some of the elements will get no boost at all.
+
===float===
  
−
==Limits==
+
The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3]
−
Any numeric modifier keyword can be followed by one or both of these special keywords:
 
−
<br>'''min'''&nbsp;&ndash; The weight specifies the minimum acceptable value for the preceding modifier. If the value is lower, the results will be flagged as a failure.
 
−
<br>'''max'''&nbsp;&ndash; The weight specifies the largest useful value for the preceding modifier. Larger values will be ignored in the score calculation, allowing other specified modifiers to be boosted instead.
 
−
<br>Note that the limit keywords won't quite work as expected for a modifier that you're trying to minimize.
 
−
<br>If '''min''' or '''max''' is specified at the start of the expression, it applies to the total score (the sum of each modifier value times its weight). A global '''max''' may allow equipment maximization to finish faster, since no further combinations will be considered once the specified value is reached.+
 
−
<br>The preference '''maximizerCombinationLimit''' (set with '''set maximizerCombinationLimit = 100000''' in CLi) constrains the number of combinations Maximizer will consider. Depending where it is set, this may mean you don't get the best combination, but you may well get a good enough one faster. Depending which equipment you can use, you may find a higher value than 100000 is needed.
 
  
−
==Other Modifiers==
+
When assigning to a variable of type float, one should be careful to always enter numbers in decimal form, as unwanted behavior can result from supplying a value that KoLmafia may interpret as an int type without the decimal point.
−
Boolean modifiers can also be used as keywords. With positive weight, the modifier is required to be true; with negative weight, it is required to be false. There is one shortcut available: '''sea''' requires both Adventure Underwater and Underwater Familiar to be true.
 
  
−
The only bitmap modifiers that currently appear useful for maximization are Clownosity and Raveosity, so they are allowed as a special case. The weight specifies the required minimum value; only one value is actually meaningful for each keyword, so '''4 clownosity''' and '''7 raveosity''' are the only useful forms.
+
Note that float is not infinitely precise; it intrinsically rounds off after a certain point. This loss of accuracy is for the sake of storage, but beware of the possibility of small errors compounding from multiple float types.
 +
{{
 +
CodeSample|
 +
description=For instance, try the following code as an example of how rather long post-decimal portions are handled:|
 +
code=
 +
<syntaxhighlight>
 +
float f;
 +
f = 4.9999999;
 +
print( f );
 +
</syntaxhighlight>}}
 +
The default value of a <code>float</code> variable is 0.0.
  
−
String modifiers are not currently meaningful for maximization.
+
===string===
−
==Equipment==
 
−
Slot names can be used as keywords:
 
−
<br>'''hat''', '''weapon''', '''offhand''', '''shirt''', '''pants''', '''acc1''', '''acc2''', '''acc3''', '''familiar''' (stickers and fake hands are not currently planned.)
 
−
<br>With positive weights, only the specified slots will be considered for maximization. With negative weights, all but the specified slots will be considered.
 
−
<br>'''empty'''&nbsp;&ndash; With positive weight, consider only slots that are currently empty; with negative weight, only those that aren't empty. Either way, '''+''slot''''' and '''-''slot''''' can be used to further refine the selected slots.
 
−
<br>'''hand'''ed&nbsp;&ndash; With a weight of 1, only 1-handed weapons will be considered. With a larger weight, only weapons with at least that handedness will be considered.
 
−
<br>'''melee'''&nbsp;&ndash; With positive weight, only melee weapons will be considered. With negative weight, only ranged weapons will be considered.
 
−
<br>'''type ''text'''''&nbsp;&ndash; Only weapons with a type containing ''text'' are considered; for example, '''type club''' if you plan to do some Seal Clubbing.
 
−
<br>'''shield'''&nbsp;&ndash; With positive weight, only shields will be considered for your off-hand. Implies '''1 handed'''.
 
−
<br>'''current''' - By default Maximizer considers your current equipment in Hardcore and Ronin. With -current keyword it does not, with +current keyword in aftercore it forces it to be considered. Not considering current equipment will reduce the number of combinations considered, but will sometimes mean changes of equipment are suggested even though they don't improve what you are wearing.
 
−
<br>'''equip ''item'''''&nbsp;&ndash; The specified item is required (positive weight) or forbidden (negative weight). Multiple uses of '''+equip''' require all of the items to be equipped.
 
−
<br>'''outfit ''name'''''&nbsp;&ndash; The specified standard outfit is required or forbidden. If the name is omitted, the currently equipped outfit is used. Multiple uses of '''+outfit''' are satisfied by any one of the outfits (since you can't be wearing more than one at a time).
 
−
<br>If both '''+equip''' and '''+outfit''' are used together, either one will satisfy the condition&nbsp;&ndash; all of the items, or one of the outfits. This special case is needed to be able to specify the conditions for adventuring in the Pirate Cove.
 
−
<br>'''tie'''breaker&nbsp;&ndash; With negative weight, disables the use of a tiebreaker function that tries to choose equipment with generally beneficial attributes, even if not explicitly requested. There are only a few cases where this would be desirable: maximizing '''+combat''' or '''-combat''' (since there's usually only one item that can help), '''adv''' and/or '''PvP fights''' at rollover, and '''familiar weight''' when facing the Naughty Sorceress familiars.
 
−
<br>'''effective''' - With positive weight, will choose weapons that are based on your muscle or moxie, whichever is higher. Useful for moxie classes with Tricky Knifework.
 
  
−
==Familiars==
+
A group of characters including, but not limited to: lowercase letters, uppercase characters, numbers, and various control characters. When assigning a value to a string, always enclose the desired value in either single or double quotes (note you must use the same quote type on both ends of the string assignment). If you need to include the same character inside of the string itself, you will need to escape it first with a backslash.{{CodeSample|
−
By default, the Modifier Maximizer does not recommend familiars, since there are many possible factors in choosing one beyond those that can be expressed via modifiers. However, you can request that specific familiars be compared with your current one:
+
description=For example:|
−
<br>'''switch ''familiar'''''&nbsp;&ndash; With positive weight, the familiar is added to the list to be considered (unless the player lacks that familiar, or is already using it, in which case there is no effect). With negative weight, the familiar is added to the list only if the player lacks the previously specified familiar. For example, '''switch hobo monkey, -switch leprechaun''' will only consider the leprechaun if the player doesn't have the monkey.
+
code=
−
==Assumptions==
+
<syntaxhighlight>
−
All suggestions are based on the assumption that you will be adventuring in the currently selected location, with all your current effects, prior to the next rollover (since some things depend on the moon phases). For best results, make sure the proper location is selected before maximizing. This is especially true in The Sea and clan dungeons, which have many location-specific modifiers.
+
string s = "This is my \"friend\" Pete.";
 +
</syntaxhighlight>|
 +
moreinfo=
 +
Will result in the following being stored to s:
 +
<pre>This is my "friend" Pete</pre>}}
 +
The default value of a string is an empty string, or literally <code>""</code>.
  
−
Among effects, stat equalizer potions have a major effect on the suggested boosts, since they change the relative importance of additive and percentage stat boosts. Likewise, elemental phials make certain resistance boosts pointless. If you plan to use an equalizer or phial while adventuring, please use them first so that the suggestions take them into account.
+
===buffer===
−
==GUI Use==
 
−
If the Max Price field is zero or blank, the limit will be the smaller of your available meat, or your autoBuyPriceLimit (default 20,000). The other options should be self-explanatory.
 
  
−
You can select multiple boosts, and the title of the list will indicate the net effect of applying them all&nbsp;&ndash; note that this isn't always just the sum of their individual effects.
+
Similar to a string, but more efficient in certain operations, including concatenation and passing as function arguments. For the most part, you can interchange references to strings and buffers. However, you should test all such actions first, as a few functions require a specific datatype to be supplied as a parameter. (Most notably, those listed under [[String Handling Routines#Regular Expressions|Regular Expressions]].)
−
==CLI Use==
 
−
The Modifier Maximizer can be invoked from the gCLI or a script via '''maximize ''expression''''', and will behave as if you'd selected Equipment: on-hand only, Max Price: don't check, and turned off the Include option. The best equipment will automatically be equipped (unless you invoked the command as '''maximize? ''expression'''''), but you'll still need to visit the GUI to apply effect boosts&nbsp;&ndash; there are too many factors in choosing between the available boosts for that to be safely automated. An error will be generated if the equipment changes weren't sufficient to fulfill all '''min''' keywords in the expression.
 
−
==Limitations &amp; Bugs==
 
−
This is still a work-in-progress, so don't expect everything to work perfectly at the moment. However, here are some details that are especially broken:
 
−
* Items that can be installed at your campground for a bonus (such as Hobopolis bedding) aren't considered.
 
−
* Your song limit isn't considered when recommending buffs, nor are any daily casting limits.
 
−
* Mutually exclusive effects aren't handled properly.
 
−
* Weapon Damage, Ranged Damage, and Spell Damage are calculated assuming 100 points of base damage&nbsp;&ndash; in other words, additive and percentage boosts are considered to have exactly equal worth. It's possible that Weapon and Ranged damage might use a better estimate of the base damage in the future, but for Spell Damage, the proper base depends on which spell you end up using.
 
−
* Effects which vary in power based on how many turns are left (love songs, Mallowed Out, etc.) are handled poorly. If you don't have the effect, they'll be suggested based on the results you'd get from having a single turn of it. If you have the effect already, extending it to raise the power won't even be considered. Similar problems occur with effects that are based on how full or drunk you currently are.
 
  
−
=Useful Expressions=
+
==Special Datatypes==
−
'''MP regen''': .5 mp regen max, .5 mp regen min
 
  
−
'''Pirates''': mainstat, +outfit swashbuckling
+
Several datatypes are included in KoLmafia to represent common categories within the KoL universe.
  
−
'''War''': mainstat, +outfit frat warrior
+
Note that while variables of these types are declared in the same way as for Primitive Datatypes; assigning and referencing them is done differently.
 +
{{CodeSample|
 +
description=For example, to declare an item datatype and assign it a value, you would use the following line of code:|
 +
code=
 +
<syntaxhighlight>
 +
item it = $item[ broken skull ];
 +
</syntaxhighlight>}}
 +
The default values of any variable of one of the following types is <code>$''type''[ none ]</code>. For example, the default value of a <code>item</code> variable is <code>$item[ none ]</code>.
  
−
'''Shieldbutting''': muscle, +shield
+
===bounty===
  
−
=More Information=
+
These are the non-items that the bounty hunter asks you to retrieve from monsters around the kingdom. There are quite a lot of them (42 in total) so I won't list them all here. You can find more about bounties at the {{kolwiki|The Bounty Hunter Hunter's Shack}}.
  
−
Here is the expression used as '''tie'''breaker:
+
===class===
  
−
:"1 familiar weight, 1 familiar experience, 1 initiative, 5 exp, 1 item, 1 meat, 0.1 DA 1000 max, 1 DR, 0.5 all res, -10 mana cost, 1.0 mus, 0.5 mys, 1.0 mox, 1.5 mainstat, 1 HP, 1 MP, 1 weapon damage, 1 ranged damage, 1 spell damage, 1 cold damage, 1 hot damage, 1 sleaze damage, 1 spooky damage, 1 stench damage, 1 cold spell damage, 1 hot spell damage, 1 sleaze spell damage, 1 spooky spell damage, 1 stench spell damage, 1 critical, -1 fumble, 1 HP regen max, 3 MP regen max, 1 critical hit percent, 0.1 food drop, 0.1 booze drop, 0.1 hat drop, 0.1 weapon drop, 0.1 offhand drop, 0.1 shirt drop, 0.1 pants drop, 0.1 accessory drop, 1 DB combat damage";
+
Besides $class[ none ], there are six possible values for this datatype:
  
−
See [http://kolmafia.us/showthread.php?4274 this thread] for details.
+
* Seal Clubber
−
<h2>See Also</h2><div style="border: dashed 1px green; margin: 0.2em; padding: 1em; width=75%; background-color: #fff8dc;"><center>[[Modifiers]]</center></div>
+
* Turtle Tamer
−
[[Category:Automation]]
+
* Pastamancer
 +
* Sauceror
 +
* Disco Bandit
 +
* Accordion Thief
 +
 
 +
===coinmaster===
 +
All shops that deal with currency other than meat. Known values include:
 +
 
 +
* {{kolwiki|The Bounty Hunter Hunter's Shack|Bounty Hunter Hunter}}
 +
* {{kolwiki|Mr. Store}}
 +
* {{kolwiki|Hermit}}
 +
* {{kolwiki|The Shore, Inc. Gift Shop}}
 +
* {{kolwiki|The Trapper's Cabin|The Trapper}}
 +
* {{kolwiki|A Vending Machine|Vending Machine}}
 +
* {{kolwiki|The Swagger Shop}}
 +
* {{kolwiki|The Hippy Camp (Wartime)|Dimemaster}}
 +
* {{kolwiki|The Orcish Frat House|Quartersmaster}}
 +
* {{kolwiki|BURT|Bugbear Token}}
 +
* {{kolwiki|Freshwater Fishbonery}}
 +
* {{kolwiki|Big Brother}}
 +
* {{kolwiki|The Terrified Eagle Inn}}
 +
* {{kolwiki|Ticket Redemption Counter|Arcade Ticket Counter}}
 +
* {{kolwiki|Cashier|Game Shoppe}}
 +
* {{kolwiki|Cashier|Game Shoppe Snacks}}
 +
* {{kolwiki|The Isotope Smithery|Isotope Smithery}}
 +
* {{kolwiki|Dollhawker's Emporium}}
 +
* {{kolwiki|The Lunar Lunch-o-Mat|Lunar Lunch-o-Mat}}
 +
* {{kolwiki|Paul's Boutique}}
 +
* {{kolwiki|The Frozen Brogurt Stand}}
 +
* {{kolwiki|Buff Jimmy's Souvenir Shop}}
 +
* {{kolwiki|Taco Dan's Taco Stand}}
 +
* {{kolwiki|You're the Fudge Wizard Now, Dog|Fudge Wand}}
 +
* {{kolwiki|The Neandermall}}
 +
* {{kolwiki|Legitimate Shoe Repair, Inc.}}
 +
* {{kolwiki|warbear black box|Warbear Black Box}}
 +
* {{kolwiki|The Dinsey Company Store}}
 +
 
 +
===effect===
 +
 
 +
Any effect you can be under in KoL, whether from items, skills, or what-have-you, is valid for this datatype.
 +
 
 +
The full range, besides $effect[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Effects}} page for more information.
 +
 
 +
===element===
 +
 
 +
Besides $element[ none ], there are seven possible values for this datatype. (Note that "Bad Spelling" is not considered a true element.)
 +
Also note that these names are case-sensitive (referencing $element[ Spooky ] will generate an error).
 +
 
 +
* cold
 +
* hot
 +
* sleaze
 +
* spooky
 +
* stench
 +
* slime
 +
* supercold
 +
 
 +
===familiar===
 +
 
 +
Any familiar available in KoL is valid for this datatype.
 +
 
 +
The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Familiars}} page for more information.
 +
 
 +
===item===
 +
 
 +
Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.
 +
{{CodeSample|
 +
description=For example, you could assign the item plexiglass pants as follows:|
 +
code=
 +
<syntaxhighlight>
 +
item it = $item[ 1234 ];
 +
</syntaxhighlight>}}
 +
The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Items}} page for more information.
 +
 
 +
===location===
 +
 
 +
Any location one can adventure at in KoL is valid for this datatype.
 +
 
 +
The full range, besides $location[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Locations}} page for more information.
 +
 
 +
===monster===
 +
 
 +
Any monster you can encounter in KoL is valid for this datatype.
 +
 
 +
The full range, besides $monster[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Monster Compendium}} page for more information.
 +
 
 +
The monster data type has the following fields, which can be accessed with $monster[].field, or in some cases, by an accessor function:
 +
{| cellpadding="3" cellspacing="0" border="1px" class="sortable"
 +
|- | style="background-color: #F2F2F2"
 +
|-
 +
!  Field Type & Name
 +
!  ASH Accessor Function / Notes
 +
|-
 +
| int id
 +
|
 +
|-
 +
| int base_hp
 +
| {{f|monster_hp}} (includes modifiers)
 +
|-
 +
| int base_attack
 +
| {{f|monster_attack}} (includes modifiers)
 +
|-
 +
| int base_defense
 +
| {{f|monster_defense}} (includes modifiers)
 +
|-
 +
| int raw_hp
 +
| (excludes modifiers)
 +
|-
 +
| int raw_attack
 +
| (excludes modifiers)
 +
|-
 +
| int raw_defense
 +
| (excludes modifiers)
 +
|-
 +
| int base_initiative
 +
| {{f|monster_initiative}} (includes modifiers)
 +
|-
 +
| int raw_initiative
 +
| (excludes modifiers)
 +
|-
 +
| element attack_element
 +
|
 +
|-
 +
| element defense_element
 +
| {{f|monster_element}}
 +
|-
 +
| int physical_resistance
 +
|
 +
|-
 +
| int min_meat
 +
| (excludes modifiers)
 +
|-
 +
| int max_meat
 +
| (excludes modifiers)
 +
|-
 +
| float base_mainstat_exp
 +
| (includes bonus stats from +ML, but not from +stat effects)
 +
|-
 +
| float base_mainstat_exp
 +
| (includes bonus stats from +ML, but not from +stat effects)
 +
|-
 +
| phylum phylum
 +
| {{f|monster_phylum}}
 +
|-
 +
| effect poison
 +
|
 +
|-
 +
| boolean boss
 +
|
 +
|-
 +
| string image
 +
|
 +
|-
 +
| aggregate boolean [string] images
 +
|
 +
|-
 +
| string attributes
 +
| A compilation of attack, defense, initiative, element, meat drop, and phylum
 +
|-
 +
| aggregate boolean [string] random_attributes
 +
| The monster's random modifiers - like those generated in the One Crazy Random Summer path
 +
|}
 +
 
 +
===phylum===
 +
 
 +
Each monster has a {{kolwiki|Phylum}}. Besides $phylum[none], the possible values for this datatype are:
 +
 
 +
* beast
 +
* bug
 +
* constellation
 +
* construct
 +
* demon
 +
* dude
 +
* elemental
 +
* elf
 +
* fish
 +
* goblin
 +
* hippy
 +
* hobo
 +
* humanoid
 +
* horror
 +
* mer-kin
 +
* orc
 +
* penguin
 +
* pirate
 +
* plant
 +
* slime
 +
* undead
 +
* weird
 +
 
 +
===servant===
 +
Servants are unique to the {{kolwiki|Actually Ed the Undying}} path and located {{kolwiki|The Servants' Quarters}}, replacing familiars.
 +
 
 +
* Assassin
 +
* Belly-Dancer
 +
* Bodyguard
 +
* Cat
 +
* Maid
 +
* Priest
 +
* Scribe
 +
 
 +
===skill===
 +
Any skill you can have in KoL (whether permable or not, granted by items, etc.) is valid for this datatype.
 +
 
 +
The full range, besides $skill[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Skills}} page for more information.
 +
 
 +
===slot===
 +
 
 +
Besides $slot[ none ], there are 16 possible values for this datatype.
 +
 
 +
* hat
 +
* back
 +
* weapon
 +
* off-hand
 +
* shirt
 +
* pants
 +
* acc1
 +
* acc2
 +
* acc3
 +
* familiar
 +
* sticker1
 +
* sticker2
 +
* sticker3
 +
* fakehand
 +
* bootspur
 +
* bootskin
 +
 
 +
===stat===
 +
 
 +
Besides $stat[ none ], there are six possible values for this datatype (the last three are for referencing sub-stats).
 +
 
 +
* muscle
 +
* mysticality
 +
* moxie
 +
* submuscle
 +
* submysticality
 +
* submoxie
 +
 
 +
===thrall===
 +
 
 +
Pastamancers have the ability to summon {{kolwiki|Pasta Thralls}}.
 +
 
 +
* Angel Hair Wisp
 +
* Elbow Macaroni
 +
* Lasagmbie
 +
* Penne Dreadful
 +
* Spaghetti Elemental
 +
* Spice Ghost
 +
* Vampieroghi
 +
* Vermincelli
 +
 
 +
==aggregate==
 +
 
 +
An aggregate is a complex datatype composed of two or more primitive or special datatypes. For more information, see [[Data Structures]].
 +
 
 +
==record==
 +
 
 +
Records are user-defined datatypes that hold as many sub-datatypes as desired. For more information, see the page for [[Data Structures]].
 +
 
 +
==Plural Typed Constants==
 +
 
 +
(see http://kolmafia.us/showthread.php?p=15592, from which this section is reproduced)
 +
 
 +
Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:
 +
{{CodeSample|code=<syntaxhighlight>
 +
foreach weapon in $items[star sword, star staff, star crossbow] {
 +
  if (available_amount(weapon) > 0) {
 +
      equip(weapon);
 +
      break;
 +
  }
 +
}</syntaxhighlight>}}
 +
The syntax is basically the same as the existing typed constant feature, but with an "s" or "es" after the type name. (The "es" case is there so that you can properly pluralize "class".) The text between the square brackets is interpreted as a comma-separated list of elements, each of which is converted to the specified type as if it were an individual constant. More details:
 +
* The list can span multiple lines.
 +
* Whitespace before or after elements is ignored.
 +
* Completely empty elements are ignored (so that you can leave a comma at the end of the list).
 +
* You can include a comma or closing square bracket in an element by writing it as "\," or "\]".
 +
* All the other escape sequences allowed in strings are possible, such as "\n" (newline), "\t" (tab), and "\uXXXX" (Unicode character value). To put an actual backslash in an element, you have to write it as "\\".
 +
 
 +
The value generated by a plural constant is of type boolean[type], with the keys being the specified elements, and the boolean value always being true - although you won't normally do anything with the boolean, you'd use a foreach loop to iterate over the keys. You can assign a plural constant to a variable declared as that type, but note that the value differs from a normal map in three important respects:
 +
* Since the expression that generates it is syntactically a constant, the value has to be immutable. If you were allowed to change it in any way, those changes would appear in every future use of the same constant.
 +
* There can be multiple instances of the same key - $ints[1,1,2,3,5,8] is perfectly valid, and will result in the value 1 appearing twice in a foreach loop.
 +
* The keys will appear in the order you wrote them, rather than being sorted alphanumerically as maps usually do.
 +
 
 +
In addition to being used in a foreach loop, plural constants also efficiently support membership testing via the 'contains' operator. Here's another example:
 +
{{CodeSample|code=<syntaxhighlight>
 +
for hour from 1 to 12 {
 +
  print("It's " + hour + " o'clock.");
 +
  if ($ints[10, 2, 4] contains hour) {
 +
      print("Time to drink a Dr Pepper!");
 +
  }
 +
}</syntaxhighlight>}}
 +
(Yes, that example could just as easily have been done with a switch statement.)
 +
 
 +
Iterating over an empty list is rather pointless, so plural constants with no elements are given a different meaning: they represent every value of the specified type, where this is practical. (The 'none' value, if defined for a given type, is omitted.) The biggest benefit here is $items[], which lets you loop over every defined item, more efficiently than you could otherwise write in a script (since the list is generated once per session and then cached), and without having to hard-code a maximum item ID number in your script. Example:
 +
{{CodeSample|code=<syntaxhighlight>
 +
foreach it in $items[] {
 +
  if (autosell_price(it) == 42) print(it);
 +
}</syntaxhighlight>}}
 +
Enumeration of all possible values works with the following types:
 +
* $booleans[] - false and true.
 +
* $items[]
 +
* $locations[]
 +
* $classes[]
 +
* $stats[] - Muscle, Mysticality, Moxie: the substat values are omitted.
 +
* $skills[]
 +
* $effects[]
 +
* $familiars[]
 +
* $slots[] - includes sticker slots and fake hands, which you might not want to consider as normal slots.
 +
* $monsters[]
 +
* $elements[] - includes slime now, and possibly other not-quite-elements like cute in the future.
 +
 
 +
The remaining types that can be used in plural constants require an explicit list of elements, since there are too many possible values:
 +
* $ints[] - you don't have enough RAM to store a list with 4 billion elements.
 +
* $floats[] - ditto.
 +
* $strings[] - nobody has that much RAM.
 +
 
 +
==Custom==
 +
 
 +
===matcher===
 +
 
 +
A matcher isn't really a datatype so much as it's a class, but it is included here for reference, as it is used much as datatypes are in ASH. It can only be declared through the function {{f|create_matcher}}, using two strings. One is the string to find matches in, the other a regular expression to test against. For more information on using a matcher, see [[Regular Expressions]].
 +
 
 +
[[Category:Scripting]]

Revision as of 00:12, 22 July 2016

Primitive Datatypes

void

Can be thought of better as the absence of a datatype. No value can be assigned to void nor can a value be returned from a function of datatype void.

boolean

A boolean value is either true or false. By default, a boolean variable is set to false.

int

A whole number (short for "integer"), either positive or negative (or 0). The int used by KoLmafia is a 32-bit signed int, meaning it has a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648. The default value of a integer variable is 0.

Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example: 

int a = 1;
int b = 2;
print( a / b * 2 );

Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.

float

The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [1]

When assigning to a variable of type float, one should be careful to always enter numbers in decimal form, as unwanted behavior can result from supplying a value that KoLmafia may interpret as an int type without the decimal point.

Note that float is not infinitely precise; it intrinsically rounds off after a certain point. This loss of accuracy is for the sake of storage, but beware of the possibility of small errors compounding from multiple float types.

For instance, try the following code as an example of how rather long post-decimal portions are handled:

float f;
f = 4.9999999;
print( f );

The default value of a float variable is 0.0.

string

A group of characters including, but not limited to: lowercase letters, uppercase characters, numbers, and various control characters. When assigning a value to a string, always enclose the desired value in either single or double quotes (note you must use the same quote type on both ends of the string assignment). If you need to include the same character inside of the string itself, you will need to escape it first with a backslash.

For example:

string s = "This is my \"friend\" Pete.";

Will result in the following being stored to s: 

This is my "friend" Pete

The default value of a string is an empty string, or literally "".

buffer

Similar to a string, but more efficient in certain operations, including concatenation and passing as function arguments. For the most part, you can interchange references to strings and buffers. However, you should test all such actions first, as a few functions require a specific datatype to be supplied as a parameter. (Most notably, those listed under Regular Expressions.)

Special Datatypes

Several datatypes are included in KoLmafia to represent common categories within the KoL universe.

Note that while variables of these types are declared in the same way as for Primitive Datatypes; assigning and referencing them is done differently.

For example, to declare an item datatype and assign it a value, you would use the following line of code:

item it = $item[ broken skull ];

The default values of any variable of one of the following types is $type[ none ]. For example, the default value of a item variable is $item[ none ].

bounty

These are the non-items that the bounty hunter asks you to retrieve from monsters around the kingdom. There are quite a lot of them (42 in total) so I won't list them all here. You can find more about bounties at the The Bounty Hunter Hunter's Shack.

class

Besides $class[ none ], there are six possible values for this datatype:

  • Seal Clubber
  • Turtle Tamer
  • Pastamancer
  • Sauceror
  • Disco Bandit
  • Accordion Thief

coinmaster

All shops that deal with currency other than meat. Known values include:

effect

Any effect you can be under in KoL, whether from items, skills, or what-have-you, is valid for this datatype.

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the Wiki Effects page for more information.

element

Besides $element[ none ], there are seven possible values for this datatype. (Note that "Bad Spelling" is not considered a true element.) Also note that these names are case-sensitive (referencing $element[ Spooky ] will generate an error).

  • cold
  • hot
  • sleaze
  • spooky
  • stench
  • slime
  • supercold

familiar

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the Wiki Familiars page for more information.

item

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.

For example, you could assign the item plexiglass pants as follows:

item it = $item[ 1234 ];

The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki Items page for more information.

location

Any location one can adventure at in KoL is valid for this datatype.

The full range, besides $location[ none ], is too much to list and keep up with here: please see the Wiki Locations page for more information.

monster

Any monster you can encounter in KoL is valid for this datatype.

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the Wiki Monster Compendium page for more information.

The monster data type has the following fields, which can be accessed with $monster[].field, or in some cases, by an accessor function:

Field Type & Name ASH Accessor Function / Notes
int id
int base_hp monster_hp() (includes modifiers)
int base_attack monster_attack() (includes modifiers)
int base_defense monster_defense() (includes modifiers)
int raw_hp (excludes modifiers)
int raw_attack (excludes modifiers)
int raw_defense (excludes modifiers)
int base_initiative monster_initiative() (includes modifiers)
int raw_initiative (excludes modifiers)
element attack_element
element defense_element monster_element()
int physical_resistance
int min_meat (excludes modifiers)
int max_meat (excludes modifiers)
float base_mainstat_exp (includes bonus stats from +ML, but not from +stat effects)
float base_mainstat_exp (includes bonus stats from +ML, but not from +stat effects)
phylum phylum monster_phylum()
effect poison
boolean boss
string image
aggregate boolean [string] images
string attributes A compilation of attack, defense, initiative, element, meat drop, and phylum
aggregate boolean [string] random_attributes The monster's random modifiers - like those generated in the One Crazy Random Summer path

phylum

Each monster has a Phylum. Besides $phylum[none], the possible values for this datatype are:

  • beast
  • bug
  • constellation
  • construct
  • demon
  • dude
  • elemental
  • elf
  • fish
  • goblin
  • hippy
  • hobo
  • humanoid
  • horror
  • mer-kin
  • orc
  • penguin
  • pirate
  • plant
  • slime
  • undead
  • weird

servant

Servants are unique to the Actually Ed the Undying path and located The Servants' Quarters, replacing familiars.

  • Assassin
  • Belly-Dancer
  • Bodyguard
  • Cat
  • Maid
  • Priest
  • Scribe

skill

Any skill you can have in KoL (whether permable or not, granted by items, etc.) is valid for this datatype.

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the Wiki Skills page for more information.

slot

Besides $slot[ none ], there are 16 possible values for this datatype.

  • hat
  • back
  • weapon
  • off-hand
  • shirt
  • pants
  • acc1
  • acc2
  • acc3
  • familiar
  • sticker1
  • sticker2
  • sticker3
  • fakehand
  • bootspur
  • bootskin

stat

Besides $stat[ none ], there are six possible values for this datatype (the last three are for referencing sub-stats).

  • muscle
  • mysticality
  • moxie
  • submuscle
  • submysticality
  • submoxie

thrall

Pastamancers have the ability to summon Pasta Thralls.

  • Angel Hair Wisp
  • Elbow Macaroni
  • Lasagmbie
  • Penne Dreadful
  • Spaghetti Elemental
  • Spice Ghost
  • Vampieroghi
  • Vermincelli

aggregate

An aggregate is a complex datatype composed of two or more primitive or special datatypes. For more information, see Data Structures.

record

Records are user-defined datatypes that hold as many sub-datatypes as desired. For more information, see the page for Data Structures.

Plural Typed Constants

(see http://kolmafia.us/showthread.php?p=15592, from which this section is reproduced)

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example: 

foreach weapon in $items[star sword, star staff, star crossbow] {
   if (available_amount(weapon) > 0) {
      equip(weapon);
      break;
   }
}

The syntax is basically the same as the existing typed constant feature, but with an "s" or "es" after the type name. (The "es" case is there so that you can properly pluralize "class".) The text between the square brackets is interpreted as a comma-separated list of elements, each of which is converted to the specified type as if it were an individual constant. More details:

  • The list can span multiple lines.
  • Whitespace before or after elements is ignored.
  • Completely empty elements are ignored (so that you can leave a comma at the end of the list).
  • You can include a comma or closing square bracket in an element by writing it as "\," or "\]".
  • All the other escape sequences allowed in strings are possible, such as "\n" (newline), "\t" (tab), and "\uXXXX" (Unicode character value). To put an actual backslash in an element, you have to write it as "\\".

The value generated by a plural constant is of type boolean[type], with the keys being the specified elements, and the boolean value always being true - although you won't normally do anything with the boolean, you'd use a foreach loop to iterate over the keys. You can assign a plural constant to a variable declared as that type, but note that the value differs from a normal map in three important respects:

  • Since the expression that generates it is syntactically a constant, the value has to be immutable. If you were allowed to change it in any way, those changes would appear in every future use of the same constant.
  • There can be multiple instances of the same key - $ints[1,1,2,3,5,8] is perfectly valid, and will result in the value 1 appearing twice in a foreach loop.
  • The keys will appear in the order you wrote them, rather than being sorted alphanumerically as maps usually do.

In addition to being used in a foreach loop, plural constants also efficiently support membership testing via the 'contains' operator. Here's another example: 

for hour from 1 to 12 {
   print("It's " + hour + " o'clock.");
   if ($ints[10, 2, 4] contains hour) {
      print("Time to drink a Dr Pepper!");
   }
}

(Yes, that example could just as easily have been done with a switch statement.)

Iterating over an empty list is rather pointless, so plural constants with no elements are given a different meaning: they represent every value of the specified type, where this is practical. (The 'none' value, if defined for a given type, is omitted.) The biggest benefit here is $items[], which lets you loop over every defined item, more efficiently than you could otherwise write in a script (since the list is generated once per session and then cached), and without having to hard-code a maximum item ID number in your script. Example: 

foreach it in $items[] {
   if (autosell_price(it) == 42) print(it);
}

Enumeration of all possible values works with the following types:

  • $booleans[] - false and true.
  • $items[]
  • $locations[]
  • $classes[]
  • $stats[] - Muscle, Mysticality, Moxie: the substat values are omitted.
  • $skills[]
  • $effects[]
  • $familiars[]
  • $slots[] - includes sticker slots and fake hands, which you might not want to consider as normal slots.
  • $monsters[]
  • $elements[] - includes slime now, and possibly other not-quite-elements like cute in the future.

The remaining types that can be used in plural constants require an explicit list of elements, since there are too many possible values:

  • $ints[] - you don't have enough RAM to store a list with 4 billion elements.
  • $floats[] - ditto.
  • $strings[] - nobody has that much RAM.

Custom

matcher

A matcher isn't really a datatype so much as it's a class, but it is included here for reference, as it is used much as datatypes are in ASH. It can only be declared through the function create_matcher(), using two strings. One is the string to find matches in, the other a regular expression to test against. For more information on using a matcher, see Regular Expressions.

Retrieved from "https://wiki.kolmafia.us/index.php?title=Modifier_Maximizer&oldid=6806"