Jill of the Jungle Map Format
From ModdingWiki
The Jill of the Jungle map format is the format used to describe the levels played during the game. The maps contain two layers - a background layer and an "object" layer. The background layer is a grid of 16x16 pixel tiles, 128 tiles wide and 64 tiles high. The object layer is made up of an arbitrary list of objects, with X and Y offsets in pixels.
Contents |
File format
The main map file starts off with the background layer, then immediately following it is the foreground layer.
Background layer
The background layer is quite simple. It is an array of 8,192 16-bit values (128 tiles wide by 64 tiles high == 8192 tiles total.) Each 16-bit value is a code, such as 0xC0D3. The formula ((x * MAP_HEIGHT) + y) * 2 (where MAP_HEIGHT is 64) will provide the offset (in bytes) into the map file where that grid's 16-bit code is located.
Once the code is found, its lower three nybbles are isolated (e.g. code & 0xFFF) which provides an ID that is listed in the tile mapping table (see below.) The tile mapping table then provides an index into the graphics file for the image that should be displayed at that grid location.
For example, if the 16-bit code is 0xC0D3, then isolating the lower three nybbles will provide the number 0x00D3. At the entry for ID 0x00D3 in the tile mapping table, the value might be 0x1234. This means that in the graphics file, tileset number 0x12 should be accessed, and tile number 0x34 within that tileset should be drawn at the grid coordinate. Note that tilesets seem to start from one (not zero) so you may need to subtract one from the tileset value to get the correct tile.
It is also important to note that these values are stored little-endian, like the SHA format. This means that for example the value 0xC0D3 is stored as the two bytes D3-C0, not as C0-D3.
Tile mapping table
There is a separate file in the game directory that contains mappings between tile codes in the background layer and the game's graphics. In Jill of the Jungle this is called JILL.DMA and in Xargon it is TILES.XRx.
This file is arranged as an array of entries, one after the other. Each entry is in the following format:
| Data type | Description |
|---|---|
| UINT16 iMapCode | ID used in map file |
| UINT16 iTileset | Index of tileset containing this tile's image |
| UINT16 iTile | Index into the tileset |
| UINT16 iFlags | Flags for this tile (can stand on, can hurt player, etc.) |
| UINT8 iLength | Length of tile name |
| char cName[iLength] | iLength characters for the tile name. This string is not NULL-terminated. |
Notes:
- iTileset seems to contain some larger values too. It is usually constrained for this reason (e.g. safe value = iTileset & 0x3F)
- iTileset seems to use 1 as the first tileset (not 0 as you might expect.) This means you may have to subtract one to get the correct index to the tileset.
iFlags is broken up as follows:
| Bit | Hex | Name | Description |
|---|---|---|---|
| - | 0x0000 | <zero> | Default solid block |
| 1 | 0x0001 | F_PLAYERTHRU | Blocks you can walk, jump or fall through (background tiles, the path on the overhead map, etc.) |
| 2 | 0x0002 | F_STAIR, F_NOTSTAIR (Xargon) | Blocks that you can stand on (can also jump up through when combined with F_PLAYERTHRU) |
| 3 | 0x0004 | F_VINE, F_NOTVINE (Xargon) | Can climb this block - usually combined with F_PLAYERTHRU (giving 0x0005) |
| 4 | 0x0008 | F_MSGTOUCH | Activates game-specific code when touched |
| 5 | 0x0010 | F_MSGDRAW | Regular blocks have just one shape, f_msgdraw triggers msg_block(msg_draw) for animated blocks. |
| 6 | 0x0020 | F_MSGUPDATE | game-specific code (through msg_block(msg_update)) at every frame. For animated blocks. |
| 7 | 0x0040 | F_INSIDE | This block contains text inside it |
| 8 | 0x0080 | F_FRONT | object property : Foreground object |
| 9 | 0x0100 | F_TRIGGER | Unknown |
| 10 | 0x0200 | F_BACK | object property: Background object (e.g. torches) |
| 10 | 0x0200 | F_TINYTHRU | (likely PlayerThru when player is in 'mini' mode, unused in Xargon) |
| 11 | 0x0400 | F_ALWAYS | object property : "Always updates object" |
| 12 | 0x0800 | F_KILLABLE | object property : monster can be killed with regular weapon. |
| 13 | 0x1000 | F_FIREBALL | object property : object is a fireball |
| 14 | 0x2000 | F_WATER | A water tile. regular player will sink, the S.U.B. and aquatic monster can swim through it, but not out of it |
| 14 | 0x4000 | F_NOT_WATER | (Xargon) Not a water tile. |
| 15 | 0x4000 | F_WEAPON | object property : object is a regular weapon |
| 16 | 0x8000 | (unused) | (unused) |
Note that the same "flag set" is used for both blocks and objects. Some properties only apply to blocks, some only apply to objects, some to both (f_msgtouch), and some flags have a different meaning for blocks and tile (e.g. 0x200 and 0x2000).
Object layer
The object layer is drawn in front of the background layer, and contains all the interactive elements of the map, such as points and enemies.
The object data starts straight after the background layer data, so that's at offset 16,384 bytes into the map file (8,192 tiles * two bytes per tile.) The first two bytes in the object layer are a 16-bit integer (UINT16LE) that stores the number of objects in the map, and this is followed by the data for each object, one after the other.
Each object is 31 bytes long, and is stored in the following structure:
| Data type | Description |
|---|---|
| UINT8 iType | Object type (e.g. a "point item", or an enemy.) |
| UINT16 iX | X-coordinate of object |
| UINT16 iY | Y-coordinate of object |
| UINT16 iXD | object horizontal speed |
| UINT16 iYD | object vertical speed |
| UINT16 iWidth | Width of object |
| UINT16 iHeight | Height of object |
| UINT16 iState | Object sub-type (e.g. what type of "point item"), or current "State" (running, jumping, etc) |
| UINT16 iSubState | object-specific semantic |
| UINT16 iStateCount | object-specific semantic, typically a frame counter |
| UINT16 iCounter | Various uses. Often used to link doors or switches to obstacles. |
| UINT16 iFlags | internally used for rendering. |
| UINT32 lPointer | Used internally. This is to keep a spot in memory during the game's execution and serves no other purpose. |
| UINT16 iInfo1 | Unknown |
| UINT16 iZapHold | Unknown |
At the present time it is assumed (perhaps hoped) that objects can be mapped to images in the same way as the tiles in the background layer can be mapped to images, but as yet there is no known way of doing this.
Credits
This file format was reverse engineered by Malvineous. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)
