StDoodle's Dungeon Parser


StDoodle's Dungeon Parser v1.6
Requires KoLmafia r11552

Who's it For?

This script is primarily for those in charge of distributing basement loot for their clan. It can also be used in a similar manner to the raid log manager, but much slower to parse and without as many nifty features.

Note that the current version isn't all that "safe" about handling its use by players who can't access various clan & dungeon-related pages in KoL. Being unable to distro loot should be handled ok; it just won't ever get to that part if you aren't allowed to do that; but if you can't visit the basement at all or view the clan activity log, you may have major issues. I will eventually add support for handling these better.

What's it DO?

In a nutshell, it's a dungeon-agnostic dungeon parser. It looks at a currently-open dungeon log, and it parses each line against a data file. The first matching line from the data file will be used to add points to the player's total for whom the current activity line recognizes and / or mark that player as being eligible for loot. Note that the number of different "points" that can be tracked per dungeon is unlimited for the current instance; however, one category must be picked as being the "points" that are summarized and accumulated. This can be used to track things such as "how many vampires have been killed per player" or "what's the monster level adjustment from non-coms" to use a couple of Haunted Sorority House examples.

The script will display whatever information you want to track as either / or of a summary of totals in the current instance and per-player summaries in a table (complete with click-sorting headers). Once you've copy-pasted the previous summary forum post, it will display how much loot each player has and how much they want (by category, such as "Outfit" or "Nodules," all defined in the data-file), as well as their old tracked points and their running-totals.

Once the script sees that there is loot from the dungeon to distribute, it will also give drop-down menus similar to those in the clan basement main page for loot distribution. It will display the distribution rules for your clan & dungeon (again, defined in data file) as a reminder, and once you're done you can hit the "Distro!" button to have the script hand out the loot as specified. If not all loot has been assigned, you'll be asked if you're sure about going ahead.

Then, it will update all of the player info (running totals of points, loot acquired) and give a new forum post for copypasta as well as a summary of dungeon debts (again, defined in data file).

What else do I need?

StDoodle's Clan Management ( is required for this script to run; this is a clan plugin. That script has a large number of dependencies which it requires, so you'll need all of its support in place first.

Not all of the information is stored in the script (it's designed originally for use in Hardcore Nation, where multiple people are in charge of loot distribution; eventually, I have ideas for adding in automatic data-sharing, but it won't happen soon). You'll need to copy & paste certain information between some central source and this script. First, you'll need a place to store the "current & historical" information (who received what, and what the current point totals are); a php-based BBS (specifically, has been used as the test-case. Second, you need a place to keep track of dungeon debts if you charge for loot / participation.

You'll also need to define a bunch of stuff in a data file to figure how you want to track the dungeon, how you want to create debts, what your distro rules are, etc. This will be explained in detail in the following post. I will also upload a copy of HCN's data file for the Slime Tube, which is very simple and counts every turn spent in the tube as one point.

Finally, you'll need to configure the "registered_tabs.txt" data file for the Clan Management script such that you get a tab for the defined dungeon (also explained below). If you use the initialization script posted in the Clan Management thread, this should be set up for you.

For reference, my current "registered_tabs.txt" file contains the following (note; each entry for "order" should be unique).

SLIMETUBE    script    dungeon_parser.ash
SLIMETUBE    parameter    Slime Tube
SLIMETUBE    actions    0    parse_history
SLIMETUBE    actions    1    distro
SLIMETUBE    actions    2    clear_history
SLIMETUBE    actions    3    force_dis
SLIMETUBE    actions    4    post_and_debt
SLIMETUBE    actions    5    reset_cache
SLIMETUBE    order    4
SLIMETUBE    enabled    true

Actually using this crazy thing...

Your best bet is probably just to run the bugger once all of the setup has been done. It's mostly self-explanatory once you have a dungeon definition data file in the right place (explained below).

For the most part, a properly configured data file will give enough directions such that you can find your own way around. Also, the script has tons of pop-up descriptions (via the "title" attribute) to help you out even more.

Honestly, I've had my head buried in this for so long that I can't fathom not understanding what it does; so if you try it out, and find yourself confused, please ask!

Version History

v1.6 Allow different types of tags for the forum summary post (see my post dated Oct. 17 2012)
v1.5 Fixed(?) bug where players with no previous forum post record had all of their "wants" at 0, instead of the dungeon's def_max
v1.4 Handle caching better and tweak some of the vprint() settings (9 will give debugging info now)
v1.03 Probably best if the forum post output is readable as input, eh?
v1.02 Fix what I broke while fixing the problem
v1.01 Fix distro function to give out last piece, not all but last
v1.0 Initial public release


  • dungeon_parser.ash
    59.7 KB · Views: 102
Last edited:


Dungeon Data File

You may want to refer to the enclosed data file and follow along. Note that to use it (and the script will abort if it isn't found), it should be put in the same "data" sub-directory used for other files, which should be named "Std_Clan_Mngmt_" + [url-encoded clan name].

First, you should know that the enclosed file has data for only one dungeon (The Slime Tube). Note that the key (Slime Tube) of this map is the same as the "parameter" field used for the Slime Tube tab in "registered_tabs.txt"; this is not a coincidence. For what it's worth, you could actually copy & paste this data, with a new key name, and if the rest stayed the same it would still be parsing the same old Slime Tube. Handy if we get another Crimbopolis. ;)

string name

Name used in-script and in forum-post to refer to the dungeon; doesn't have to match any other data, so it can get weird if you want (eg "Crimbopolis").

string tab_id

This must match key & name in "registered_tabs.txt" data file.

string distro_rules

Displayed below distribution drop-downs, to help the user make assignments.

string closing_rules

Helpful reminders for what to do with the post-distro data.

string div

This field is to tell the script which part of the dungeon log to look at; specifically, everything inside of the "div" html tag with an id that matches this field's value.

string chat

This field has not yet been implemented; eventually, the script will post a warning message to the appropriate channel as soon as the distro-assignment portion is loaded, in order to notify other admins that things are already being taken care of.

string id

KoL recently added the dungeon id inside of an html comment; it's preceded by a short string identifier that is different for each dungeon. This field should be set to that identifier.

boolean early_distro

If true, any loot waiting for distro is shown and available for distribution immediately; if false, the script waits until the dungeon is finished before giving assignment options.

string saved_points

While the script can track many different categories of "points" during an instance, only one will be saved and accumulated; this field must match the .cur key that is accumulated.

dungeon_action [int] actions

This field is of a record called "dungeon_action", with sub-fields string match, boolean eligible and float [string] mods.
  • string match is a string used in a regular expression; the simple example file will match any logged action. Note that the script adds certain parts (player name and id to front, number-of-turns identifier to end), such that you will only match actions, not loot distribution. The script stops checking for matches as soon as it finds one, so you should list these in order from "most specific" to most general, and don't forget to add to all points categories that are relevant. Note, one special match is required for proper functioning of the distro part of the script: a match (or several) that indicate the dungeon is "done" and assigns points to "DUNGEONDONE".
  • boolean eligible if true, matching this action means a player is eligible for loot. If false, a player who matched this line may or may not be eligible for loot, depending on their other actions. As such, as soon as a player has a single "true" match, they are counted as eligible.
  • float [string] mods is a map keyed by point category name, with a value equal to the multiplier. For instance, on a match with a key of "TURNS" and a value of "2.0", any match would increment that player's "TURNS" by 2 points for each action (if the dungeon log line says "5 times" or whatever, a total incrementation of 10 would occur).
string [int] table and string [int] general

The value for both of these should be a point category as above; they are both keyed by the order they should be displayed in. The latter is displayed as totals from all players in the dungeon; the former in a table, listed by player.

string [int] descriptions

Another map, the key corresponds to the key for a string [int] table field. This is how the accumulated formats are displayed. If the description contains "NNN" it will be replaced with the appropriate number; otherwise, the number is listed in parentheses after the description.

loot_category [int] loot

A map of a record called "loot_category" that is keyed by the name of its category (such as "Outfit"). For most purposes, you can think of the "category" as the "zap group." For instance, most clans don't track who has received hardened slime pants, who has the belt, yada yada; since the three are in a zap group, you'd normally check for X of Y received and let the player sort out individual items.

Fields of the "loot_category" record are boolean [item] things, which is a plural item map containing each item in the category; int priority, which (from smallest to largest) determine the display order in the summary table and forum post; int def_max, which is the default number a player would be listed as "wanting" to acquire if they haven't previously specified; and int cost, which is the amount of meat a player is charged to receive the item (note, if your dungeon is funded a different way than by loot distribution, you should set this to 0). This can be over-ridden during distro on a per-item basis (but only to "No debt," not to a different amount, at least through the script itself).

int eligible_cost

How much meat a player owes for becoming eligible for loot in the dungeon; if you charge by loot distribution, you'll probably want to set this to 0.

int max_cost

If you want to limit dungeon debts to a certain ceiling (say, the opening cost), set this to that amount. Note that you should set this to a -1 if you don't want to have a "cap" on instance debts. I dunno why I picked that number; I was probably tired. You could also set it to a rediculously high number if that makes you feel better.

string post_head and string post_foot

The forum post generated post-distro consists of three parts; the "header," the summary, and the "footer." The header will automatically include the dungeon name, id, and distro time in UTC, as well as a copy of the "loot distro" portion of the log (faked actually, to avoid a server hit). If anything else is desired before the summary, you should put it as the post_head value. Someday, I'll add in support for using stuff from the general fields here.

Next after the "header" is the summary, which is explained below under post_type.

Finally comes the "footer," which is likely to be a general note to your clannies or reminders of recent rules changes, or whatever.

string post_type

Different clans will want to put their summaries in differnt places, and not all forums support the same tags and display things the same. Eventually, I'd like to support all of the "major" players. For now, the only useful value here is "dot_padded" (technically you can set this to whatever you want, but it will use "dot_padded" anyway). There is also support for loading information from a "tabbed" style, but you'd have to create it by yourself (but it's probably the easiest way to get starting data out of a spreadsheet).

This type of post puts the player name and id first, then the loot in the form of (X of Y / A of B) etc., where each set is howmany items a player has out of how many they want. Finally, they will list their turns. If they didn't participate in this instance, it will be a single number of their running tally. If they did participate, it will be in the form of OLD + NEW = TOTAL. This will be followed by " / 0" if their turns were reset for receiving loot.

Finally, these lines for all players are wrapped in a "code" tag (square brackets), and padded with periods (dots) such that everything should line up the same.

Editof 2013-02-12:

Data file updated to include tracking of squeezes and HCO/N forum format update.


  • saved_dungeons.txt
    3.7 KB · Views: 95
Last edited:


RE: Change to version 1.6

Previously, most, but not all, of what was presented in the summary forum post was controlled in the dungeon's data file, so you could use phpbb style tags, raw html, whatever, with no need to change the actual code of the script. Except, I neglected to do that in one spot. That should be fixed; now, when the script uses hard-coded text (such as for the very first line describing the dungeon), it will look for a setting (see "clan_settings.txt") named "forum_style". If it's set to phpbb, it will use square brackets for things like bold and italics. Anything else currently defaults to html angle brackets.

For those HCN/O ers using this script, if you'd like the summary posts to have bolded text (instead of raw html tags) again, you'll need to add the above setting to the "clan_settings.txt" file (note: between the setting name and value is a tab, not a space), as well as edit the "saved_dungeons.txt" file. Only three lines need to have the html replaced with bbcode; the "descriptions" line, the "post_head" line, and the "post_foot" line. Just replace any instance of "<b>" with "" and similar for closing tags or other markup.


I did some work for Dreadsylvania. The script is heavily based on the slime tube one but without the haves/wants.
And defaults for debt/reset dropdowns were added.

dungeon_parser.ash needs a small adjustment to parse the saved_dungeons.txt
    boolean no_debt;
    boolean no_reset;
needs to be added to record loot_category.
Last edited:


I folded both parsers back into one file. The error message have seen some improvements. There is currently a problem with once per player items (i.e. hard mode combat items (bell, lice, citation pad and scissors)) when distributed to players who already have them. Best to distro them early, reset the script, distro the rest and merge posts/accounting afterwards.


  • registered_tabs.txt
    1.3 KB · Views: 107
  • saved_dungeons.txt
    16.5 KB · Views: 218
Last edited:


Some marginal fixes. Todo: distribute those combat items first and exit gracefully if that fails.


  • dungeon_parser.ash
    63.1 KB · Views: 68