NAME¶
c4 - Chip's Challenge combined converter
SYNOPSIS¶
c4 [-INTYPE] INFILENAME [-OUTTYPE] OUTFILENAME
c4 allows one to translate between the several different types of files used to
represent level sets for the game Chip's Challenge.
c4 expects there to be two files named on the command-line. c4 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. If not, then it may be necessary 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 is
the file type used by most other programs, such as ChipEdit and Tile World.
-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 is 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.
-T textual source file (*.txt)
This file type is native to c4. It is 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.
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.)
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.)
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.
The remainder of this documentation describes the syntax of the textual source
file format.
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.
Any other line that begins with a percent sign is treated as a comment, and its
contents are ignored.
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.
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.
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.
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. The
password
statement supplies the level's password. This password must consist of exactly
four uppercase alphabetic characters.
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).
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
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 ] map [ X Y ]
LINE1 LINE1
LINE2 LINE2
... ...
and end
OVER1
OVER2
...
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.
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.
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¶
A tile definition consists of two parts. The first part is either one or two
characters. The characters can be letters, numbers, punctuation -- anything
except spaces. The second part is the name of a tile or a pair of tiles. The
characters then become that tile's representation.
Here is an example of some tile definitions:
tiles
# wall
* teleport
rb red button
@ chip south
end
(Note that a single tab character comes after the characters and before the tile
names.) Once these definitions have been provided, the newly-defined
characters can then be used in a map.
The above definitions all use singular tiles. To define a pair of tiles, combine
the two names with a plus sign, like so:
tiles
X block + bomb
G glider north + clone machine
end
Notice that the top tile is named first, then the bottom tile.
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 can be used in every subsection. Tile definitions inside a subsection are
local, and apply only to that level.
A number of tile definitions are pre-set ahead of time, supplying standard
representations for some of the most common tiles. (If these representations
are not desired, the characters can always be redefined.) Here are 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 tiles allow one to specify multiple definitions in 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.) All creatures, including
Chip, can be defined using this abbreviated form.
Doors and keys are the other groups that have this feature; the following
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 defined representations, using the map statement
is a simple matter. Here is 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; the fourth contains a chip. On the east wall
is an exit guarded by a chip socket.
Note that each cell in the map is two characters wide. (Thus, for example, the
octothorpes describe a solid wall around the room.)
Here is a larger example, which presents 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 simply use tile definitions which contains 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 can only be done with 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. Note that 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. The map
statements will be combined together to make the complete map.
OVERLAY SECTIONS¶
Every map statement can optionally include an overlay section. This overlay
permits button connections and monster ordering to be defined.
The overlay is applied to the same position as the map section it accompanies.
The overlay can duplicate parts of the map section it covers, and any such
duplication will be ignored. The only characters in the overlay that are
significant are the ones that differ from the map section it covers. These
characters are treated as labels. Labels are always a single character; two
non-space characters in a cell always indicates 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 is a map with an overlay that demonstrates 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.
(Note that the gliders atop clone machines are not numbered. While it is 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.
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.) Thus, 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.
TILE NAMES¶
Here is the complete list of tiles as they are named in definitions. Two or more
names appearing on the same line indicates that they are two different names
for the same tile. Note that the tile names are not case-sensitive;
capitalization is ignored.
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
(The last nine lines, listing the creatures, only show the north-facing
versions. The remaining 27 names, for the south-, east-, and west-facing
versions, follow the obvious patttern.)
Note that tile names may be abbreviated to any unique prefix. In particular,
this permits one to write names like "glider north" as simply
"glider n".
There are also tile names for the "extra" MS tiles. These tiles are
listed in parentheses, as an indicator that they were not originally intended
to be used in maps.
(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)
Finally, note that one can also explicitly refer to tiles by their hexadecimal
byte value under the MS rules by using the "0x" prefix. Thus, the
names "0x2A" and "bomb" are equivalent.
PREDEFINED TILE DEFINITIONS¶
The following is the complete list of built-in tile definitions:
# 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¶
c4, Copyright (C) 2003-2006 Brian Raiter <breadbox@muppetlabs.com>
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.