                     HUGI SIZE CODING COMPETITION 13
                          (The Unlucky Compo?)

Welcome to the Hugi Size Coding Compo #13! Overcome your triskaidekaphobia
and accept this challenge to code a Soko-Ban game in as few bytes as
possible.

"Soko ban" is Japanese for "warehouse man". The game is played using the
arrow keys to move a little blue man and coax him into pushing boxes onto
loading docks. (Although the man only pushes one box at a time, he still
gets blue in the face from the effort.)

                                 Ŀ
                                  0 0 
                                 \___/
                                 
                                Soko Ban

To avoid needing code that makes the man's face turn red, the Backspace
key is used to back out of embarrassing situations, such as pushing a box
into a corner where it can no longer be moved.

To cover any possible embarrassment (such as when your boss is about to
catch you playing this at work) the Esc key can be used to instantly
terminate the program.

The puzzle is solved by pushing all the boxes onto the loading docks, or,
if there are more boxes than docks, by loading all the docks.

There are many levels to the game. Each presents a floor plan to be
solved. The program defaults by loading level A, but any level (A-Z or
0-9) can be specified by entering it on the command line. When a level is
solved, the next level is automatically loaded.



COMMAND LINE
~~~~~~~~~~~~
Your program must load any file entered on the command line. The file
name is a single character A through Z or 0 through 9. You may assume
that the command line will either be empty or contain a valid file name.
You also may assume that there is no path or any extra space characters
in the name. If no name is entered then level A must be loaded. In other
words, the two formats your program must handle are:

                       ENTRY <CR>
                       ENTRY <SPACE> <LEVEL> <CR>



FILE FORMAT
~~~~~~~~~~~
The level files consist of 17, 20-character lines each terminated with
CR+LF. Besides CR and LF only the following characters are used:

                    Char    Hex    Represents
                    ~~~~    ~~~    ~~~~~~~~~~
                    Space   20     Floor
                      !     21     Loading dock
                      "     22     Background
                      #     23     Wall
                      $     24     Box on floor
                      %     25     Box on dock
                      &     26     Man on floor

You may assume that:

* The floor is completely enclosed by walls. In other words, as long as
  your program doesn't allow moves through walls, you don't need to worry
  about moving outside the playing area.

* There is only one man (&).

* The number of boxes is greater than or equal to the number of loading
  docks ($+% >= !+%).

* The level is solvable.



THE DISPLAY
~~~~~~~~~~~
To make the display a little more interesting, your program must convert
the characters in a level file to the colorful characters shown here:

       Char    Hex    Represents      Convert to             Hex
       ~~~~~   ~~~    ~~~~~~~~~~~~    ~~~~~~~~~~~~~~~~       ~~~~~
       Space   20     Floor           White background       20 70
         !     21     Loading dock    Cyan background        20 30
         "     22     Background      Black background       20 07
         #     23     Wall            White screen on red    B0 47
         $     24     Box on floor    Yellow box on white    FE 7E
         %     25     Box on dock     Yellow box on cyan     FE 3E
         &     26     Man on floor    L.Blue face on white   02 79

There are several ways that the solid color character cells used for the
background, floor, and loading docks may be displayed. For instance,
besides a space character (20h) with a cyan background (30h), a loading
dock also may be displayed using 00h or FFh. Since in these cases the
foreground color isn't displayed, it may be anything. You may display the
floor using the letter 'A' as long as the foreground and background
colors are both white. You also may use the solid block character (DBh)
as long as the foreground color is correct (and it doesn't flash).

Set the video mode to 1 (or 0) for a 40x25 text screen, which gives a
somewhat square aspect ratio.

Display the converted file characters centered on the screen, beginning on
the 5th line in the 11th column.

Display the level name in the upper-left corner in light red on the black
background (color attribute = 0Ch). The level name may be displayed
either in upper or lower case.

Display a move counter in the upper-right corner in yellow (attribute =
0Eh). This must be right justified so that the last digit appears in the
40th column. There are no leading zeros.

Your starting screen for level A should look something like this:

                     11th column
                          v
               Ŀ
               A                                      0
                                                       
                                                       
                                                       
  5th line -->                     
                                   
                                   
                                   
                                   
                                   
                                   
                         ۰          
                         ۰          
                         ۰          
                                   
                                   
                                   
                                   
                                   
                                   
                                   
                                                       
                                                       
                                                       
                                                       
               

The dots () shown above merely indicate the position of the input file.
They are not used on your display.



KEY COMMANDS
~~~~~~~~~~~~
Your program must handle the following key commands:

        Arrow keys      Move man (possibly pushing a box)
        Backspace       Undo move
        Esc             Terminate program

Other keys should be ignored, but for the purposes of the compo they are
undefined. They may do anything including crash the machine.

Keystrokes must be read using interrupt 16h, function 0. This is necessary
so that the test program (which hooks INT 16h) can verify proper
operation.

Since the up, down, left, and right arrow keys don't return an ASCII
value, their scan codes must be used. Scan codes are returned in register
ah. (For the other keys, the ASCII value is returned in register al.)

The Backspace key is used to undo moves. Pressing it multiple times must
undo multiple moves, a step at a time, back to the beginning of the
level. Don't forget to undo the move counter.

You may assume a maximum of 4000 moves. Beyond this the program's
behavior is undefined: it may display an incorrect move count, corrupt
the screen, or do anything including crash the machine. Your program
must, however, limit the number of undone moves to the beginning of the
level. In other words, the Backspace key cannot decrement the move
counter below 0.

When the Esc key terminates the program, the normal 80x25 text screen
(mode 3) must be restored.



NEXT LEVEL
~~~~~~~~~~
When the puzzle is solved, your program must beep, wait for a key to be
pressed, and then load the next level. The next level is contained in
another file whose name is also a single ASCII character, the ASCII
successor of the current level's name (i.e. B follows A, etc.). If the
file does not exist (e.g. '[' follows 'Z' but does not exist), your
program must restore the 80x25 text screen (mode 3) and exit cleanly to
DOS.



MOVING
~~~~~~
The up, down, left, and right arrow keys are used to move the man and
possibly a box. This pseudo code shows the logic:

        LET Mx,My = Current man location (screen column and row)
        LET Nx,Ny = Possible new man location
        LET Bx,By = Possible new box location

        IF key = up    THEN Ny:= My-1; By:= Ny-1
        IF key = down  THEN Ny:= My+1; By:= Ny+1
        IF key = left  THEN Nx:= Mx-1; Bx:= Nx-1
        IF key = right THEN Nx:= Mx+1; Bx:= Nx+1

        Increment move counter (even if move is illegal)

        IF contents of Nx,Ny = floor or dock THEN GOTO (1)

        IF contents of Nx,Ny doesn't = box THEN GOTO (2)

        IF contents of Bx,By doesn't = floor or dock THEN GOTO (2)

        Display box at Bx,By

   (1)  Display man at Nx,Ny and blank out man at Mx,My

   (2)  (done)

When moving the man or box, be sure to preserve the background color of
the floor or dock.



STEPS
~~~~~
Here are the steps your program must do:

        Read command line for initial input file name (level)
        Default to level A if no level is specified

   (1)  Open file, or if file does not exist (>Z) go to (3)

        Switch to 40-column text mode (also clears screen)

        Turn off flashing cursor

        Read file, convert to colorful symbols and display them

        Close file handle (if used)

        Display file name in upper-left corner

        Zero move counter

        Display move counter in upper-right corner

        Find location of man symbol

   (2)  Read keyboard using AH=00 INT 16h

        - If arrow key then:
                Save state so move can be undone
                Increment move counter and display it
                Move man, and possibly box, and display them

        - If Backspace key then undo previous move

        - If Esc key then go to (3)

        If level is not solved then go to (2)

        Beep speaker

        Wait for keystroke, read and discard character

        Form next input file name

        Go to (1)

   (3)  Restore 80-column text display (mode 3)

        Exit cleanly to DOS


To make this all as clear as possible, an example program has been
written for you. Look at EXAMPLE.ASM.



TEST PROGRAM
~~~~~~~~~~~~
A test suite is also included in this pack. Adok will use it to verify
that your entry executes properly. Your program must be named
"ENTRY.COM".

Please note that passing the test suite does not guarantee that your
entry has followed all the rules. It's quite possible that a loop hole
exists. Check the Hugi website (http://home.pages.de/~hugi-compo/) and
the eGroups Hugi-compo mailing list for updated test suites.

Besides the rules described in this document, you must comply with the
general rules that apply to all Hugi size coding competitions. These are
described in the file GENERAL.TXT.

If you are unsure about some detail then please post a question to the
Hugi compo mailing list (hugi-compo@egroups.com).

After the compo deadline, a period of public judgment occurs during which
you and others determine penalties for rule violations.



SCHEDULE
~~~~~~~~
Nov 01, 2000               Compo starts
Dec 15, 2000 11:59 pm CET  Deadline for entry submission
Dec 16, 2000               Entries and beta results released
                           Start of Public Judgment
Dec 22, 2000 11:59 pm CET  End of Public Judgment
Dec 23, 2000               Final results released



HISTORY
~~~~~~~
Sokoban (as it is usually spelled) was created in 1982 by Hiroyuki
Imabayashi, president of Thinking Rabbit, a company in Japan. It won
first prize in a computer game contest because of the simplicity of the
rules and the challenge of the problems. It soon became very popular.

Many people have created many levels to the game. There are at least 1400
of them available at: http://mujweb.cz/Zabava/sokoban/downloada.htm

The 0-9 set included in this pack are the original levels by Thinking
Rabbit. The A-Y set are from a Java version written by Riza Purwo Nugroho
of Jakarta, Indonesia, although he is not the original author.



CREDITS
~~~~~~~
A big THANX goes to Bonz who wrote the first draft of these rules and who
pointed out bugs and made other suggestions for improving the code. (Too
bad the graphic version was voted out.) Thank Metalbrain for puzzle "Z",
which has more boxes than docks. Credit also goes to TAD and Ruud whose
previous compo rules and test code I've ripped off to various degrees.
Of course special credit goes to Adok, without whose tireless efforts
there would be no compo. And thanks to all you competitors who make these
compos fun.

Good luck!
(even though luck has nothing to do with it)

Boreal
(loren_blaney@idcomm.com)
