CHUNKED

Background Chunk Editor For Side Scroller

We have been working on an Ncurses based side side scroller and it will require at least a couple of asset editing tools. This article is about one of them. Namely, Chunked! It is essentially a drawing tool for creating fixed sized character based images. It is written in C++ and doesn't use any libraries apart from the standard library and Ncurses.

Chunked deals with four types of files. These fall into two classes of files, namely composite files and (for lack of a better term) standard files.
These so called standard files have the extensions .bgchunk and .crchunk.
The composite files have the extensions .levbg and .levcr and are composed of the concatenated contents of .bgchunk files and .crchunk files respectively.
Chunked can be used to create a series of .bgchunk and .crchunk files (.bgchunk and .crchunk files are created / edited simultaneously.)
Once these files are created they can be compiled together into .levbg files and .levcr files.
.levbg files and .levcr will be referenceable from config files that the side scroller can read.

.bgchunk files are essentially image files where the picture elements are a subset of extended ASCII characters with added colour information. They use a simple run-length encoding compression scheme. There is an eight byte header that is interpreted as a chunk coordinate this consists of two signed 32 bit numbers, y and x. After this is the image. Each run of pixels of equal value that is more than bgCompressionAdvantagePoint (3) is encoded using a run-length encoding. The pixels are represented by integers of type backgroundChunkCharType (unsigned short). This allows for all the combinations of characters and colours we need to represent all possible pixel values with some small space left over that we can use for a special constant (bgRunLengthSequenceSignifier) that will represent the start of a run length sequence (which consists of this special character, a length and a pixel.) Each pixel is encoded as an extended ASCII number minus lowerUnusedASCIIChNum (which is 32 -1) times a color pair number. The images are always of the same dimensions (48x178) so each run of 178 pixels (starting from the origin ((0, 0) top left)) represents a horizontal line of pixels.
.crchunk files are similar except a small subset of ASCII characters are used for the pixels and there is no color information.

.levbg files are used for level backgrounds. Level backgrounds consist of a series of images (chunks) that have coordinates. .levcr files are used for level boundaries and surfaces that the player can interact with. Currently there are only two types of boundaries / surfaces (AKA character rules). These are borders (represented by border characters 'b's) and platforms (represented by platform characters 'p's.) The player cannot move through border characters and can only move up through platform characters. There should be a rules chunk for each background chunk (even if the rules chunk contains no character rules. In which case it will contain only spaces (which have no effect on the player.)) Chunked offers a number of modes. Basic info about the supported modes can be seen by starting Chunked with the -h switch. If you do this you will be presented with the following:

================================================================================
./chunked Help:
        ./chunked has seven modes. They are as follows.

    1st mode:
        The first mode is known as Single Chunk Edit Mode. If the files have the
        extensions ".bgchunk" and ".crchunk" respectively and the paths are
        valid. The program will enter Chunk Edit Mode. In this mode the
        background chunk file and the rules chunk file can be edited and saved.
        The files can be pre-existing files or they can be new files. If the
        files are pre-existing their pre-existing contents will be editable. If
        the files are new the user will be asked to supply a chunk coordinate
        for the files (If just one of the files is new the chunk coordinate will
        be read from the pre-existing file.) The coordinate of the chunks can
        also be changed in this mode.
            Example:
                ./chunked superGood.bgchunk superGood.crchunk

    2nd mode:
        The second mode is an alternative form of Single Chunk Edit mode.
        Instead of supplying the names of one ".bgchunk" file and one ".crchunk"
        file the names of two ".bgchunk" and two ".crchunk" files must be
        supplied. This second set of files will be viewable as a reference in
        the editor when editing the first set of file. Where the second set are
        the files that appear after a file with the same extension in the
        command.
            Example:
                ./chunked superGood.bgchunk superGoodReference.bgchunk superGood.crchunk superGoodReference.crchunk

    3rd mode:
        The third mode is known as Append Mode. In this mode the contents of a
        ".bgchunk" file will be appended to a ".levbg" file.
        Or alternatively the contents of a ".crchunk" file willbe appended to a
        ".levcr" file.
        Which action is performed depends of the file extensions of the
        arguments. If the file extensions of the arguments are ".bgchunk" and
        ".levbg" respectively then the first action will be performed.
        However if the file extensions of the arguments are ".crchunk" and
        ".levcr" respectively then the second action will be performed.
            Example:
                ./chunked superGood.bgchunk splendid.levbg

    4th mode:
        This mode is known as Extraction Mode. In this mode a chunk is removed
        from a .levbg file or a .levcr file and placed in a
        .bgchunk file or a .crchunk file. A .levbg file must be
        specified as the first argument. This should be followed by a .bgchunk
        file and finally by the desired y and x coordinate of the chunk to be
        extracted.
        Or alternatively a .levcr file must be specified as the first
        argument. This should be followed by a .crchunk file and finally by the
        desired y and x coordinate of the chunk to be extracted.
            Example:
                ./chunked splendid.levbg superGood.bgchunk 11 -3

    5th mode:
        This mode is known as Delete Mode. Chunks can be removed from ".levbg"
        and ".levcr" files. A valid chunk coordinate for a chunk to be removed
        should be supplied.
            Example:
                ./chunked splendid.levbg 11 -3

    6th mode:
        This mode is known as Map View Mode. In this mode a .levbg
        file or a .levcr file can be viewed in a zoomed out mammer,
        with one character corresponding to 1 chunk. If the layout is not
        viewable in this way within the view port. The user may use the arrow
        keys to move around. To enter this mode the user must supply a file as
        the soul argument. The file must either be a .levbg file. Or a
        .levcr file.
            Example:
                ./chunked splendid.levbg

    7th mode:
        This mode is known as Help Mode and does what it says on the tin.
                Example:
                ./chunked -h
                                           
       

Single Chunk Edit Mode and Map View Mode have help menus that can be accessed by pressing h. Each of these modes also have what we will call sub-modes. These modes have their own help menus.