
                                adv770c.tgz

This package contains C sources (programmatically derived from the A-code
master source) of my 770 points version of Adventure. The game, generally
known as Adv770, and the associated files may be freely distributed and
archived.

If you do find any bugs, however small, please consult the Adv770 bug list
http://www.mipmip.dsl.pipex.com/adv770/bugs.shtml and if appropriate, report
the bug to me on mla@britishlibrary.net.

Game versions with the same major version number (version 1.x at present) are
upward compatible in that they can restore games saved by an earlier version,
unless the bugs list states otherwise. This means that it is quite safe to
upgrade to later bug-fixed versions. Should an unavoidable incompatibility
arise at some future time, it will be signalled by the game major version
changing from 1 to 2.

For more Adv770 or A-code information, please visit my web-site:

                     http://www.mipmip.dsl.pipex.com/

Hope you enjoy the game!

                                       Mike Arnautov
                                        15 Jul 2006


-----------------------------------------------------------------------------

Package contents:

README.txt         This file
*.c                C sources
*.h                header files
adv770.dat         Game data file
advbuild           Linux script which automatically searches for Glk 
                   and readline libraries and builds an executable
                   according to their presence or absence.

-----------------------------------------------------------------------------


                           Compilation symbols

The A-code kernel consists of the two source files adv00.c and adv0.h,
which need to be compiled together with the C sources generated from
A-code by the acdc translator.  See below for command line options
understood by the resulting executable. 

On Linux/Unix, the supplied advbuild.sh script can be used to compile
and link the lot together, using Glk, if available or readline, if
available, or just creating a "dumb" executable, if neither is available.

It is also easy to compile and link the game "manually".  Any ANSI C
compiler can be used to build the executable from the kernel source and
the adv<nn>.c adv<n>.h sources generated by acdc from the A-code game
source.  The simplest possible compilation will result in a "dumb" but
fully functional executable.  The following compilation command line
symbols can be used:

GLK                  Causes the object files to be Glk-instrumented, ready
                     to be linked with a Glk library implementation.
                     If defined, this symbol suppresses the -j -and the -s
                     text formatting command line options.

READLINE             If Glk isn't available, but the libreadline and
                     libncurses are installed, this symbol can be used
                     to build and executable, which supports command history
                     and editing.

MEMORY               Causes text file to be read entirely into memory on
                     game startup. This increases the resident memory size
                     of the running executable.

FILE                 Causes text file to be accessed entirely by reading
                     from disk. This results in the smallest possible
                     executable, but may in some cases degrade the running
                     speed.

SWAP                 This is the default if the C source was created by acdc
                     without the -preload command line option. It causes
                     the game to operate a set of 32 1K text locate buffers,
                     using the "least recently used" algorithm.

SWAP=<n>             This option can be used to modify the default number of
                     locate buffers (32) to any value <n> from 16 to 128.

(NB: If acdc was run with the -preload option, with the result of
creating the additional header file adv6.h, defining one of the MEMORY,
FILE or SWAP symbols will cause the game on its first run to create a
separate data file out of adv6.h.  From then on the game will use the
text file in the specified manner, as if the C code was created without
the -preload option.)

JUSTIFY              Specifies that right-justifying text should be the
                     game default. The default default is to wrap text.
                     The -j command line keyword can be used to override
                     either setting. This symbol is ignored if the GLK
                     symbol is defined. It is also ignored in the "old-
                     style" A-code (i.e. in adv550).

TIGHT_PROMPT         Specifies that the game default should be to suppress
                     blank lines around the '?' prompt lines. This is the
                     default for games written in old-style A-code. Blank
                     lines are the default in games using A-code style 10
                     or higher. Either setting can be overridden by the
                     -b command line keyword.

Any other symbols used in the kernel source are there for the internal
use by the game itself, or for development/debugging purposes.


-----------------------------------------------------------------------------

                          Command line options

NB: the following does not apply to Windows Glk-instrumented 
executables, because winglk does not support invocation command line
arguments. 

An A-code game executable can take a number of command line arguments, of
which the first three (-w, -b and -s) do not apply to Glk-instrumented
executables (even Unix/Linux ones).

 -w                  inverts the default wrap/justify setting of the game.
                     In wrap mode, text is simply broken into lines
                     according to the screen width (see the -s keyword).
                     With justification turned on, each line is right-
                     justified. All of this pre-suppose a fixed font
                     being in use. For variable font devices, which tend
                     to do their own wrapping, the default screen width
                     should be set to zero, meaning "infinite", and the
                     margin should be specified as zero too.

 -b                  inverts the default setting for blank lines around
                     the '?' prompt line. In old-style A-code, which does 
                     not distinguish between replies to queries and general
                     commands, this only affects presence/absence of
                     a blank line after the prompt line, and never before it.

 -p                  pause on exit.
                     Requests that after printing the final exit message
                     the game prompts the player for a <CR>, before exiting.
                     This feature is intended for players who wich to
                     play console version of the game, in a window which
                     closes as soon as the game exits.

 -s <W>x<H>[-<M>]    sets screen size (width in fixed font characters, height
                     in lines, and margin in fixed font blanks).
                     The default screen dimension is 80x24-1, the margin
                     being set to 1 character. The -s keyword allows a
                     different screen size (and optionally margin) to be 
                     specified. Screen width of zero means "infinite" width.
                     Note that the line length cannot be set to less than
                     16 characters and the minimal number of lines per
                     screen is 5.

 -d <dbsdir>         specifies dbs directory.
                     By default, the game database is assumed to live in
                     the same directory as the executable. The -d keyword
                     allows a separate location to be specified. The
                     program will attempt to work out the separator
                     which should follow the directory name, but if in doubt
                     as to the appropriate one for the given platform,
                     the dbs name will be simply concatenated with the
                     supplied pathname -- hence if it doesn't work, try
                     adding the trailing separator to the pathname.

 [-r] <dumpfile>     restore game from dump.
                     The -r keyword is optional in that any command line
                     argument which is not a keyword and is not associated
                     without a preceding keyword, will be taken as the name
                     of the dumpfile to restore on invocation. The game
                     must actively support this feature, otherwise the
                     kernel will exit with an error message.

 -c <cominfile>      replay game from log.
                     This is a debugging tool, which allows a game to be
                     replayed from a log file (see below). If the logfile
                     contains more than one session log, only the first
                     session will be replayed.

-l <logfile>         log the game (non-Glk executables)
                     Specifies the file into which a session log is to
                     be written. The log is human-readable, but has some
                     additional features allowing it to be used subsequently
                     for replaying the session. If the nominated logfile
                     already exists, it gets appended to. If no logile is
                     specified the name of the game is used, suffixed with
                     .log. [NB: this will only work if the log was
                     created by exactly the same version of the game.

 -log <logfile>      log the game (Glk executables)
                     As -l above (because the Glk interface quietly removes
                     "-l <logfile>" from the command line).

 -u {on|off|forbid}  set the initial state of undo-history collection
                     The "forbid" state implies "off" and disallows the
                     undo history. being subsequently switched on from
                     within the game. The default state is "on" for games
                     which define the verb UNDO, and "forbid" otherwise.

 -h                  print command line usage summary.

The functionality of the -s, -u and -w keywords is also provided via kernel
hooks (see procedure special() in the kernel module adv00.c), so that the
game may, at author's discretion, offer the player commands for toggling
the justification switch, switching change history on and off, and altering
screen size and margin. 


=============================================================================

                                            Mike Arnautov
                                            mla@britishlibrary.net
                                            4 Mar 2006
