Official development blog

Morgue Files

Death is fairly frequent in roguelikes, but the fun doesn’t stop there! We usually still have access to post-game “content” in the form of text files detailing how a particular run played out.

The typical traditional roguelike player tends to love statistics describing their performance, and detailed morgue files are a good way to satisfy that desire, while at the same time enabling players to show off achievements, get opinions from other players, and review an experience to perhaps learn more from it. Looking back through an overview of their game, a player might discover something they hadn’t noticed before, or the file may directly reveal unknowns like the fully identified contents of one’s inventory. (I had a potion of what?!)

Other Roguelikes

A lot of the major roguelikes have been modernizing their community services with extensive public databases that allow for searching, sorting, and all manner of additional features. (References: DCSS Online Players and Scoring Overview; ToME4 Characters Vault; Angband Ladder; Nethack High Scores) I’ve written a little bit about Web Support in Single-Player Roguelikes before, while here we’ll just be focusing on a survey of text info data referring to a specific run/character.

morgue_file_DCSS

DCSS morgue file header (complete file).

DCSS begins with a summary of vital information, followed by:

  • basic character stats and status
  • detailed descriptions of each inventory item
  • dungeon locations visited and features discovered
  • message log and map immediately before the run ended
  • complete list of kills
  • long list of important chronological notes from throughout the run
  • chart containing a breakdown of all major actions taken

I really like the density of information at the top, probably the best example of a character file where so many details are available without scrolling--even equipped items are summarized right there. The actions chart found at the end is an interesting tool for reviewing general strategy and comparing it to other runs.

morgue_file_DoomRL

DoomRL morgue file header (complete file).

DoomRL also begins with an overall summary, though subsequent sections come in a somewhat unexpected order, seemingly aimed at front-loading information reflecting final results:

  • special levels
  • awards earned
  • snapshot of the map/surroundings where the run ended
  • basic character stats
  • equipment and inventory items
  • complete list of kills
  • history of important events
  • message log immediately before the run ended
  • meta information comparing previous runs

My favorite part of this one is the history, which in describing only important events in a condensed format does a better job of telling the story of the run than a full message log can. I’d like to incorporate something similar into Cogmind, later when story elements are in place and such a feature would be a lot more meaningful.

Meta info tracking the player’s progress from other runs is a nice addition, too, though here it’s quite limited.

morgue_file_Angband

Angband morgue file header (complete file).

Angband’s file opens with a very dense block of character stats, then:

  • detailed equipment list
  • carried inventory items
  • home inventory items
  • history of important events and when/where they occurred
  • UI/game options

As with DCSS, I like the density up front, the one drawback being that it is more complicated to parse when writing code to scrape the data. The best way to handle this is of course to store the information in a separate format meant to be parsed, then it can be output in any format necessary. Nethack, for example, does exactly this with its Xlogfile format, but it surprisingly doesn’t have human-readable morgue files, at least nothing official. The online system linked earlier does record and display basic run information, however.

morgue_file_ADOM

ADOM morgue file header (complete file).

ADOM begins with a complete screenshot of the final game state, map, stats and all, followed by:

  • character background
  • equipped items list
  • backpack (inventory) contents
  • weapon skills
  • skill list
  • spell list
  • major achievements
  • artifacts generated
  • other player characteristics
  • monsters vanquished
  • meta data (play time, version)

The screenshot opening is a nice approach, as it provides a pretty effective summary, which honestly a good UI should be capable of in the first place--putting it directly into the log reflects that effectiveness. ADOM is capable of outputting the character log in both an abbreviated and verbose form (the latter is what’s shown above).

Format

All of the above games provide their morgue files in a simple text format, enabling players to easily share/paste them on forums or elsewhere. Of course an alternative is to just link directly to an online record, text or not, which is currently the only way to share complete character information in ToME4, for example. That does have the advantage of providing a more interactive experience for understanding the contents (ex: ability descriptions), though the information itself isn’t as easily posted elsewhere in a predefined format.

Terminology

There is no common term for referring to these files throughout the genre. In fact, there are almost as many terms as there are games…

  • Character File: The official term for DCSS morgue files, and the most generic of the bunch that doesn’t really have any additional connotations, except that it perhaps doesn’t imply that a run has ended. Technically this one’s generic enough that it could be confused for a save file.
  • Morgue File: Generally associated with DCSS as well, though not an official term. (It happens to be the one I’ve picked up on.) The name implies that a character is dead, and therefore may not feel all that appropriate for victories (although as we know death is more common). That said, your character will die eventually, right? :) (On that note, even when you win UMoria, it will indicate that you died of “ripe old age.”)
  • Character Dump: This term implies that the information might have been exported from a game still in progress, though Angband uses it even for completed games.
  • Post-mortem Character Dump: DoomRL adds a qualifier to indicate that the run has actually ended.
  • Character Log: The ADOM community uses this one (though it’s not written anywhere in the file itself); it’s pretty generic and applies well enough to this use, although there is that chance of confusion between a record of everything about a character and just the message log itself.
  • Character Record: Another generic term used by some games not discussed here.
  • YASD/YAVP: Colloquial abbreviations that can just as easily refer to the files themselves as they can the final outcome, adding a little extra meaning since we know both that the run ended and how.

Not that terminology is super important; I just thought it was interesting to note while doing this survey.

Cogmind Score Sheets

I’ve always called Cogmind’s morgue files by yet a different name (of course…): score sheets. When first created the intention was to essential just show a score breakdown and a handful of character stats, but even early on that changed rapidly and score was left as only a very small portion of the file contents…

History

Shortly after Cogmind’s birth for 7DRL2012 I decided to hold a player tournament for fun, but felt that basing it on score alone wouldn’t by very exciting, so the first update in preparation for that was to add to the score sheet a variety of other collected stats that described the player’s run. Not just the number of kills on enemy type X, but also some less obvious values like “number of tactical retreats,” “shots fired from each class of weapon,” “number of items of each type lost to attrition,” etc.

At the time there were 78 variables, along with a few separate lists of varying types. These served as the basis for a more interesting tournament while I was still working on improving the game by implementing feature requests.

Then of course as a little side project the game was put on permanent hiatus with no plans to revive it.

Then of course “no plans to revive it” turned into making it something really big, and throughout more than a year of pre-alpha development I kept adding more of those score sheet variables as new features were added (and I came up with more ideas).

Now we have 350 of them.

Score Sheet 0.10

After completing the above survey of morgue files in other games, I’m surprised that none of them go as far as to record numerous statistics describing events or highly specific actions that shed light on player behavior, or derive other meaningful stats from the game data. (The DCSS action chart is a notable exception, but still limited in scope.)

Perhaps it’s that Cogmind is much more a tactical game than a strategic one. Most roguelikes on the other hand have a strong emphasis on long-term character development and therefore recording and reporting information about the player characters themselves already tells you so much. That’s where a majority of the gameplay decisions are reflected, whereas in Cogmind there is almost no emphasis on character development at all; instead it’s a game about making minute-to-minute decisions without certainty that your condition or form will be even remotely similar on the next floor, or even around the next corner. As such, the focus of a score sheet should be more about actions, behavioral statistics, and factors external to the character.

To be more specific, here are some of the variables recorded for each run in Cogmind:

cogmind_morgue_file_stat_excerpt

Cogmind score sheet excerpt; data columns doubled up to save space / show more.

In any case, without additional variables like these Cogmind’s score sheet would be pretty barren. Having all the extra data also came in handy when the recent Alpha Challenge 2015 took a page from the 7DRL tournament playbook and added lots more achievements based on them. With data like this there are also the many useful graphs that come out of comparing runs or combining data from multiple players as shown in the previous post about player metrics.

As with the other games, let’s look at the header of a Cogmind score sheet then discuss the contents:

morgue_file_Cogmind

Cogmind morgue file header (complete file).

(The first thing you’ll notice is it doesn’t use horizontal space very well. More on that later.)

Cogmind begins with a complete score breakdown, then:

  • player stats
  • attached parts
  • inventory contents
  • peak state
  • favorite item of each type and subtype
  • many gameplay stats (e.g. the earlier variable lists)
  • list of identified prototype items
  • meta data (play time, UI preferences, etc.)

So-called “peak state” is very important, added because unlike characters in other roguelikes, most Cogminds die naked and alone. Sad, I know. We’d never know what a player’s equipment really looked like if only recording it at their point of death (unless they made it to the surface, as in the sheet shown above).  So the game also shows what a fallen Cogmind looked like at their best, defined as when the combined combined rating of all their attached parts is at its highest.

cogmind_morgue_file_peak_state_examples

Sample peak states, for fun :D.

Because Cogmind’s gameplay revolves tightly around the items you use, which may change significantly throughout a game (since there is no such thing as skill/class/race limitations that might lock you out of using anything in particular), simply looking at peak state is only informative about a relatively short duration of the run. To tell us more, there are lists of favorite items of each type, further divided into subtypes:

cogmind_morgue_file_favorites_examples

Sample favorite item lists, for double the fun.

Taking the bottom-left list as an example, while that player may have been a hovering hacker bot at their peak state, according to their favorites they spent most of the game as a treaded heavy weapons platform.

Format

Having become bloated by simply tacking on more and more variables, while the content is sufficient the score sheet’s overall format is far from perfect, with its combination of vertical lists and simple VARIABLE=VALUE format all the way down. All that horizontal white spice should be put to work as we see in the DCSS and Angband morgue files. Many variables could be expanded to show more details, reorganized into meaningful charts, and more…

I’d really like to redesign the entire file to better condense the information, though as mentioned earlier that’s a problem for parsing. Using two files, one machine-readable and one human-readable, isn’t the greatest solution since players tend to share human-readable files so there would be no way to easily import a file shared that way. However, seeing as the game directly uploads the score sheets now anyway, maybe that would be a route worth considering. Upload a non-human-readable version of the data which is easy to parse, while separately outputting a local text file for the player’s own records.

Additional Post-Mortem Features

Like many other roguelikes, at the end of a run Cogmind shows a summary window. It contains a complete score breakdown (there aren’t all that many score components) as well as select stats, serving as an abbreviated version of the score sheet.

cogmind_gameover_screen

Cogmind gameover screen.

Because a full message log is too verbose to include in the score sheet itself and there is no short version yet, that is not included. Instead, in the options menu the player can choose to not save it (the default) or output it to either a text or html file. The latter has the advantage of being able to use the same colors as the in-game log, making it easier to parse.

cogmind_message_log_output

Sample message log output, the same segment in txt (left) and html (right).

I thought this would be enough, but players have since requested even greater detail in the output logs to better follow progress of the game when re-reading it for learning purposes.

The Possibilities!

Outside the existing score sheet and log files, there is the potential for quite a few other related features that serve similar purposes, or present the same information in a different form. Keep in mind that none of what I mention below is 100% certain to happen, but with unlimited time (haha) I’d love to be able to at least test, if not implement, many of these features:

Dumps

Mid-game character dumps are useful for sharing progress and getting feedback online, so it would be nice to have a dedicated way to do that.

Image sharing is so common on the web now I’m not sure how many players would bother to use a text-based dump option if available. The latter is less readable due to lack of color information, and any time someone pastes/views it without a monospace font it would look terrible, but I put together a mockup anyway:

cogmind_progress_dump_sample_text

Progress dump mockup (text version).

The current stand-in method for character dumps--a simple screenshot of the HUD--already works pretty well (and is what players have been using) since it shows nearly everything you’d want to know. Its primary drawback is an inability to show more than 12 inventory items at once, an issue for some combat builds. Screenshots are also exceptionally wide for those players using high resolutions since it uses their font settings, making them harder to view on smaller screens.

By rearranging some of the existing windows I put together a mockup of a somewhat more condensed “image-style progress dump,” though this one doesn’t look so great, and is too wide.

cogmind_progress_dump_sample1

Progress dump mockup (image version, style 1).

Instead here’s an alternative mockup of a truly condensed version without any secondary information--it’s nice and tight, and includes space for a lot more inventory items, but no map:

cogmind_progress_dump_sample2

Progress dump mockup (image version, style 2).

Even cooler would be a way to output your current build--or peak state from a run--using the game’s ASCII art to represent the items. Unfortunately at the high end you can have so many parts that the combined art wouldn’t fit within any reasonably sized image.

Score Sheet 1.0

By the time the score sheet is complete, it should include not only more stats, but also expand to contain a written summary of a run’s history, told like a story, as well as a world map showing the route taken through the world.

cogmind_world_route_text

World route mockup (text).

Along with the score sheet, there might also be an option to output an accompanying image of the entire last floor explored (not just the part viewable on the screen). This wouldn’t uncover unexplored areas (which would too easily reveal secrets), but players could at least learn something about map layouts without having to try to map it themselves (we’ll leave that practice in the 80s, or to games with smaller maps). The problem there being that maps can get quite huge, not to mention the data loss to corruption by this point:

cogmind_map_route_output_sample

Explored map image (sample). (Click for full size.)

It would be a nice addition if the map also highlighted the specific path taken through the map.

Long-Term Performance

For those players who can’t or don’t want to upload score data, we could add a local history of personal high scores. Taking that a step further, we know that roguelike players appreciate more data, so why not track even more performance indicators over time.

Currently the results of each run are stored and viewed in complete isolation, except that each record shows the total number of runs that came before it, and a meta data file stores which items have been discovers and allows their art and usage counts to be viewed in the gallery.

cogmind_performance_graphs_mockup

Some examples of performance graphs/charts that could be interesting (mockups).

I can see this being a huge development time sink for too little value if not limited to only a handful of the most useful data.

Another much simpler yet more granular approach to progress, is to have a place where players can review what discoveries they’ve made in the game so far. We already have this in the form of an “art gallery” that shows all the items collected throughout previous games, including their name, ASCII art, and how many times each was found and used (plus of course a name chosen by the item’s associated early supporter as a perk).

cogmind_art_gallery_alpha3

Cogmind’s in-game art gallery, with data and discovered/used items from my own runs (click for full size). DON’T OPEN THIS AND LOOK AT THE PLAYER NAMES if you are an alpha supporter and would like to discover your item for yourself!

This feature is a great incentive to keep players exploring, while showing just how much more there is to discover (a lot!). Recording the number of times each item has been used also gives this feature some statistical value for even those players who’ve discovered most of the items (discovering all of them is impossible at this point, since many of the best ones can’t yet be found).

It would be nice to expand this to include other parts of the game, such as types of maps and robots (however, I don’t believe I’d be drawing the latter).

Online Database

As mentioned before, it would be nice to have an online database with sortable tables and customizable graphs based on the data. Before we get to that point, I may further expand the current leaderboards by increasing the number of generated html pages to at least include some sortable charts that also link directly to individual records. I’m not rushing into that since I would want to make sure it’s somewhat future proof when it comes to new versions.

For the tournament I already wrote a data parser which scrapes a directory for all of its score sheets and compiles everything into a single CSV file. That formed the basis for the stats and analysis I shared earlier.

cogmind_AC2015_stats_csv

Complete CSV data from the tournament, 234,048 fields in all :D.

 

Update 190724: Since this original article I revisited Cogmind’s morgue files to greatly expand them even further, and wrote up a series of articles about what goes into “Building the Ultimate Roguelike Morgue File.” Cogmind’s leaderboards and online database have also since been revamped.

This entry was posted in Meta and tagged , , , , . Bookmark the permalink. Trackbacks are closed, but you can post a comment.

13 Comments

  1. Posted October 21, 2015 at 5:49 am | Permalink

    I like how you started with a well-rounded comparison of major roguelikes, even delving into terminology and then moving on to some neat ideas and innovations! I’d certainly like to see more of that :)

    I took the liberty of linking this article back at RogueBasin http://www.roguebasin.com/index.php?title=Articles#Interface

    On the negative side there are a couple of revision slips throughout the post, and I’d have preferred code blocks instead of images for the example files when possible, but it certainly didn’t detract from the quality of the analysis. Good luck with further development!

    • Kyzrati
      Posted October 21, 2015 at 8:55 am | Permalink

      Ouch, by “revision slips” do you mean editing errors? I really should’ve proofread this article. I was tired after a long trip before publishing and this is the very first article I’ve ever posted without first doing a final proofread :/

      I should go back and do that now…

      Edit: Maybe you meant something else? I just proofread and found no errors.

      (Regarding code blocks, I considered it but don’t have a good format for that on my blog since I don’t normally use them, so I instead linked to the original file for each.)

      Thanks for linking to the article--I sometimes feel I should go back and add some content to RogueBasin myself, since the articles there were where I got my own start a while back, and I haven’t contributed anything to the articles section despite having written on many of those topics since. (Instead I guess I do the part by maintaining FAQ Friday on /r/roguelikedev :D; I do plan to eventually add a page about that to RogueBasin when it’s even further along.)

      I did enjoy going through and doing real research on other games--there’s a lot of opportunity for meaningful work like that in the genre. It’s just very time-consuming, and in many cases doing a topic justice would require playing the game, or having sufficient prior experience with it. Morgue files are a convenient exception since they’re an isolated feature that doesn’t require play, and not too hard to find.

      I do have a couple other topics I’d like to compare across multiple roguelikes, at least one of which would require diving deeper into the details of each one. And I’ve done this a few times before, like with the Fonts in Roguelikes article and a few comparison images like those seen in Traps, though in most cases the research is not as in-depth as seen this time. (I tag articles containing info about other games with “roguelikes“.)

      • Posted June 25, 2016 at 2:21 am | Permalink

        Sorry for the late reply. Yes I did mean writing errors, but I’m not taking the time to read it again myself now since I’m busy, sorry!

        And by all means do take the time to add your own articles to roguebasin! I mean it, it will take you probably half an hour and not only promote your own work (posts and game) but also help out the entire community! You could add the link to your reddit stuff as well since those are usually pretty rich. I don’t mean transposing your entire articles to the site, just adding links there should be fine -- it would be great because there are a lot of outdated resources there as well.

        I’ll definitely read your article on traps too later on. This is something I was thinking about myself for Javelin (by the way watch out for a big release in a week or two, if you want to try out the game)!

        • Kyzrati
          Posted June 25, 2016 at 2:49 am | Permalink

          Hehe that was a late reply :P

          Oh I hadn’t realized you were the JavelinRL dev--you’re pretty far along now and should consider signing up for Feedback Friday on /r/roguelikedev :)

          True that the Basin is becoming increasingly dated, though at least a lot of the content is pretty timeless. It’s just lacking compared to the growing wealth of information found in other places on the net. I should take some time to fix that at some point! Some of my relevant Reddit posts I’ll also be fixing up and putting on the blog eventually, too. The first is coming next week…

  2. kripto
    Posted October 21, 2015 at 8:25 am | Permalink

    Fascinating as always. I like the idea of the graphical representation of your loadout, but it would definitely be just impractical more than anything :p

    Is one of the stats that are tracked/displayed “How many times you hit yourself with your own guns” ? I feel like that would be ridiculously high for me, since I often just find myself unwilling to clear swarms the reasonable way and just shooting my less severe explosives in point-blank range. It’s possibly the closest you can get to a ” questionable decisions ” counter.

    • Kyzrati
      Posted October 21, 2015 at 8:58 am | Permalink

      That’s a good idea for a stat! I don’t have that one right now, but it’s definitely going in there :)

      Certainly you want to try to avoid situations like that, but once you are already in such a situation, point blank explosives can sometimes be the lesser evil. We could also record the total amount of self-inflicted damage in such attacks.

  3. *Weaver
    Posted October 25, 2015 at 1:37 pm | Permalink

    The biggest thing missing from both the the end-of-game screen and the log/score files is WHAT THE HELL KILLED ME?! … at least once I’ve died walking down a hallway and I think it was a trap maybe but…

    Great read here, though :3

    • Kyzrati
      Posted October 25, 2015 at 1:49 pm | Permalink

      Good point! That’s something that was never updated from the 7DRL, despite the growing number of possibilities since then.

      Originally the only source of damage was being shot at, so reasons for death were those that the game will list now--core destroyed (by hostile fire), suicide, or system corruption (pretty much impossible). Now we have some potential new causes such as exploding machines and traps, all of which still just fall under “core destroyed.”

      Thanks for letting me know; I’ll expand that feature in the future. I can see it showing a very specific reason, e.g. robot X with weapon Y, an explosion of machine Z, or even your own AoE weapon W ;). (I wouldn’t want to develop a system for that too soon because as with any feature related to many different parts of the code it makes more sense to wait until most of the potential related elements are in place. But it shall be done!)

      Thanks for reading!

  4. Posted December 30, 2016 at 5:38 am | Permalink

    Would it be possible to implement replay files in cogmind? There is support for custom seeds, and I imagine the game state can be reliably reconstructed by providing the same inputs.

    • Kyzrati
      Posted December 30, 2016 at 7:54 am | Permalink

      Unfortunately not really, no. If it were possible to do well I would definitely do it, but the way the animation system was put together (the results of actions are dependent upon the animations themselves, and not predetermined), I believe it’s theoretically possible (not sure…) for the results to diverge depending on the system playing the game. That and the source would need to force different RNGs for logic and everything that’s not logic, which would be a rather big project to implement and test.

      Replays are essentially something that should be built into the architecture from the start, but this engine and game have been expanding for many years with no such considerations :P. Too late now!

      Still, maybe one day I’ll at least take stock of what might need to happen in order to allow for replays (post 1.0, of course). I did test a replay system back when first building this engine in 2011, but it didn’t seem too compatible with the animation system, so I gave up after a couple days. However, I later incidentally discovered that those tests may very well have failed due to an unrelated oversight in the code xD. So maybe it’s not impossible after all…

      It’s a good point you bring up, though! Replays are definitely a fun and interesting form of post-game information. That said, with any long game it’s naturally going to be important for a replay to be fast-forwarded, and that’s significantly more complicated with Cogmind because the animation speed cannot be adjusted :/

  5. Anonymous
    Posted July 19, 2018 at 3:56 pm | Permalink

    What’s the font you’re using in the screenshots of the morgue files (especially near the top)?

    • Kyzrati
      Posted July 19, 2018 at 4:16 pm | Permalink

      All the morgue screenshots were taken directly from my browser, which for text files uses my default system font MingLiU. It’s a cool-looking monospaced font which is also pretty easy to read and still has that traditional look :)

      For these shots in particular I zoomed out to 70%.

Post a Comment

Your email is never published nor shared. Only the anti-spam entry is required. See here for the privacy policy.

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>