Group File Format

The binary assets of the game are stored in a handful of files that I’ll collectively refer to as “group files” in this document. Each episode has one STN file and one VOL file; both are required for the game to function:

The astute will notice that all of the STN files, regardless of the episode they belong to, are bit-for-bit identical. This seems to be a core part of the rationale for the STN/VOL split – the base functionality that appears in all three games is identical, so the assets that accompany those features can be stored in and fetched from identical STN files. The VOL files, on the other hand, are all very different from episode to episode.

What do STN and VOL stand for?

That’s known only to the original designer(s) of the layout. If I were forced to wager a guess, I would say standard and volume.

A group file is simply a container that holds one or more entries. Each entry is a blob of data, indexed by a DOS-style (“8.3”) name. Entries within a group file are analogous to files within a directory on a disk.

There is no compression or encoding used anywhere in the group file format. What’s stored on disk is exactly what gets copied into memory.

Location

The group files are always opened relative to the DOS working directory when the game was started. This means that the user must CD to the directory containing the group files before trying to start the game.

If the working directory is not correct (i.e. entering CD \ and then something like C:\COSMO1\COSMO1.EXE), the game will fail to locate the group files. There is no error handling for this condition, and the game will crash with a bit of display garbage.

Header

Each group file contains a header structure listing entry names, offsets, and sizes (sort of like a table of contents or, more properly, a file allocation table).

The structure of one header entry is:

Each header entry occupies exactly 20 bytes, and the entries repeat one after another until there are no more entries to list.

Immediately after the last header entry, the total number of entries is encoded as an ASCII string (i.e. 32h 31h for "21"). I do not have enough specimens of this data format to definitively say if the number here is fixed-width, padded, or null-terminated.

Following this, the header is null-padded until offset FA0h. Regardless of the number of entries in each group file, the header is padded to be exactly 4,000 bytes long and, presumably, can hold at most 199 entries. (The 200th entry slot would contain the total count as an ASCII string.) Again, I do not have a specimen with that many entries inside, and it’s not at all clear what should happen in the corner cases that crop up when processing such a large header.

Reading Data

The data for all entries starts immediately after the header padding. The data is stored contiguously without special alignment or inter-entry padding. There is not even a requirement that entries start on an even offset; the evenness of so many of the offsets is a consequence of the fact that almost all the entry sizes are naturally even.

To read the data for any entry, first walk the header looking for an entry whose name matches the one needed. Read the offset and size values from that entry. Seek to offset, and read size bytes starting from there.

Note: Like most of the data in the game, the integer values for the offset and size are packed in little-endian order.

If the search arrives at an entry with a null name, or if the end of the 4,000 byte header is reached, all entries have been searched without finding a match.

As a pseudocode example, say we wanted to find the data named my.mni inside the group file COSMO1.STN:

fp = open("COSMO1.STN")
found = false

for (i = 0; i < 4000; i += 20):
    fp.seek(i)
    entryname = fp.read_string(12)

    if entryname == "":  # Put another way, it starts with a null byte
        # There are no more occupied entry slots
        break

    if entryname != uppercase("my.mni"):  # Header names are all-caps
        # Not looking at the right `entryname` yet
        continue

    # The `entryname` matches what we're looking for
    found = true
    offset = fp.read_integer(4)
    size = fp.read_integer(4)
    fp.seek(offset)
    data = fp.read_binary(size)  # `data` contains everything we want
    break

if not found:
    # `my.mni` is not in this group file

This format, while quite simple, is also flexible and immensely abusable. Some things that should be possible:

• Storing entry data in a different order than the header indexes it.
• Naming entries as arbitrary 12-byte strings with no dot, or a misplaced dot. The 8.3 naming style is merely a convention.
• Declaring the same name twice in the index (per the techniques described on this page, only the first entry would be accessible).
• Pointing multiple header entries to the same data, or partially-overlapping windows into some larger data.
• Creating slack space between the end of one entry’s data and the start of another. Data could be hidden in this way.

Much to my own disappointment, none of these techniques have been used in any of the group files that shipped with the game.

List of Group File Contents

For anyone who is curious what’s contained inside each group file, here is a dump of the header data. Each row contains a brief description of what that entry is used for in the game.

All offsets and sizes are in decimal bytes, to show the “round” nature of many of the entry sizes.

COSMO{1,2,3}.STN

Total entries: 21

COSMO1.VOL

Total entries: 36

COSMO2.VOL

Total entries: 37

Byte Pincher

COSMO2.VOL includes entries for MDRUMS.MNI and BDFOREST.MNI, neither of which is actually used by any of the maps in that episode. Omitting them would have shaved almost 43 KiB off the size of the file.

COSMO3.VOL

Total entries: 35

What does MNI stand for?

Why does everybody ask me things I don’t know? All I have is an educated guess: manifest.

If not that, maybe moniker or mnemonic.

Overall the entries are split up in a rational way. MZZTOP.MNI and MTECK4.MNI are the only entries that appear in all three VOL files. They would have been ideal candidates to be stored in the STN files instead, but for whatever reason they ended up where they did.

It appears as though a conscious effort was made to ensure entry names across different episodes were kept unique (for instance, END1/END2/END3 for the end story images and A1/B1/C1 for map one of each episode). If all the group files were extracted into the same directory, the only names that would conflict are identical copies of the same data (and PREVDEMO.MNI).

I see patterns where none exist.

There may be some archaeological significance to the order of the entries in each group file, with later entries having been changed/added more recently in the game’s development and testing. It’s also possible that I’m completely wrong about that.

The STN Files Have It All

If you look at what’s actually in the VOL files, you’ll notice there aren’t any sprites, tiles, cartoon images, or sounds anywhere inside. All of those come from the STN file, which means all that data is available in all the episodes – even the first shareware episode.

Episode one didn’t have the Red Jumper Creature, for instance. Or the Frozen Duke. It also did not have any story screens that showed cartoons of Cosmo jumping through a cave ceiling or speaking to Zonk. Nobody playing episode one should have encountered any of these, and yet all the graphical data that supported these elements was on the shareware disk.

Similarly, episodes two and three didn’t have the Cosmo family’s ship from the beginning of E1M1. Episode two didn’t have the Boss. The nontrivial amount of tiles needed to build these are nestled snugly in the STN file regardless, seemingly unaware that nobody ever intended to use them in these episodes.