DAT

Revision as of 23:49, 23 January 2022 by 184.162.166.228 (talk) (→‎5: Cloner linkage: Supposedly starts at $02 since all others do?)

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.

$0_ $1_ $2_ $3_ $4_ $5_ $6_
$_0   Floor   Clone block (S) [1] unused [2]   Thin wall (SE)   Bug (N)   Glider (N)   Paramecium (N)
$_1   Wall   Clone block (E) [1]   Thief   Cloner   Bug (W)   Glider (W)   Paramecium (W)
$_2   Computer chip   Force floor (N)   Chip socket   Random force floor   Bug (S)   Glider (S)   Paramecium (S)
$_3   Water   Force floor (E)   Green button   Drowned Chip [3]   Bug (E)   Glider (E)   Paramecium (E)
$_4   Fire   Force floor (W)   Red button   Burned Chip [3]   Fireball (N)   Teeth (N)   Blue key
$_5   Invisible wall   Exit   Toggle wall   Burned Chip [3]   Fireball (W)   Teeth (W)   Red key
$_6   Thin wall (N)   Blue lock   Toggle floor unused [4]   Fireball (S)   Teeth (S)   Green key
$_7   Thin wall (W)   Red lock   Brown button unused [4]   Fireball (E)   Teeth (E)   Yellow key
$_8   Thin wall (S)   Green lock   Blue button unused [4] [5]   Ball (N)   Walker (N)   Flippers
$_9   Thin wall (E)   Yellow lock   Teleporter   Fake exit [3]   Ball (W)   Walker (W)   Fire boots
$_a   Dirt block   Ice corner (NW)   Bomb   Fake exit [3]   Ball (S)   Walker (S)   Ice skates
$_b   Dirt   Ice corner (NE)   Trap   Fake exit [3]   Ball (E)   Walker (E)   Suction boots
$_c   Ice   Ice corner (SE)   Hidden wall   Swimming Chip (N) [3]   Tank (N)   Blob (N)   Chip (N)
$_d   Force floor (S)   Ice corner (SW)   Gravel   Swimming Chip (W) [3]   Tank (W)   Blob (W)   Chip (W)
$_e   Clone block (N) [1]   Fake blue wall   Recessed wall   Swimming Chip (S) [3]   Tank (S)   Blob (S)   Chip (S)
$_f   Clone block (W) [1]   Real blue wall   Hint   Swimming Chip (E) [3]   Tank (E)   Blob (E)   Chip (E)
  1. 1.0 1.1 1.2 1.3 Must be used when creating a block cloner, to indicate the direction of cloning. A clone block placed on its own won't be pushable.
  2. Used internally as the Combination tile.
  3. 3.0 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 This tile is an implementation detail, not an intended game element.
  4. 4.0 4.1 4.2 This byte does not correspond to any defined tile, but acts like an invisible wall.
  5. In the pgchip hack, this byte is used to indicate an ice block.

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
$02 2 x-coordinate of brown button
$04 2 y-coordinate of brown button
$06 2 x-coordinate of trap
$08 2 y-coordinate of trap
$0a 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
$02 2 x-coordinate of red button
$04 2 y-coordinate of red button
$06 2 x-coordinate of cloner
$08 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 127 moving monsters in a level.

Offset Bytes Content
$00 1 x-coordinate of monster
$02 1 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