DAT

Revision as of 12:00, 2 May 2021 by G-lander (talk | contribs) (→‎Tile encoding: Fixed typo of the thief type)

In the context of Chip's Challenge, DAT or .dat is the file format which Chip's Challenge 1 level sets are commonly stored in, named for the CHIPS.DAT file containing the levels for MSCC. The .dat extension is short for "data" and commonly used on data files with ad-hoc formats; it is not specific to Chip's Challenge.

Since the release of CCTools, the format is sometimes referred to as CCL or .ccl, short for "Chip's Challenge levels". For people who have ChipEdit, which does not provide a way to open CCL files "normally", simply change the extension back to .dat, or type the file name manually when in the Open dialog.

Structure

The format is a relatively simple binary structure. All fields are little-endian.

File header =

Offset Bytes Content
$00 4 Magic number, identifying the file format. MSCC will reject the file if this is not $0002AAAC. Tile World will also accept $0102AAAC as meaning a level set using Lynx rules. The pgchip modification expects $0003aaac.
$04 2 Number of levels in the file.

Levels begin at offset $06, immediately following the header.

Level structure

Offset Bytes Content
$00 2 Length of this level in bytes, not including this field.
$02 2 Level number.
$04 2 Time limit, in seconds. Zero indicates the level is untimed. Every official version of the game has a three-digit timer, so values over 999 are uncommon.
$06 2 Required number of chips. This may be less than the number of chips in the level, in which case the extras will be optional, or it may be more, in which case the chip socket will be impossible to open.
$08 2 Unclear. Must always be 0 or 1. The original levels all have this set to 1. Possibly once indicated whether the level data was compressed or not.
$0a 2 Length of top layer, in bytes.
$0c varies Contents of top layer; see below.
varies 2 Length of bottom layer, in bytes.
varies varies Contents of bottom layer; see below.
varies 2 Total length of all metadata chunks, in bytes; see below. MSCC crashes if there are more than 1152 bytes of metadata.
varies varies Zero or more metadata chunks; see below.

Level contents

The level is encoded as two layers, top and bottom. Every CC1 level is 32×32, so each layer contains exactly 1024 tiles. If a cell only contains one tile, it should be placed on the top layer, and the corresponding tile in the bottom layer should simply be floor. (Another way to think of this is that the floor byte, $00, represents nothing, but that every cell implicitly has floor underneath.)

Any tile may appear on either layer, which allows for a vast number of strange combinations. However, within the original rules of the game, the only valid combinations are a lone static tile, or a static tile with a movable object on top. Anything else (including some otherwise intuitive possibilities that would work in Chip's Challenge 2, like a key on gravel) is an invalid tile, will be rejected by Tile World's Lynx mode, and may behave unexpectedly.

A layer is a simple stream of bytes representing the tiles in reading order. A lone byte indicates a particular tile according to the encoding below. A $FF byte indicates simple run-length encoding, where the next two bytes are the number of copies and the byte to repeat. The sequence `00 FF 0A 01 00` thus describes twelve tiles: a floor tile, a span of ten walls, and another floor tile.

Tile encoding

The tile encoding exactly matches the arrangement of sprites in the MSCC tileset.

Values of $70 and above are used internally for graphical transparency.

Byte Tile Byte Tile Byte Tile Byte Tile Byte Tile Byte Tile Byte Tile
$00   Floor $10   Clone block (S) $20 unused
(used internally as Combination)
$30   Thin wall (SE) $40   Bug (N) $50   Glider (N) $60   Paramecium (N)
$01   Wall $11   Clone block (E) $21   Thief $31   Cloner $41   Bug (W) $51   Glider (W) $61   Paramecium (W)
$02   Computer chip $12   Force floor (N) $22   Chip socket $32   Random force floor $42   Bug (S) $52   Glider (S) $62   Paramecium (S)
$03   Water $13   Force floor (E) $23   Green button $33   Drowned Chip $43   Bug (E) $53   Glider (E) $63   Paramecium (E)
$04   Fire $14   Force floor (W) $24   Red button $34   Burned Chip $44   Fireball (N) $54   Teeth (N) $64   Blue key
$05   Invisible wall $15   Exit $25   Toggle wall $35   Burned Chip $45   Fireball (W) $55   Teeth (W) $65   Red key
$06   Thin wall (N) $16   Blue lock $26   Toggle floor $36 unused
(acts as invisible wall)
$46   Fireball (S) $56   Teeth (S) $66   Green key
$07   Thin wall (W) $17   Red lock $27   Brown button $37 unused
(acts as invisible wall)
$47   Fireball (E) $57   Teeth (E) $67   Yellow key
$08   Thin wall (S) $18   Green lock $28   Blue button $38 unused
(acts as invisible wall)
(Ice block in pgchip)
$48   Ball (N) $58   Walker (N) $68   Flippers
$09   Thin wall (E) $19   Yellow lock $29   Teleporter $39   Fake exit $49   Ball (W) $59   Walker (W) $69   Fire boots
$0a   Dirt block $1a   Ice corner (NW) $2a   Bomb $3a   Fake exit $4a   Ball (S) $5a   Walker (S) $6a   Ice skates
$0b   Dirt $1b   Ice corner (NE) $2b   Trap $3b   Fake exit $4b   Ball (E) $5b   Walker (E) $6b   Suction boots
$0c   Ice $1c   Ice corner (SE) $2c   Hidden wall $3c   Swimming Chip (N) $4c   Tank (N) $5c   Blob (N) $6c   Chip (N)
$0d   Force floor (S) $1d   Ice corner (SW) $2d   Gravel $3d   Swimming Chip (W) $4d   Tank (W) $5d   Blob (W) $6d   Chip (W)
$0e   Clone block (N) $1e   Fake blue wall $2e   Recessed wall $3e   Swimming Chip (S) $4e   Tank (S) $5e   Blob (S) $6e   Chip (S)
$0f   Clone block (W) $1f   Real blue wall $2f   Hint $3f   Swimming Chip (E) $4f   Tank (E) $5f   Blob (E) $6f   Chip (E)

Level metadata chunks

Each chunk begins with a small header.

Because the length of a chunk is stored in a single byte, no chunk may be longer than 255 bytes.

Offset Bytes Content
$00 1 Chunk type
$01 1 Chunk length in bytes, not including this two-byte header

A level must have a title (3) and password (6). A level intended to work under MS rules should also have trap linkage (4), cloner linkage (5), and a monster list (10), or those elements will not work.

Unrecognized chunk types are ignored.

1: Time limit

Offset Bytes Content
$02 2 Time limit in seconds

This chunk is never used in the original game, since it's redundant with the time limit field in the level header.

2: Required chips

Offset Bytes Content
$02 2 Required number of chips

This chunk is never used in the original game, since it's redundant with the required chips field in the level header.

3: Title

Offset Bytes Content
$02 ? Map title. Must include a trailing NUL byte, and must not exceed 64 characters (including the NUL). Should generally be ASCII, though Tile World appears to interpret this as Latin-1.

4: Trap linkage

Contains zero or more of the following structure. As this structure is 10 bytes in size, the chunk size should be a multiple of 10, and there cannot be more than 25 trap linkages in a level. Any given brown button may only be linked to a single trap.

Offset Bytes Content
$00 2 x-coordinate of brown button
$02 2 y-coordinate of brown button
$04 2 x-coordinate of trap
$06 2 y-coordinate of trap
$08 2 Always zero. Presumably a placeholder for runtime state regarding whether the trap is open or closed.

This structure links brown buttons to traps in MSCC, where such linkage must be explicit. If a brown button is not listed in this chunk, it will not function in MSCC.

Tile World in Lynx mode will ignore this structure and always connect brown buttons in reading order.

If this chunk appears more than once, MSCC will only read the first, but Tile World will merge them all.

5: Cloner linkage

Contains zero or more of the following structure. As this structure is 8 bytes in size, the chunk size should be a multiple of 8, and there cannot be more than 31 cloner linkages in a level.

Offset Bytes Content
$00 2 x-coordinate of red button
$02 2 y-coordinate of red button
$04 2 x-coordinate of cloner
$06 2 y-coordinate of cloner

This structure links red buttons to cloners in MSCC, where such linkage must be explicit. If a red button is not listed in this chunk, it will not function in MSCC. Any given red button may only be linked to a single cloner.

Tile World in Lynx mode will ignore this structure and always connect red buttons in reading order.

If this chunk appears more than once, MSCC will only read the first, but Tile World will merge them all.

6: Password

Offset Bytes Content
$02 ? Encrypted password. Must include a trailing NUL. Should be ASCII. May be up to 10 characters, but generally should be 5 (4 + NUL).

The password is encrypted trivially, by XORing every character (not including the trailing NUL) with 0x99.

7: Hint

Offset Bytes Content
$02 ? Hint text. Must include a trailing NUL byte, and must not exceed 128 characters (including the NUL). Should generally be ASCII, though Tile World appears to interpret this as Latin-1.

8: Unencrypted password

This chunk is identical to chunk 6, but without the encryption. It is never used in the original CHIPS.DAT, and Tile World ignores it.

10: Monster list

Contains zero or more of the following structure. As this structure is 2 bytes in size, the chunk size should be a multiple of 2, and there cannot be more than 128 moving monsters in a level.

Offset Bytes Content
$00 2 x-coordinate of monster
$02 2 y-coordinate of monster

This structure allows monsters to move in MSCC; if a monster is not listed in this chunk, it will not move.

Tile World in Lynx mode will ignore this structure and always allow any number of monsters to move as normal.

See also

External Links

Explanation of the CHIPS.DAT format