ASH Function Reference Manual

T

Tirian

Member
Introduction post

Holatuwol challenged us to pick up the gauntlet of ASH training, and I think that he is right to have done so. Not simply because we are all a bunch of overdependent do-nothings, but also because the developers have been too busy with new and fabulous features to keep the manuals in proper reflection of the state of the product. In short, we're the right people to document ASH and this is the right place to document ASH, so let's get to it! So here's my little introductory FAQ:

What can I learn here? What can't I learn here?

It is my intention that this manual cover the functions in ASH. That is, the words that are followed by a set of parentheses that maybe have things inside them. I'm not going to cover the fundimentals of the ASH language specifically or structured programming in general. I hope someone else feels compelled to write something up to cover that, because it is a great subject and I think that ASH would be an ideal first programming language for someone to learn. I'm also not going to cover other script-ish parts of KoLmafia like CLI, CCS, or moods -- again, someone else is welcome to step up to the plate.

How is this manual going to be different from the old one?

Content-wise, not very different at all. I've got some different notions on how to group the functionality together to cover common themes so that the function you're looking for might be easier to find.

The major difference that I think will be useful is that this manual will provide a link from the functions to actual working scripts in this repository that use the functions in context. So there won't be any question about how or why one would want something, it's just right there. This will also provide, I hope, a survey of proper syntax and best programming practices while also showcasing the diversity of writing styles among sound programmers.

How complete is the manual?

Umm, I'm not certain. I had the functions from the old manual stored on my hard drive, and I've added in the functions that Holatuwol added for us over the past few weeks, and I've scratched my head a few times saying things like "Hey, why isn't sell_item() here?" If you see stuff missing, call me on it. Eventually, I'll sit down with a bottle of wine and the ASH source code and make sure that it's all included.

Hey wait, I want to suck up to Holatuwol too!

Outstanding, there's lots left to do! Like I mentioned before, there is the fundimental language reference to write for people who don't know about "if" and "return" and global variables and maps and the ASH raw data types. Also, someone who is more in-depth with CLI can try to recreate that manual or offer to revise it and get the old copy.

In addition, I'd love to have people volunteer their scripts as examples. I want to be a little particualr here, because I don't want every script ever written to overshadow the goals of the document. At the moment, I'm looking for something that is well-written and commented, that uses functions that do not currently have examples given, and is not unreasonably long. I may turn out to be pickier than that by the time all is said and done, so forgive me in advance if you offer something and I turn you down. :)

(Mods, I know that I'm about to double post. I hope you can appreciate the benefits of keeping these two posts separate. Cut my post count in half if you think I'm deliberately spamming to make myself seem important. ::))

( this is why I call them "guidelines" rather than "rules". Carry on, soldier! ;-) -Daychilde )

ETA: Did I say double-post? I evidently meant multi-post, due to the size restrictions on the posts. But that's the last of it, with enough room for editing in the future I think!
 
ASH Function Reference Manual
version 0.1
July 19, 2006
by Tirian (mostly)​

[size=12pt]Part 1 - Elementary knowledge about your character[/size]
We'll start with a long look in the mirror. Here's how to tell about you.

string my_name()
Returns your character's name

string my_turncount()
Returns the number of adventures you have had in this ascension

int my_level()
Returns your level
Sample: Friar's Quest

class my_class()
Returns your class

stat my_primestat()
Returns the stat associated with your class

zodiac my_zodiac()
Returns your ascension sign

boolean in_moxie_sign()
boolean in_muscle_sign()
boolean in_mysticality_sign()
Tells you if your sign is associated with the given stat

int my_hp()
int my_mp()
int my_maxhp()
int my_maxmp()
Returns your current and highest available HP and MP levels

int my_basestat(stat st)
int my_buffedstat(stat st)
Returns your base and buffed values in the given stat

familiar my_familiar()
Returns the familiar you are carrying now

int my_adventures()
Returns the number of adventures that you have remaining today
Sample: Friar's Quest

int my_inebrity()
int inebrity_limit()
Returns how drunk you are and the limit at which you must stop adventuring

int my_meat()
int my_closetmeat()
Returns your current meat in your inventory and closet

boolean can_eat()
boolean can_drink()
boolean can_interact()
boolean in_hardcore()
Tells you about your limitations due to ronin, hardcore, or voluntary dietary restrictions
Sample: Friar's Quest

int pulls_remaining()
If you are in ronin, the number of additional items that you can remove from Ancestral Storage today
Sample: Jammies

int current_mind_control_level ()
boolean mind_control (int level)
Returns or sets the level of the Super-Secret Canadian Mind-Control Device

boolean have_chef()
boolean have_bartender()
Tells you if you have a robotic creator installed in your campground

boolean have_mushroom_plot()
Tells you if you bought the mushroom plot in Degrassi Knoll.

int stills_available()
Returns the number of transformations you can make at Nash Crosby's Still today (or 0 if you have no access).
Sample: Jammies
 
[size=12pt]Part 2 - Item management[/size]
Now we'll expand our focus to include some of your special "me-places" in the Kingdom and how to play with them

int item_amount (item it)
int closet_amount (item it)
int museum_amount (item it)
int shop_amount (item it)
int storage_amount (item it)
int stash_amount (item it)
Returns the amount of the given item in (respectively) your main inventory, your Collosal Closet, your Display Case, your Mall store, Hagnk's Ancestral Storage, and your clan's stash (to the degree that you have access to these locations).

boolean take_closet (int count, item it)
boolean take_storage (int count, item it)
boolean take_stash (int count, item it)
boolean put_closet (int count, item it)
boolean put_stash (int count, item it)
Attempts to move the desired number of the desired item into or out of the Colossal Closet, Ancestral Storage, or your clan's stash. The return value indicates the success of your endeavor. If you have fewer than the desired number of the item, then the function will not place any.
Sample: Jammies

boolean put_shop (int price, item limit, item it)
Places all of the associated item into your mall store at the desired price and with the associated limit on purchases per day, if possible. If the price is set to 0, then the price set will either be 999,999,999 meat if there were previously none of the item in your store, or the previous price if you already had some of that item in the store.

boolean buy (int count, item it)
Tries to buy items. First preference is given to NPC stores that you have access to and then, if possible, will buy the cheapest available items from the mall.
Sample: Jammies

boolean sell_item (int count, item it)
Autosells the given items.

boolean bounty_hunter_wants (item it)
Tells you if the bounty hunter is accepting the specified item today
Sample: Jammies

boolean trade_bounty_hunter (item it)
Trades all of the specified item with the bounty hunter if he is accepting them today.
Sample: Jammies

boolean trade_trapper (item it)
Trades all of your yeti fur to the L33t Tr4pz0r's in exchange for the indicated fur.
Sample: Jammies

boolean trade_hermit (int count, item it)
Buys the appropriate number of the given item from the Hermit. It assumes that you have enough worthless items but will manage buying the Hermit Permits if needed.

boolean use (int number, item it)
Uses one or more items.

boolean create (int number, item it)
Attempts to create the desired items. Depending on your in-game settings and conditions, this may involve buying ingredients for the items or servants to create the items for you.

int creatable_amount (item it)
Returns the number of copies of the item that you are capable of creating with your current inventory. Servant availability and remaining adventures are not factored into this calculation.


[size=12pt]Part 3 - Equipment [/size]
Time to get dressed!

boolean equip (item it)
Puts on the specified item in the "natural" slot. For example, it won't equip a weapon to the off-hand and it will only put a accessory into an empty slot.

boolean equip_slot (slot sl, item it)
Puts the specified item in the desired slot, if possible.

boolean unequip (iten it)
Takes off the specified item.

slot item_to_slot (item it)
Returns the natural slot for the item, if it is equippable.

item current_equipment (slot sl)
Returns the item currently equipped in the given slot.
Sample: Jammies

boolean have_equipped (item it)
Tells you if the specified item is currently equipped (as it would not otherwise show up in item_amount()).

boolean can_equip (item it)
Tells you if you meet the requirements to equip the given item (regardless of whether you own it).
Sample: Jammies

boolean equip_familiar (familiar pet)
Takes the specified familiar out of your Terrarium. Use equip() and unequip() to manage your familiar's gear.

item familiar_equipment (familiar pet)
Returns the most common piece of equipment that is specially designed for the familiar's type.

boolean have_outfit (string outfit_name)
Lets you know if you have all of the pieces of the specified outfit, whether in-game or a custom outfit.

boolean outfit (string outfit_name)
Wears the specified outfit.
 
[size=12pt]Part 4 - Skills and Effects[/size]
Just a few buffs and then we're ready to face the world!

boolean have_skill (skill sk)
Tells you if you have the indicated skill in this current ascension.
See: Friars

int have_effect (effect ef)
Returns the number of adventures remaining of the given effect, or 0 if you are not under the effect. (Intrinsic effects are not covered here.)

effect skill_to_effect (skill sk)
skill effect_to_skill (effect ef)
Returns the desired association between skills and the effects that they produce.

int mp_cost(skill)
Returns the amount of MP that it costs to use the specified skill. Passive skills return 0. MP reduction items are not factored into this calculation.

boolean use_skill (int number, skill sk)
Casts the given skill as many times as you indicate. MP restoration will happen automatically as needed to cover the cost.

boolean restore_hp (int amount)
boolean restore_mp (int amount)
Uses KoLmafia's autohealer to restore the specified thing as it thinks best.


[size=12pt]Part 5 - Adventuring[/size]
Go get 'em, tiger!

boolean adventure (int visits, location place)
Visits the desired place the number of times that you wish.
Sample: Friar's Quest

void add_item_condition(int count, item it)
Specifies adventuring conditions. With conditions in palce, adventure(...) will successfully complete before using all the specified adventures if the conditions are all met. See the CLI manual for additional condition programming.

void council()
Visits the Council of Loathing.
Sample: Friar's Quest

boolean hedgemaze()
Uses all of your hedge puzzles to navigate the maze. The return value indicates if it successfully completed the quest.

item guardians()
Climbs the Naughty Sorceress' Tower and passes the challenges that it can. If it completes the challenge, it returns $item[none]. Otherwise, it returns the item that it needs to pass the next stage.


[size=12pt]Part 6 - Miscelaneous commands[/size]
Mostly internal stuff. Some good for everyone, some only for ASH wizards.

void print (string helloworld)
Prints the given string to the graphical CLI window and to the status line of the main Adventuring window
Sample: Friar's Quest

boolean cli_execute (string command)
Executes the given command as if it were entered into the graphical CLI window. This can be used for CLI commands or, if you're careful and not an asshat, for raw URLs. See the CLI manual for more details.
Sample: Friar's Quest

string get_property (string key)
boolean set_property (string key, string value)
Gets or sets a stored property from your character's .kcs file. Again, only do this if you really know what you're doing.

string boolean_to_string(boolean flag)
string int_to_string(int number)
string float_to_string(float number)
string item_to_string(item it)
string zodiac_to_string(zodiac sign)
string location_to_string(location spot)
string familiar_to_string(familiar pet)
string class_to_string(class cl)
string stat_to_string(stat st)
string skill_to_string(skill sk)
string effect_to_string(effect ef)
Converts in-game variables to printable counterparts. Generally unnecessary now, as ASH will cast all variables to strings if it senses the need to do so.

int item_to_int(item it)
int skill_to_int (skill sk)
...
Converts the ASH-based object into the number that will be recognized by the KoL server. Needed when you're building raw URLs from time to time.

item int_to_item(int nItem)
...
Converts the KoL-based number into an associated ASH object. These aren't the commands you're looking for. You can go about your business.
 
wow, this is awesome!! Thanks for taking the time and being dedicated enough to put this list together. Much appreciated!
 
This ASH function reference project has brought back all of KoLmafia's documentation, aside from the data override reference (which I won't update until after v8.4).  I have stolen your categorizations concept and underwent the painful process of re-arranging the CLI manual (I imagine not too many people here use it because of its simplicity).

The ASH type reference has been re-added to the website and merged with Xylpher's basic tutorial and Veracity's maps tutorial, and where the function reference would have appeared now links here.  Absolutely amazing work.  Thanks for restoring a little bit of faith that I have in the KoLmafia end-user community.  You have no idea how much I needed it.
 
[quote author=holatuwol link=topic=298.msg1590#msg1590 date=1153363522]
Absolutely amazing work.[/quote]Seconded!
 
Hopefully, Tirian isn't stuck doing this alone, because then it's just me and Tirian switching places with maintaining documentation. ;) So, once again hopefully, you'll find some willing partners in your endeavor to dig up examples of where they've used these functions in their non library-sized scripts. :)
 
Heh I have too much spare time, I'll see if I can write up some example scripts for you, something simple that wont be all messy like my usual work... and smaller.
>> I completely suck at explaining things so I don't really see myself writing actual "references" as such >>


Edit: Just a little typo "string my_turncount()" seems to be a int rather then a string.

Edit2: Im going to avoid writing these little example scripts for the ones you already have linked to in proper scripts unless someone requests it.

Edit3: Found another typo "inebrity" is spelt "inebriety".
 
[quote author=Nightmist link=topic=298.msg1609#msg1609 date=1153388395]Edit: Just a little typo "string my_turncount()" seems to be a int rather then a string.

Edit2: Im going to avoid writing these little example scripts for the ones you already have linked to in proper scripts unless someone requests it.

Edit3: Found another typo "inebrity" is spelt "inebriety".[/quote]Thanks for the info, the wiki manual has been updating using my new-found ability :).
 
As of this moment, the Wiki copy of the manual is a full acounting of ASH's functions. Phew! I had no idea there was so much stuff there, I've evidently been overusing CLI. There are also five code samples to demonstrate how the functions work together and how to write pleasing syntax; that section will continue to grow as ideas are submitted or occur to me independently.
 
You know what this means! It's time for me to ... add functions to the ASH. ^_~ Except, I'll not do that until after the release. What kinds of functions did you find and not know about while browsing the source?
 
[quote author=holatuwol link=topic=298.msg1675#msg1675 date=1153888030]
What kinds of functions did you find and not know about while browsing the source?
[/quote]

Well im not sure about the ones Tirian added but I had to manually add the random and url_encode//decode to the wiki list.
 
Yes, I noticed those three additions. I literally went through the KoLmafia source code and pulled out every function that was referenced there. So the sorts of things that I added were weapon_hands(), ranged_weapon(), have_familiar(), wait(), the rounding functions, and the monster data functions.

The stuff that surprised me was that I didn't realize that all of the quest functions had ASH wrappers -- I had it in my mind that it was just hedgemaze() and guardians(). And also I thought that retrieve() was just a CLI function. Small things like that. But I also learned from your updated CLI manual that you can "acquire 3 worthless item", which is going to come in handy.

[quote author=holatuwol link=topic=298.msg1675#msg1675 date=1153888030]
You know what this means! It's time for me to ... add functions to the ASH. ^_~ [/quote]

Oh, what a tragic waste of your genius. You should recruit someone from the community to freshen up ASH while you apply your talents to the more difficult parts of KoLmafia.... ;D
 
[quote author=Tirian link=topic=298.msg1573#msg1573 date=1153328367]
[size=12pt]Part 2 - Item management[/size]

boolean bounty_hunter_wants (item it)
Tells you if the bounty hunter is accepting the specified item today
Sample: Jammies

boolean trade_bounty_hunter (item it)

[/quote]

Are there updates for these functions? I was trying to loop through possible bounty items to collect to see if one of those was an option for the day, but these functions aren't recognized.
 
[quote author=lordbaum link=topic=298.msg5847#msg5847 date=1191539855]


Are there updates for these functions? I was trying to loop through possible bounty items to collect to see if one of those was an option for the day, but these functions aren't recognized.
[/quote]

This was intended for the previous version of the BHH who accepted items such as skins, I believe that BHH scripting support has been dropped.

Check this thread for more info
http://kolmafia.us/index.php/topic,938.msg4645/topicseen.html#msg4645
 
As a little add-in:
For those who wish to find help with ash functions you may type in "ashref" into the gCLI and get a full print out of the function library.
Or for a more specific function you might want to try "ashref XXX" where you replace "XXX" with anything...
For example, when typing in "ashref print" into gCLI it will return:
Code: 
void logprint( string )
void print( string )
void print( string, string )
void print_html( string )
Any question about this function you may post here or PM me.
 
Is it possible that someone with global edit privileges could update at least the commands that have been renamed in the first few posts eg. Equip_familiar has become use_familiar.

I know we can use ashref but we can't search it and it's sometimes hard to identify the command you need - it must be extremely confusing to newcomers.

Tom
 
You must log in or register to reply here.
Back
Top