C4(6)

✨ c4 — Chip's Challenge combined converter ✨

okay so hi bestie, welcome to C4(6). This is the manual page for c4, and by the time we're done you're gonna know level file formats like the back of your hand. 🎀 No cap.

---

🌸 SYNOPSIS 🌸

c4 [-INTYPE] INFILENAME [-OUTTYPE] OUTFILENAME

c4 is your little converter bestie: it translates between the several different types of files used to represent level sets for the game Chip's Challenge. 💅

So here's the vibe: c4 expects there to be two files named on the command-line. It reads the levels stored in the first file, and then writes the levels out to the second file. The format to use with each file usually can be inferred by c4 by examining the filenames — it's giving psychic, honestly. If it can't figure it out, then you may need to use switches before one or both filenames to indicate their type. 🦋

There are four different types of files that c4 understands:

• -D — MS data file (*.dat). This is the file type used by Chip's Challenge for Microsoft Windows 3.x. It's the file type used by most other programs, such as ChipEdit and Tile World. The main character of file formats, lowkey. 👑
• -R — Lynx ROM file (*.lnx, *.lyx) This "file type" is actually just a ROM image of the original Chip's Challenge for the Atari Lynx handheld. It's used by Lynx emulators such as Handy.
• -P — MS-DOS fileset (directory of *.pak files) This is the format used by the MS-DOS port of Chip's Challenge. In this case, the filename given on the command line actually names a directory, containing *.pak files. Yes bestie, a directory counts as a filename here. We love a plot twist. 🙈
• -T — textual source file (*.txt) This file type is native to c4. It's a plain text file, which allows levels to be defined pictorially using a simple text editor. A complete description of the syntax of these files is provided below. 👇

---

💖 EXAMPLES 💖

c4 mylevels.txt mylevels.dat

Create a .dat file from a textual source file. ✨

---

c4 -P levels -D doslevels.dat

levels is a directory of MS-DOS *.pak files. c4 translates the directory contents into a single .dat file. Note that the switches in this example are optional, as c4 would be able to infer the desired formats. (It's just built different. 🫶)

---

c4 mylevels.dat chipsch.lnx

Embed the levels from the .dat file into a Lynx ROM file. Note that c4 does NOT create chipsch.lnx. You must provide the ROM image file, which c4 then alters to contain your levels. (Obviously, you should not use this command on your master copy of the ROM file. Like, please. Protect your faves. 😭)

---

c4 chipsch.lnx -T out

Output the levels in the .dat file as a text file. Here the -T switch is needed to indicate that a text file is the desired output format. 🦋

---

When producing a text file, c4 will attempt to produce legible source, but the results will often not be as good as what a human being would produce. (In particular, c4 cannot draw overlays.) It's doing its best, okay?? 💀

---

🌈 NOTES 🌈

Be aware that there can be various problems when translating a set of levels using the MS ruleset to one of the Lynx-only file formats. There are numerous objects and configurations in the MS ruleset which cannot be represented in the Lynx ruleset. Usually c4 will display a warning when some aspect of the data could not be transferred intact because of this. Pay attention to the warnings bestie, they're there for a reason. 😤

The remainder of this documentation describes the syntax of the textual source file format. 📝

---

🎀 LAYOUT OF THE INPUT FILE 🎀

The source file is broken up into subsections. Each subsection defines a separate level in the set. 🧚

The subsections are separated from each other by a line containing three percent signs:

%%%

A line of three percent signs also comes before the first level and after the last level, at the end of the source file. So it's giving little fences around everything. 🌸

Any other line that begins with a percent sign is treated as a comment, and its contents are ignored. Go off, write whatever you want in there. 💅

Beyond these things, the source file consists of statements. Statements generally appear as a single line of text. Some statements, however, require multiple lines. These multi-line statements are terminated with the word end appearing alone on a line. (Alone. By itself. Main character energy. 👑)

---

✨ INPUT FILE HEADER STATEMENTS ✨

There are a couple of statements that can appear at the very top of the source file, before the first level subsection.

• ruleset [ lynx | ms ] The ruleset statement is the most important of these. It defines the ruleset for the level set. If the ruleset statment is absent, it defaults to lynx.
• maxlevel NNN The maxlevel statement specifies the number of the last level in the .dat file. By default, this value is provided automatically and does not need to be specified. So like, you can just not. 🫶

In addition to the above, a set of tile definitions can appear in the header area. See below for a full description of the tiles multi-line statement. Any tile definitions provided here remain in force throughout the file. Periodt. 💖

---

💅 INPUT FILE LEVEL STATEMENTS 💅

Within each level's subsection, the following two statments will usually appear at the top.

• title STRING
• password PASS

The title statement supplies the level's title, or name. The title string can be surrounded by double quotes, or unadorned — your call bestie. The password statement supplies the level's password. This password must consist of exactly four uppercase alphabetic characters. Four. Uppercase. Letters. No numbers, no lowercase, no vibes-based guessing. 🎀

If the level's number is 150 or less, the password statement may be omitted. In that case the level's password will default to match that level in the original Lynx set. (N.B.: The Lynx ROM file format does not provide a mechanism for setting passwords, so in that case the default password will be used regardless.) 😌

The following statements may also appear in a level subsection.

• chips NNN The chips statement defines how many chips are required on this level to open the chip socket. The default value is zero.
• time NNN The time statement defines how many seconds are on the level's clock. The default value is zero (i.e., no time limit). Live your truth, no clock. ⏰
• hint STRING The hint statement defines the level's hint text. As with the title statement, the string can either be unadorned or delimited with double quotes. If a section contains multiple hint statements, the texts are appended together, e.g.:

hint This is a relatively long hint, and so it
hint is helpful to be able to break it up across
hint several lines.

Note that the same can be done with title statements. ✨

• tiles … end

tiles
DEF1
DEF2
...
end

The tiles multi-line statement introduces one or more tile definitions. The definitions appear one per line, until a line containing end is found. Note that the tile definitions given here only apply to the current level. A complete description of tile definitions is given below. 👇

• map [ X Y ] … and … end or map [ X Y ] … end

map [ X Y ]
LINE1
LINE2
...
and
OVER1
OVER2
...
end

map [ X Y ]
LINE1
LINE2
...
end

The map statement defines the actual contents of (part of) the level's map. The line containing the map statement can optionally include a pair of coordinates; these coordinates indicate where the the section will be located on the level's map. If coordinates are omitted, the defined section will be located at (0 0) — i.e., the upper-left corner of the level. The lines inside the map statement pictorially define the contents of the map section, until a line containing and or end is encountered. When the map is terminated by and, then the lines defining the map section are immediately followed by lines defining an overlay. The overlay uses the same origin as the map section (though it is permissible for the overlay to be smaller than the map section it is paired with). A complete description of the map and overlay sections is given below. 🗺️

• border TL The border statement specifies a tile. The edges of the map are then changed to contain this tile. Typically this is used to enclose the level in walls. Cozy. 🧱

The following statements are also available, though they are usually not needed. They provide means for explicitly defining level data, for the occasional situation where the usual methods are more cumbersome. (iykyk 💅)

• creatures X1 Y1 ; X2 Y2 ... The creatures statements permits explicit naming of the coordinates in the creature list. Pairs of coordinates are separated from each other by semicolons; any number of coordinate pairs can be specified. There can be multiple creatures statements in a level's subsection.
• traps P1 Q1 -> R1 S1 ; P2 Q2 -> R2 S2 ... The traps statement permits explicit naming of the coordinates for elements in the bear trap list. Coordinates are given in one or more groups of four, separated by semicolons. Each group consists of the x- and y-coordinates of the brown button, an arrow (->), and then the x- and y-coordinates of the bear trap. Any number of traps statements can appear in a level's subsection.
• cloners P1 Q1 -> R1 S1 ; P2 Q2 -> R2 S2 ... The cloners statement permits explicit naming of elements in the clone machine list. It uses the same syntax as the traps statment, with the red button's coordinates preceding the coordinates of the clone machine. 🫶
• level NNN The level statement defines the level's number. By default it is one more than the number of the prior level.
• field NN B01 B02 ... The field statement allows fields to be directly specified and embedded in the .dat file. The first argument specifies the field number; the remaining arguments provide the byte values for the actual field data. These statements are only meaningful in conjunction with producing a .dat file.

🎀 DEFINING TILES 🎀

okay bestie, a tile definition is literally two parts, no more. part one is either one or two characters — letters, numbers, punctuation, anything you want except spaces (spaces are banned, do not try it). part two is the name of a tile, or a pair of tiles. and boom 💥 those characters become that tile's representation.

here's what some tile definitions look like:

tiles
#       wall
*       teleport
rb      red button
@       chip south
end

(quick note, there's a single tab character sitting after the characters and before the tile names — don't forget it, the parser is picky.) once you've handed over these definitions, those shiny new characters are free to be used in a map. slay ✨

all of the definitions above use singular tiles. wanna define a pair of tiles? just glue the two names together with a plus sign, like this:

tiles
X       block + bomb
G       glider north + clone machine
end

and notice, the top tile gets named first, then the bottom tile. top then bottom, always, no cap 🫶

The tiles statement is the only statement that can appear in the header, as well as in a level's subsection. tile definitions in the header are global and work in every subsection. tile definitions inside a subsection are local and apply only to that one level. local girl, global girl, both valid 💅

a bunch of tile definitions come pre-set ahead of time, giving you standard representations for some of the most common tiles. (if you don't vibe with those representations, no worries, you can always redefine the characters.) here's some of the built-in definitions:

#       wall                  $       computer chip
,       water                 H       socket
=       ice                   E       exit
&       fire                  []      block
6       bomb                  ?       hint button

see below for the complete list of tile names and built-in definitions 👑

a few groups of tiles let you specify multiple definitions on a single line. for example:

tiles
G       glider
end

this one definition is equivalent to the following:

tiles
Gn      glider north
Gs      glider south
Ge      glider east
Gw      glider west
end

(note that G by itself is still undefined — it's giving ✨mystery✨.) all creatures, including Chip, can be defined using this abbreviated form.

doors and keys are the other groups with this feature, so this definition:

tiles
D       door
end

is equivalent to:

tiles
Dr      red door
Db      blue door
Dy      yellow door
Dg      green door
end

---

🗺️ MAP SECTIONS 🗺️

once all the needed tiles have representations, using the map statement is honestly a simple matter. here's an example:

map
# # # # # #
# &     & # # #
    []    H E #
# &     $ # # #
# # # # # #
end

this is a map of a small room. a block stands in the way of the entrance. three of the four corners contain fire, and the fourth contains a chip. on the east wall there's an exit guarded by a chip socket. cute little room, lowkey iconic 🏠🔥

note that each cell in the map is two characters wide. (so for example, those octothorpes are describing a solid wall all the way around the room.)

here's a bigger one, presenting the map from LESSON 2:

tiles
B       bug north
C       chip south
end

map 7 7
    # # # # # # #
    #     $     #
    #           #
    #     #     # # # # # # # # # #
# # #     # B     , ,           $ #
# E H     # # B   , ,   [][]C ?   #
# # #     # B     , ,           $ #
    #     #     # # # # # # # # # #
    #           #
    #     $     #
    # # # # # # #
end

there are a couple of different ways to fill a cell with two tiles. the first way is to just use tile definitions that contain two tiles:

tiles
X       block + bomb
G       glider east + clone machine
end

map 12 14
        # #
      6 E #
        # # X
G
end

the second way is to squeeze two representations into a single cell. obviously this only works when both representations are a single character:

tiles
[       block
G       glider east
+       clone machine
end

map 12 14
        # #
      6 E #
        # # [6
G+
end

in both cases, the top tile always comes before the bottom tile. and you can "bury" a tile by placing it to the right of a space:

map
# # # # # #
   6 6 6E #
# # # # # #
end

any number of map statements can appear in a level's subsection, and all those map statements get combined together to make the complete map 🧩

---

✨ OVERLAY SECTIONS ✨

every map statement can optionally include an overlay section. this overlay is what lets you define button connections and monster ordering.

the overlay is applied to the same position as the map section it accompanies. it's allowed to duplicate parts of the map section it covers, and any such duplication just gets ignored. the only characters in the overlay that matter are the ones that differ from the map section it covers. those characters are treated as labels. labels are always a single character, and two non-space characters in a cell always means two separate labels. any non-space characters can be used as labels, as long as they don't match up with the map. 🏷️

an overlay section defines a button connection by using the same label in two (or more) cells. one of the labelled cells will contain either a bear trap or a clone machine, and the other will contain the appropriate button. if there are more than two cells with the same label, all but one should contain a button.

characters that only appear once in an overlay, on the other hand, indicate creatures. the characters then indicate the ordering of the creatures in the creature list with respect to each other. the ordering of characters is the usual ASCII sequence (e.g., numbers first, then capital letters, then lowercase letters).

for example, here's a map with an overlay demonstrating all three of these uses:

tiles
G       glider east
+       clone machine
r       red button
*       beartrap
b       brown button
end

map
G                           v #
G+      *   r   * G+    b &   # r
G+    *     r     #           # r
# >   b b G             < #   #
and
2                           v #
A       c   C   d C     d &   # A
B     a     C     #           # B
# >   a c 1             < #   #
end

in this example, capitals are used for the clone machine connections, lowercase for the bear trap connections, and numbers are used for the creature ordering. chef's kiss, genuinely 💋

(note that the gliders atop clone machines are not numbered. while it's not an error to include clone machine creatures in the ordering, they are ignored under the MS ruleset.)

it is not necessary to reproduce any of the map section's text in the overlay section — blanks can be used instead. the ignoring of matching text is simply a feature designed to assist the user in keeping the overlay's contents properly aligned. bestie alignment tool fr fr 🫶

the traps, cloners, and creatures statements can be used in lieu of, or in conjunction with, data from overlay sections. in the case of the creature list, items are added to the list in the order that they are encountered in the source text.

if a level contains no overlay information and none of the above three statements, then this information will be filled in automatically. the data will be determined by following the original Lynx-based rules — viz., buttons are connected to the next beartrap/clone machine in reading order, wrapping around to the top if necessary. (likewise, the creature ordering is just the order of the creatures in their initial placement, modified by swapping the first creature with Chip.)

so if you actually want to force an empty bear trap list, clone machine list, or creature list, you must include an empty traps, cloners, and/or creatures statement. no skipping this one, the auto-fill will absolutely come for you otherwise 😭

🌸 TILE NAMES 🌸

okay bestie this is the full list of every tile name you can use in definitions, exactly as they're spelled. if two names are sitting on the same line, that means they're just two different names for the same tile — pick whichever vibes with you 💖

and heads up: tile names are NOT case-sensitive. capitalization is fully ignored, so go off, type it however.

empty
wall
water
fire
dirt
ice
gravel
computer chip          ic chip
socket
exit
ice corner southeast   ice se
ice corner southwest   ice sw
ice corner northwest   ice nw
ice corner northeast   ice ne
force floor north      force north
force floor south      force south
force floor east       force east
force floor west       force west
force floor random     force random              force any
hidden wall permanent  invisible wall permanent
hidden wall temporary  invisible wall temporary
wall north             partition north
wall south             partition south
wall east              partition east
wall west              partition west
wall southeast         partition southeast       wall se
closed toggle wall     closed toggle door        toggle closed
open toggle wall       open toggle door          toggle open
blue door              door blue
red door               door red
green door             door green
yellow door            door yellow
blue key               key blue
red key                key red
green key              key green
yellow key             key yellow
blue button            button blue               tank button
red button             button red                clone button
green button           button green              toggle button
brown button           button brown              trap button
blue block floor       blue wall fake
blue block wall        blue wall real
thief
teleport
bomb
beartrap               trap
popup wall
hint button
clone machine          cloner
water boots            water shield              flippers
fire boots             fire shield
ice boots              spiked shoes              skates
force boots            magnet                    suction boots
block                  moveable block
cloning block north    block north
cloning block south    block south
cloning block east     block east
cloning block west     block west
chip north
chip south
chip east
chip west
ball north
tank north
bug north              bee north
paramecium north       centipede north
fireball north         flame north
glider north           ghost north
blob north
walker north           dumbbell north
teeth north            frog north

(okay so those last nine lines — the creatures — only show the north-facing versions. the other 27 names, for the south-, east-, and west-facing versions, follow the obvious patttern. yes, three t's. we don't make the rules 💅)

THE BEST PART: tile names can be abbreviated to any unique prefix. so you can literally write stuff like glider north as just glider n. iconic. efficient. ate. ✨

---

there are also tile names for the "extra" MS tiles, and those get listed in parentheses — which is the lil indicator that they were not originally meant to be used in maps. so like, proceed with caution bestie 🫶

(combination)
(chip drowned)
(chip burned)
(chip bombed)
(unused 1)
(unused 2)
(unused 3)
(exiting)
(exit 1)
(exit 2)
(chip swimming north)  (chip swimming n)
(chip swimming west)   (chip swimming w)
(chip swimming south)  (chip swimming s)
(chip swimming east)   (chip swimming e)

and finally — you can also refer to tiles explicitly by their hexadecimal byte value under the MS rules, using the 0x prefix. so 0x2A and bomb are literally the same thing. no cap. 🎀

---

✨ PREDEFINED TILE DEFINITIONS ✨

here's the complete list of built-in tile definitions, ready to go, zero setup required:

    #       wall                  E       exit
    $       ic chip               H       socket
    ,       water                 =       ice
    &       fire                  6       bomb
    ;       dirt                  :       gravel
    ~       wall north            ^       force floor north
    _       wall south            v       force floor south
    |       wall west             <       force floor west
     |      wall east             >       force floor east
    _|      wall southeast        <>      force floor random
    ?       hint button           @       chip south
    []      block                 [       block
    ^]      cloning block north + clone machine
    <]      cloning block west + clone machine
    v]      cloning block south + clone machine
    >]      cloning block east + clone machine

---

💜 LICENSE 💜

okay so here's the legal bit — gotta include it, it's the whole point of the thing. c4, Copyright (C) 2003-2006 Brian Raiter <breadbox@muppetlabs.com>. and then the actual license text, verbatim, because that's how licenses work bestie:

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and documentation (the "Software"), to deal in the
Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tl;dr: no warranty, be nice, keep the notice. 💀

---

and that's the whole page, bestie!! 🌈 this one's from Tile World, version/date 2025-02-16, filed under C4(6). go forth and build the silliest little levels ever, you absolute main character. mwah. 💅💖🎀🦋