Damaniel's Pixel By Number
==========================

This is a paint by number game. Think something like the mobile game Cross
Stitch World, or something like actual diamond painting.

While I'm not ready to call the game 'complete', I believe that all of the
planned functionality is in.

See the PDF manual for more details about the interface, controls and other
features of the game.

Requirements
------------

   A 386 or higher (it runs in protected mode)
   Some amount of RAM. 4MB is probably enough in all cases. Smaller images will
     work with 2.
   A VGA card. It uses Mode 13 (320x200, 256 colors), supported by all VGAs.
   A copy of CWSDPMI.EXE, either in the program directory or on your PATH.

Additional tools
----------------

There are some tools in the 'tools' directory. You can build the C programs them
by running make tools from the root of the main directory. These tools are:

   convert: The tool that creates picture files from PCX files. Run convert.exe
            for usage instructions
   expand: takes a PCX saved in 16 color mode and converts it to a 256 color
           version. This is important since it allows the creation of picture
           files with fewer than 16 colors while maintaining compatibility with
           Allegro.
   installer: creates an installer for the game, meant for copying files from a
              floppy disk to (presumably) a hard drive

The python tools are some batch converters that I'm using to make larger
collections. They are:

   batch_convert.py: takes a directory of image files and creates a set of
                     DamPBN picture files in a separate output directory.
                     Supported image file formats are JPG, PNG and PCX.
                     This converter will also adjust the image size and color
                     palette if needed, so any images can be used without
                     preprocessing.
   image_process.py: takes 2 directories of identical files - one with original
                     names, one with numbered names, and makes a metadata file
                     for batch_convert.py
   image_split.py: takes a pile of images and divides them into groups of 50,
                   putting each group into sequentially numbered directories

An additional python tool is present:

   generate_manifest.py: creates a manifest for the installer. Scans a
                         directory tree and generates a file that tells
                         the installer what directories to make and what files
                         to copy

Build requirements
------------------

This program can be built in one of two ways:

   A modern version of DJGPP and Allegro (9.3.0 and 4.2.2 respectively).
   My 'old' toolchain (gcc 2.95.2 and Allegro 3.12)

The modern version is the default. Running make will generate this version of
the program. If you want to build the old version, running
'make -f Makefile.295' will do that instead.

Also note that the 2.9.x toolchain isn't widely available - I have a bespoke
setup on my PC for it. The main reason to use it is compile speed - it builds
much faster on older hardware and generates smaller executables. The newer
version also loads a fair bit slower on older hardware, though seems to run more
or less at the same speed. For playing around on DOSBox, the default build is
fine - the 'old' build will probably just be offered as binary packages for now.

Note that the upx call in make prod in the modern DJGPP build will fail on
DOSbox due to the compiler setting the executable read-only. For now, until I
figure out what to do about it, just run upx on it manually if desired.

Deployment
----------

The steps required to deploy a copy of the game is:

   Build the code
   Build the tools
   (If needed) Build the installer
   Copy the required distribution files to a target directory and compress
      them as needed
   Run the manifest generator in the target directory
   Take the resulting directory and use a tool like WinImage to make a floppy
      image file from it

One issue is that the first 4 steps need to be done from a DOS environment,
while the last 2 need to be done in an environment with a copy of Python and a
copy of WinImage (or some other tool that can generate floppy images from a
directory tree). As a result, my current workflow is to:

   Run 'make' or 'make -f Makefile.295 prod' from the DamPBN directory
   Run 'make tools' from the DamPBN\tools directory
   Run 'build' from the DamPBN\tools\install directory
   Copy the relevant files (binaries, cwsdpmi.exe, resources, pic files) to a
      DIST directory
   Run UPX on all the binaries that need it (dampbn.exe, install.exe,
      covert.exe, expand.exe) in DIST
   Run the manifest generator from DIST
   Use WinImage to make a disk from the contents of DIST

Not very convenient (and it certainly could be more automatable with some work),
but I make releases so infrequently that I don't mind doing a couple manual
steps once or twice a year.

What's done
-----------

   Logo screen, title screen
   Save / Load
   Mouse support
   Funcional timer
   'Mark' (highlight) function
   3 different pixel styles
   Overview 'map' showing overall progress
   High level overview on the main game screen
   Load picture menu
   Help screen
   Replay of draw progress on screen when picture is complete
   Auto save on exit
   The ability to watch completed replays from the image select screen
   An installer (and a floppy image that uses it)
   An experimental MIDI player
   Option screen (continue last, start/continue another), with configuration
   Periodic auto-save

Note that the MIDI player itself isn't experimental (it's just using Allegro
code), the behavior is. It currently plays through a series of MIDI files that
are placed into RES/MUSIC, as long as the player is working on an image. It
doesn't play on the title screen, loading screen (when coming from the title
screen), or the image complete screen, since if I were to provide MIDI files,
there would be separate ones for each of those. I'm sure I'll come up with
something better and I'm planning to add keys to play the previous/next song
in the list.

What's left to do?
------------------

Right now, the only other feature I might add is some sound effects, but I
don't think that would add very much. Functionally, I think the game is
complete.

Outside of the game, I need to finish up the manual, which is mainly adding the
option section, make the terminology more consistent ('Image' instead of
'Picture'), and check for typos/incorrect stuff.

Current bugs to fix
-------------------

   None that I know of, but I'm sure there's plenty.

Additional notes
----------------

Currently, images can be up to 320x200 pixels in size, with up to 64 colors.
There are two Image versions:

   version 1 only supports square/rectangular images (i.e. every square in a
      X x Y region needs to be a color)
   version 2 allows non-square/irregular images. The tools that create these
      use a transparency mask to determine which squares will need to be
      colored and which won't.
   Version 2 is backward and forward compatible. The version 1 reader will skip
      version 2 data, and the version 2 reader treats the version 1 files like
      earlier versions of the game.

You are viewing proxied material from damaniel.xyz. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.