|
|
| Line 1: |
Line 1: |
| − | ELVL Format now superecedes the [[RGN Format]].
| + | apple cows |
| − | | |
| − | The latest version can always be found at http://sscx.net/asss/extended-lvl-format.txt
| |
| − | | |
| − | <pre>
| |
| − | extended level file format
| |
| − | version 0.4
| |
| − | grelminar@yahoo.com
| |
| − | ------------------------
| |
| − | | |
| − | 0. note
| |
| − | | |
| − | this document is a work in progress. it often speaks about things being
| |
| − | implemented in asss. it's often wrong: implementation of the features
| |
| − | described in this document is still ongoing, and many features described
| |
| − | here are not yet implemented.
| |
| − | | |
| − | | |
| − | 1. background
| |
| − | | |
| − | the basic level format, in use for many years, supports two main pieces
| |
| − | of data: a bitmapped tileset for the map, and the tile data. the tileset
| |
| − | bitmap is optional. the file layout is relatively simple: the bitmap
| |
| − | comes first, if it's present, followed by tile data to the end of the
| |
| − | file. if the bitmap signature isn't present, applications assume the
| |
| − | whole file contains tile data.
| |
| − | | |
| − | to support advanced features that are already, or will soon be, possible
| |
| − | in asss, i'd like to propose a backwards-compatible extension of the
| |
| − | basic level format.
| |
| − | | |
| − | | |
| − | 2. goals
| |
| − | | |
| − | the primary goal is to make it possible to embed more metadata in level
| |
| − | files. this includes descriptive information about the creator of the
| |
| − | file and its intended use, but also some functional information.
| |
| − | | |
| − | the most important, and complicated, type of metadata that i'd like to
| |
| − | embed are regions. a region is just a set of tiles, usually but not
| |
| − | necessarily contiguous, plus some information describing how the server
| |
| − | (and maybe eventually the client) should treat that set of tiles.
| |
| − | | |
| − | | |
| − | 3. file format
| |
| − | | |
| − | 3.1. embedding metadata in lvl files
| |
| − | | |
| − | currently, level files have one of two formats:
| |
| − | | |
| − | <bitmapfileheader>
| |
| − | <bitmapinfoheader>
| |
| − | <color table>
| |
| − | <bitmap data>
| |
| − | <tile data>
| |
| − | | |
| − | or just:
| |
| − | | |
| − | <tile data>
| |
| − | | |
| − | for now, i'm just going to talk about level files that contain tilesets.
| |
| − | tileset-less files will be discussed later.
| |
| − | | |
| − | to preserve backwards compatibility with all the programs that read or
| |
| − | write level files (subspace, continuum, ssme, ssled, facts, subgame,
| |
| − | etc.), the beginning of the file will have to remain the same. the tile
| |
| − | data will also have to remain the last item in the file, since all the
| |
| − | level-file-reading code assumes that all the data from a specific point
| |
| − | to the end of the file is tile data. thus, the new data will have to be
| |
| − | inserted in the middle of the file, making it look like this:
| |
| − | | |
| − | <bitmapfileheader>
| |
| − | <bitmapinfoheader>
| |
| − | <color table>
| |
| − | <bitmap data>
| |
| − | <metadata/regions> <-- new stuff
| |
| − | <tile data>
| |
| − | | |
| − | the trick that makes this work is the fact that the bitmapfileheader
| |
| − | contains a field that specifies the total file size, which programs use
| |
| − | to locate the start of the tile data. (at least i hope they do. if any
| |
| − | program assumes the tile data directly follows the bitmap data, these
| |
| − | extended files will break it.) another nice feature is that header also
| |
| − | contains 4 bytes of reserved space, which we will use to point to the
| |
| − | metadata section.
| |
| − | | |
| − | for reference, the windows BITMAPFILEHEADER struct looks like this:
| |
| − | | |
| − | struct BITMAPFILEHEADER {
| |
| − | u16 bfType; // == 0x4D42 ("BM")
| |
| − | u32 bfSize; // the total size of the file, which is also
| |
| − | // the offset of the tile data
| |
| − | u16 bfReserved1; // previously reserved, but we're going to
| |
| − | // use this for our format
| |
| − | u16 bfReserved2; // this one is still unused, should be 0
| |
| − | u32 bfOffBits; // the offset to the bitmap data
| |
| − | };
| |
| − | | |
| − | so, to make an extended level file, lay out your two bitmap headers,
| |
| − | color table, and bitmap data as before, then the metadata section, and
| |
| − | finally the tile data. the metadata section should be aligned to start
| |
| − | at a multiple of 4 bytes from the start of the file, so you might need
| |
| − | 0-3 bytes of padding between the end of the bitmap data and the start of
| |
| − | the metadata. the metadata section will always be a multiple of 4 bytes
| |
| − | long, so the tile data will also always start on a multiple of 4 bytes.
| |
| − | | |
| − | set the bfReserved1 field to the byte position of the start of the
| |
| − | metadata section. typically, this will be 49720 bytes. also, the bfSize
| |
| − | value, which was previously almost always 49718, will now point to the
| |
| − | tile data, which will be located right after the extended metadata. so
| |
| − | for a file containing 4000 bytes of metadata, bfSize will be 53720.
| |
| − | | |
| − | note that this means from the perspective of a program that only
| |
| − | understands bmp files, or one that only understands plain lvl files, the
| |
| − | metadata is part of the bitmap. it just happens that the bitmap contains
| |
| − | more bits than is necessary for its dimensions and color depth.
| |
| − | | |
| − | to make an extended level file without a tileset, you simply start off
| |
| − | the file with the metadata chunk, followed by the tile data. WARNING:
| |
| − | currently no programs except asss understand extended level files
| |
| − | without tilesets.
| |
| − | | |
| − | | |
| − | 3.2. metadata format
| |
| − | | |
| − | now, the format of the metadata section itself. this is designed to be
| |
| − | extensible, so new features can get added to lvl files without
| |
| − | redefining the whole format. it's somewhat inspired by the png file
| |
| − | format, which was inspired by iff, etc.
| |
| − | | |
| − | first, there's a header:
| |
| − | | |
| − | struct metadata_header {
| |
| − | u32 magic; // == 0x6c766c65 ("elvl", for "extended lvl")
| |
| − | u32 totalsize; // the number of bytes in the whole metadata section
| |
| − | u32 reserved; // reserved, should be 0
| |
| − | };
| |
| − | | |
| − | magic should always be equal to 0x6c766c65. if it isn't, the file is
| |
| − | incorrect or corrupted. incidentally, the magic value is how extended
| |
| − | level files without tilesets can be identified. (that is, an initial
| |
| − | "BM" means an initial tileset, which may or may not contain extended
| |
| − | data, an initial "elvl" means an extended level file without a tileset,
| |
| − | and anything else is a plain level file without a tileset.) also note
| |
| − | that the magic value is an illegal value for tile data.
| |
| − | | |
| − | totalsize is the number of bytes in the whole metadata section,
| |
| − | including the header. note that the tile data will start at an offset of
| |
| − | totalsize bytes from the start of the metadata_header.
| |
| − | | |
| − | directly following the header is a series of "chunks". there is no limit
| |
| − | to the number of chunks. each chunk contains a chunk header:
| |
| − | | |
| − | struct chunk_header {
| |
| − | u32 type; // describes what this chunk represents
| |
| − | u32 size; // the number of bytes in the data portion of this
| |
| − | // chunk, _not_ including the header.
| |
| − | };
| |
| − | | |
| − | the header is followed by arbitrary data whose interpretation is
| |
| − | determined by the chunk type. the data portion of a chunk may be of any
| |
| − | length, including 0 bytes and odd numbers of bytes. if a chunk isn't a
| |
| − | multiple of 4 bytes long, it should be padded up to a multiple of 4
| |
| − | bytes so that the next chunk starts on a 4-byte boundary (but the
| |
| − | padding isn't counted in the size field, it's just understood to be
| |
| − | there).
| |
| − | | |
| − | an application can ignore chunk types that it doesn't know about. if
| |
| − | it's an editor that's loading and saving elvl files, it should probably
| |
| − | save the extra chunks and write them back to the file when it gets
| |
| − | saved.
| |
| − | | |
| − | there are several chunk types defined so far:
| |
| − | | |
| − | "ATTR" - defines a textual attribute
| |
| − | "REGN" - defines a region
| |
| − | "TSET" - defines a tileset
| |
| − | "TILE" - defines tile data
| |
| − | | |
| − | i'll describe their function and format one by one:
| |
| − | | |
| − | 3.2.1. "ATTR" chunks
| |
| − | | |
| − | these define miscelaneous textual attributes. the format is ascii text,
| |
| − | not null terminated, in this form: "<key>=<value>". each "ATTR" chunk
| |
| − | should contain just one key/value pair. multiple chunks of this type may
| |
| − | be present in one file.
| |
| − | | |
| − | some keys that might be typically found in a level file are:
| |
| − | | |
| − | "NAME" - a descriptive name for this map
| |
| − | "VERSION" - a version number for this map
| |
| − | "ZONE" - the zone this file is intended to be used with
| |
| − | "MAPCREATOR" - the person who created this map (the format of the value
| |
| − | should be "name <email>")
| |
| − | "TILESETCREATOR" - the person who created the tileset
| |
| − | "PROGRAM" - the name of the program that was used to create this level
| |
| − | file
| |
| − | | |
| − | 3.2.2. "REGN" chunks
| |
| − | | |
| − | these chunks define regions. to recap, a region is a set of tiles,
| |
| − | usually but not always contiguous, with certain properties. asss
| |
| − | understands regions and can implement some advanced features using them.
| |
| − | currently continuum doesn't understand regions, but it would be nice if
| |
| − | it did, and we'll be able to do even cooler things when it does.
| |
| − | | |
| − | there's a lot of stuff that you might want to say about a region, so to
| |
| − | support all the varied uses, and also future uses, we'll use the chunk
| |
| − | model again: each region gets its own set of "subchunks" describing its
| |
| − | function. to avoid confusion, all sub-chunk types that go inside the
| |
| − | "REGN" superchunk start with "r". the data of the big "REGN" chunk is
| |
| − | simply a series of subchunks.
| |
| − | | |
| − | here are some defined sub-chunk types:
| |
| − | | |
| − | "rNAM" - a descriptive name for the region
| |
| − | "rTIL" - tile data, the definition of the region
| |
| − | "rBSE" - whether the region represents a base in a flag game
| |
| − | "rNAW" - no antiwarp
| |
| − | "rNWP" - no weapons
| |
| − | "rNFL" - no flag drops
| |
| − | "rAWP" - auto-warp
| |
| − | "rPYC" - code to be executed when a player enters or leaves this region
| |
| − | | |
| − | 3.2.2.1. "rNAM" chunks
| |
| − | | |
| − | this is just a plain ascii string, not null terminated. every chunk
| |
| − | should have exactly one of these.
| |
| − | | |
| − | 3.2.2.2. "rTIL" chunks
| |
| − | | |
| − | this subchunk describes the tiles that make up the region. it's stored
| |
| − | in a compact rle-ish representation.
| |
| − | | |
| − | conceptually, a region is some subset of the 1024x1024 tiles in the map.
| |
| − | to encode a region, encode it row by row, left to right, top to bottom.
| |
| − | | |
| − | for each row, split it into runs of empty tiles and present tiles. for
| |
| − | each run, output one of these bit sequences:
| |
| − | | |
| − | 000nnnnn - n+1 (1-32) empty tiles in a row
| |
| − | 001000nn nnnnnnnn - n+1 (1-1024) empty tiles in a row
| |
| − | 010nnnnn - n+1 (1-32) present tiles in a row
| |
| − | 011000nn nnnnnnnn - n+1 (1-1024) present tiles in a row
| |
| − | | |
| − | for the two-byte sequences, the bits in the second byte are the low
| |
| − | bits, and the two bits at the end of the first byte are the high bits.
| |
| − | | |
| − | for example, if you have a run of 10 present tiles, you'd output the
| |
| − | byte 01001001, or 73 decimal. if you have a run of 300 empty tiles,
| |
| − | you'd output 00100001 00101011, or 33 43.
| |
| − | | |
| − | for each row, you must output a sequence of runs that sum to exactly
| |
| − | 1024 tiles. anything else (missing tiles at the end of a row, or a run
| |
| − | that extends past the end of the line) is an error.
| |
| − | | |
| − | there are two exceptions to the above rule: first, rows that contain no
| |
| − | tiles at all can (optionally) be encoded specially:
| |
| − | | |
| − | 100nnnnn - n+1 (1-32) rows of all empty
| |
| − | 101000nn nnnnnnnn - n+1 (1-1024) rows of all empty
| |
| − | | |
| − | second, if the same pattern of tiles appears in more than one
| |
| − | consecutive row, you can use these special codes to save more space:
| |
| − | | |
| − | 110nnnnn - repeat last row n+1 (1-32) times
| |
| − | 111000nn nnnnnnnn - repeat last row n+1 (1-1024) times
| |
| − | | |
| − | the rTIL chunk must describe exactly 1024 rows. this might require only
| |
| − | two bytes (163 255 for the totally empty region), or it might require
| |
| − | much more.
| |
| − | | |
| − | note: several bit patterns don't correspond to any of the above codings.
| |
| − | that's deliberate. don't use them.
| |
| − | | |
| − | 3.2.2.3. "rBSE" chunks
| |
| − | | |
| − | this is a 0-byte chunk. its presence signifies that this region should
| |
| − | be considered a "base".
| |
| − | | |
| − | 3.2.2.4. "rNAW" chunks
| |
| − | | |
| − | this is a 0-byte chunk. if present, antiwarp should be disabled for
| |
| − | ships in this region. currently, this disabling happens on the server,
| |
| − | and players whose antiwarp is being disabled aren't necessarily aware of
| |
| − | it. it would be nice if in the future continuum understood this feature
| |
| − | so that it could inform the player that antiwarp is unavailable in this
| |
| − | location.
| |
| − | | |
| − | 3.2.2.5. "rNWP" chunks
| |
| − | | |
| − | this is a 0-byte chunk. if present, all weapons are non-functional in
| |
| − | this region. the same notes apply to this feature as to the no antiwarp
| |
| − | feature.
| |
| − | | |
| − | 3.2.2.6. "rNFL" chunks
| |
| − | | |
| − | this is a 0-byte chunk. if present, any flags dropped in this region are
| |
| − | respawned as neutral flags in the center of the map (or wherever the
| |
| − | settings indicate they should be spawned).
| |
| − | | |
| − | 3.2.2.7. "rAWP" chunks
| |
| − | | |
| − | this chunk, if present, turns on the auto-warping feature. any player
| |
| − | entering this region will be immediately warped to the specified
| |
| − | destination.
| |
| − | | |
| − | the data for this chunk specifies the destination, in this format:
| |
| − | | |
| − | struct autowarp_destination {
| |
| − | i16 x; // the destination x coordinate, 1-1023, 0 for the
| |
| − | // default, or -1 for the player's current x coordinate.
| |
| − | i16 y; // the destination y coordinate.
| |
| − | char arena[16]; // the destination arena name. null if the warp
| |
| − | // does not cross arenas.
| |
| − | };
| |
| − | | |
| − | as a simple space optimization, if the warp does not cross arenas, you
| |
| − | can leave out the 16 bytes of arena name, so that the whole chunk data
| |
| − | is 4 bytes long.
| |
| − | | |
| − | 3.2.2.8. "rPYC" chunks
| |
| − | | |
| − | this chunk lets you embed code in level files. the exact semantics of
| |
| − | this data haven't yet been determined, but it'll probably go something
| |
| − | like this:
| |
| − | | |
| − | this chunk should contain ascii data representing some python code. the
| |
| − | code will be executed when the map is loaded, and it may define several
| |
| − | functions: a function named "enter", if it exists, will be call each
| |
| − | time a player enters this region. it will be called with one argument,
| |
| − | which is the player who entered the region. a function named "exit"
| |
| − | works similarly, except of course it gets called when someone leaves.
| |
| − | | |
| − | | |
| − | 3.2.3. "TSET" and "TILE" chunks
| |
| − | | |
| − | these chunk types are intented to be used only in the far future, when
| |
| − | all lvl files use the extended format, and the backwards-compatible
| |
| − | format described so far doesn't have to be used. such files will start
| |
| − | with the "elvl" metadata header described above, and they will contain
| |
| − | the tileset bitmap and tile data as chunks.
| |
| − | | |
| − | the format of a "TSET" chunk is a windows format bitmap, _without_ the
| |
| − | bitmapfileheader stuff (because its function is taken care of by the
| |
| − | chunk header). that is, it starts with a bitmapinfoheader, which is
| |
| − | followed directly by the color table, which is followed directly by the
| |
| − | bitmap data. the bitmap data should be in 8-bit format with no
| |
| − | compression.
| |
| − | | |
| − | the format of a "TILE" chunk is just tile data, in the same format it's
| |
| − | always been in:
| |
| − | | |
| − | struct tile {
| |
| − | unsigned x : 12; // range 0-1023, upper two bits should be 0
| |
| − | unsigned y : 12;
| |
| − | unsigned tile : 8;
| |
| − | };
| |
| − | | |
| − | there should be no more than one of each of these chunks in a file. one
| |
| − | file should not contain both an ETST and a TSET chunk. if a file
| |
| − | contains neither of those two types, the default tileset should be used.
| |
| − | | |
| − | | |
| − | 4. comments
| |
| − | | |
| − | if you have an suggestions for improving the file format or this
| |
| − | document, email them to grelminar@yahoo.com, or post them on the forums
| |
| − | at http://forums.minegoboom.com/
| |
| − | | |
| − | | |
| − | 5. history
| |
| − | | |
| − | version 0.3:
| |
| − | - removed ETST chunks, since cont basically supports this
| |
| − | functionality already through tiles.bm2
| |
| − | | |
| − | version 0.2:
| |
| − | - better format for region tile data
| |
| − | | |
| − | version 0.1:
| |
| − | - initial version
| |
| − | </pre>
| |
| − | | |
| − | [[Category: Formats]]
| |
| − | [[Category: Map]]
| |
