Relay override ... what?

holatuwol

Developer
[size=16pt]What is it?[/size]

Starting with the release of KoLmafia v11.3, end-users will be given the ability to override (almost) any HTML that is sent to the relay browser in order to help out with ideas for the actual relay browser interface.


[size=16pt]How does it work?[/size]

When the browser requests a page, it will be given to KoLmafia, which usually relays it to the KoL servers (which is why it's called the "relay browser" ^_~).  If it's a request for custom combat, KoLmafia will initiate its custom combat routine.  Otherwise, KoLmafia will pass the URL to the ASH and ask, "Do you want to override this URL?"  The answer to that question comes in two parts.

First, KoLmafia will check for a file named like the PHP file in its "relay" directory (not created by default).  For example, if the page is fight.php, KoLmafia will ask if there's a fight.ash file in the relay directory.  If no such file exists, KoLmafia will assume there is no override script and continue processing everything as normal.  If there is such a script, KoLmafia will call that script's main function (no parameters).

Second, the URL has not been visited when the script is called, so the script can decide to visit the URL (a special visit_url() with no parameters is provided to do this), visit a completely different URL, or simply generate data.  Note that during this time, visit_url(string) will return the same HTML that would be presented if the player visited it via KoLmafia, rather than the KoL text.  If you wish to transmit information to the relay browser, you must use the write(string) method added for this purpose.

If no HTML is generated using write(string), KoLmafia checks if visit_url() was called and uses the response text from there; if no HTML is generated and visit_url() was never called, KoLmafia assumes that the ASH script wants KoLmafia to handle everything and runs the request as normal.


[size=16pt]Why was this feature added?[/size]

Essentially, all it lets you do is add any information that the ASH can access (for example, item modifiers) anywhere in the KoL browser interface, but only while using KoLmafia.  Think of it as a toned-down Greasemonkey with flexibility of being able to traverse DOM trees (and GM_getValue and GM_setValue) exchanged for a whole lot of data.

Given that, I don't imagine a lot of people will write these scripts (at least compared to the auto-adventure ones), but it's a totally different idea, which is why this forum exists.  However, it's not without its purpose -- it (a) lets me try out relay browser ideas without committing code to the repository, and (b) lets you present functioning ideas on how the relay browser can be modified to make the game more fun to play.


[size=16pt]But string processing is hard...[/size]

Because HTML manipulation is complicated business, and you don't get to traverse DOM trees like Javascript does (well, unless you choose to inject Javascript), KoLmafia has been augmented with a lot more string processing functions and two new data types: "matcher", which is similar to Java's Matcher class, and "buffer", which is similar to Java's StringBuffer class.

In order to make these easier to look up, and since these are very natural with dot notation, the "ashref" CLI command has been augmented to let you look up functions by first parameter type.  So, "ashref string" will return all functions where you can say "mystring.blah()" ... which should make finding the functions associated with the new data types a lot easier.


[size=16pt]Can we see an example script?[/size]

Bear in mind that these scripts tend to be very long because of what they have to do (believe it or not, the KoLmafia code equivalents aren't any shorter).  However, a relatively simple script is attached -- all it does is add disco combos to the fight page for disco bandits who have the appropriate skills.
 

Attachments

  • fight.ash
    3.1 KB · Views: 205
Thanks for adding this Holatuwol!

Soon I will be writing up some scripts which will make use of this feature, and you may like some of them enough to add them to the list of great relay features built into kolmafia.
 
Top