Provided by: tworld-data_1.3.0-5_all bug

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.

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.

       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.

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.

       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.

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. 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.