00-INSTALL --------------------------------------------  ITETRIS

****************************************************************
****************************************************************
**     IMPORTANT.  B E F O R E    Y O U    I N S T A L L      **
****************************************************************
****************************************************************
VIDEO.
------

The console version works properly with svgalib version 1.2.10
or later. If you are unsure about the version of your library,
look for /lib/libvga.so.*    The library should be found as
libvga.so.X.X.XX  where X.X.XX is the version.

The  latest  version  of  svgalib  can  be  found on the following
FTP sites
     sunsite.unc.edu   in   /pub/Linux/libs/graphics
     tsx-11.mit.edu    in   /pub/linux/sources/libs

as svgalib-X.X.X.tar.gz.

After the library is installed, try  'vgatest' (found in svgalib 'demos'
subdirectory, or in /usr/lib/svgalib). Try the following modes:

        640x350   16 colours (4 bitplanes)
        640x480   16 colours (4 bitplanes)
        640x480, 256 colours (packed-pixel, banked)

If 256-colour mode is supported, than you should not have problems
with the game. If the 256c mode fails, but at least one of
two other modes works, you will have to edit 'DEFAULT_VIDEO'
setting in tetconfig.h Read 00-CONFIGURE for details.

--------------------------------------------------------------------
COMPILER.
--------
To successfully compile the code, you need gcc (I use version 2.7.2),
or egcs and appropriate library: libc5 or glibc.

--------------------------------------------------------------------
JOYSTICK DRIVER.
----------------
If have an analogue joystick and want it to be supported by the game,
get the joystick driver version 0.8.0 (originally by Art Smith)
from sunsite.unc.edu, tsx-11.mit.edu, or one of numerous mirror sites:

metalab.unc.edu   /pub/Linux/kernel/patches/console/joystick-0.8.0.tar.gz
tsx-11.mit.edu    /pub/linux/patches/joystick-0.8.0.tar.gz

This driver is designed to be used as a module, so that you probably don't
need to recompile the kernel: ensure that the kernel supports modules and
does not have a built-in joystick support.

Driver 0.8.0 does not compile with linux kernels 2.1.xx and 2.2.xx.
However a patch is included with this distribution. Copy it to
the location where you uncompressed joystick 0.8.0 driver source and
use patch command in this directory, e.g.:

	cp joystick-patch.2.2.x.diff /usr/src/joystick-0.8.0
	cd /usr/src/joystick-0.8.0
	patch -p0 < joystick-patch.2.2.x.diff 


The new joystick driver is included with latest linux 2.1.xx and 2.2.xx
kernels and is available separately for linux 2.0.xx users at

atrey.karlin.mff.cuni.cz      /pub/linux/joystick/joystick-1.2.xx.tar.gz

This driver supports a wide range of analogue and digital joysticks, however
version 2.1.13 and prior don't work right with an analogue joystick:
try to get version 2.1.14, or use 0.8.0 instead.

It all cases you are not recommended to use joystick on a slow computer.

--------------------------------------------------------------------
FONTS.
------
Check for console font directory. Type

        ls /usr/lib/kbd/consolefonts

If the directory is not found, you may attempt to find the location
of your console fonts with 'find' command, e.g.:

        find  /  -name default8x9

and change appropriately CONSOLE_FONT_DIR parameter in tetconfig.h
Alternatively you can use a sample font file supplied here.
Read 'Font selection' section in 00-CONFIGURE for the details.

---------------------------------------------------------------------
PATHS.
------
Check location of the highscores file specified by SCOREDIR and SCOREFILE
parameters in Makefile. 'make install' creates the directory, if needed,
copies starting score file, and sets adequate permissions. If you use
X-version and cannot log in as 'root', locate it in your home directory
(e.g.  ~/.itetris.score).

IMPORTANT. If you switch from libc5 to glibc or vice versa, the high
scores file becomes incompatible. Repeat 'make install', or simply
delete the high score and run the game once as root. This will
create the new and compatible high scores file. Unfortunately all
results will be lost. The problem is beyond my competence.

****************************************************************
****************************************************************
**                I N S T A L L A T I O N                     **
****************************************************************
****************************************************************

To install the game:

1. To install the SVGALIB version, you must login as 'root'.
   X-version can be installed in your home directory.

2. Check Makefile in the ITETRIS root directory (i.e. directory where
   this document is located) for the binary file and manual paths.
   For example, in some systems you may with to add libraries other than

3. Run configuration script.
   In the simple case, just type 
	configure

   In this case the script will select all available features and
   default directories for binaries, man page and score file.
   
   You may wish to specify command line arguments for 'configure'
   in order to disable or customize some featires (e.g. no joystick,
   only X version, local score file). Consult 00-CONFIGURE. 

   IMPORTANT. Configuration script will exclude unavailable features.
   For example, if SVGALIB is not installed, only X-version will be
   created. If you later install SVGALIB, and decide to re-run the
   script, type 'make wipe' before that. This will clean the cache
   file, and force the script to rebuild it.

   
   If configuration script fails 'illogically' you may attempt to use
   predefined make file, called Makefile.orig. Just make a link to
   activate it:
               ln  -sf  Makefile.orig Makefile


4. Edit file tetconfig.h to specify some extra features, unavailable
   in configuration script.  See 00-CONFIGURE for details.


5. Run one of the following:

        make                    - To create SVGALIB and X versions
        make  itetris           - To create SVGALIB version only
        make  xitetris          - To create X version only

6. Run
        ./itetris
        ./xitetris

   to see how it works.

 Alternatively you can run it with '-D' option to watch the computer playing
 the game

       ./itetris -D
       ./xitetris -D

7. If the game looks all right, and you want to use it, run

        make install

  and
        make install_man

 This will copy the game binary, and manual to directories,
 where it can be accessed without typing the full path.

 Congratulations. You've done it.

 If you want to repeat the process with changed settings,
 type 'make clean' before re-compiling.


****************************************************************
****************************************************************
**  P L A Y I N G     M U S I C    I N    B A C K G R O U N D **
****************************************************************
****************************************************************

The game allows you to play music, as you play game or watch demo.
Music automatically changes with a new level, and stops with ending
the game.

In order to play background music, you need to build a Background Music
List file. Standard location of Background Music List file is specified
during the installation. Normally it is '.itetris.bgl' (pay attention on
the leading dot) in user's home directory. This location can be suppressed
with -M command line option, so that several lists can be used.

Background Music List is is a text file, that contains command lines to
involve music players by levels in the following order:

        - Introduction
        - Selection screen
        - Level 0  to Level 9 (10 lines)
        - End of game (statistics)
        - Top score reached


Each command line starts from the playing program name and contains music file
name and options recognized by the program. As usual, for the player you do not
needed to specify a path, that is contained in PATH environment variable (i.e.
/usr/bin/). Be sure that the player name and path (if needed) are specified
correctly: on failing to start the program, the system will revert screen to
text mode in the middle of the game, forcing you to restart the computer.
Unfortunately, I cannot fix this problem (shell or kernel bug ?) so far.

Each command line can be prefixed with modes in angle brackets <...> 
The modes are specified in the same way as for \fI-o\fR command line
argument but are effective only for current line. See example below.

A Background Music List may also include comments, continuation and quiet lines.

COMMENTS start with a hash(#) character. Comments may follow a command line
after at least one space or Tab, or appear as a separate comment line, starting
with #. Comment lines may be inserted anywhere in the file.

CONTINUATION LINE is used instead of a command line to indicate, that the music
should not be interrupted at the corresponding level. Continuation line starts
with an asterisk (*).

QUIET LINE is used to indicate that the music should stop at the current level.
It starts with a hyphen(-).


Example:
########################################################
#  Sample background music list to use with itetris    #
########################################################
# Next command will be terminated with SIGKILL signal,
# and loop is disabled
<Kl>playmidi -a /f:/mid/gusmid/678-ital.mid # Played in intro
*                                       # Selection screen - tune unchanged
#
# A comment line can appear anywhere
#
s3mod/   f:/mod/lizard/tango.mod        # Level 0
# For next command, sysout will not be masked, 
# but syserr will
<oE>xmp -q /f:/mod/s3m/cronolog.s3m     # Level 1
*                                       # Level 2 - unchanged
midp    /f:/mod/xm/n97-amb2.xm          # Level 3
*                                       # Level 4 - unchanged
playmidi /f:/mid/gusmid/682-schw.mid    # Level 5
*                                       # Level 6
s3mod -q /f:/mod/lizard/watbelow.mod    # Level 7
*                                       # Level 8
nspmod  /f:/mod/lizard/trans_at.mod     # Level 9
-                                       # Statistics (music stops)
playmidi /f:/mid/when_im_sixty_four.mid # Top scorer
########################################################
#  End of background music file list                   #
########################################################

A sample Background music file list, itetris.bgl is supplied in the directory
where this document is found.

Choosing a music player:

- The playing program must be a non-X application, that do not communicate to
  the screen or the keyboard, other than through the standard output and input
  files. These files are automatically redirected to /dev/null, while you must
  not specify any redirection in a command line of the music list.

- In particular, you should apply use a player, that uses ncurses (or curses)
  library, since this library operates directly to /dev/console. Fortunately,
  some curses-based players (e.g s3mod), can be started in quiet mode, others
  (like mikmod) can be recompiled without access to libncurses.

- If you use joystick for playing game, the player obviously should not use it.
  So far, I haven't came across any player that refers to a joystick.

- The player should proceed kill (SIGTERM) event and release playing device
  (/dev/sequencer or /dev/dsp), as well as all heap memory, on receiving
  the killing signal.

- The player should not poll (lock the CPU), while waiting for an event. I have
  serious problems with 'gmod', presumably because of this problem. I wouldn't
  recommend using 'gmod' with the game.


The following players appear to be all right with the game:

        playmidi v 2.3
        midp (MIDAS Module Player) v 0.1.0
        s3mod  v 1.09  (quite mode)
        nspmod v 1.0

The following players appear to be more or less right with the game:
        midp (MIDAS) v 0.1.0 - newer versions may
                         cause problems because of libncurses
        s3mod  v 1.09  - quiet mode needed
        nspmod v 1.0
        mikmod v 3.0   - quiet mode needed
        xmp v  1.1.3   - quiet mode needed; produces "can't reset terminal"
                         at end - just ignore it.
        playmidi v 2.4 
	mpg123  v0.59r


****************************************************************

CONTACT DETAILS
Email:     xifrac@yahoo.com.au




