
        Level 9 Interpreter v5.1
        An interpreter for Level 9 games in any format,
        including Spectrum snapshots.

        Copyright (c) 1996-2011 Glen Summers and contributors.
        Contributions from David Kinder, Alan Staniforth,
        Simon Baldwin, Dieter Baron and Andreas Scherrer.

        Level9 is released under the terms of the GNU General
        Public License. See the file COPYING that is included
        with this program for details.


Introduction
------------

During the 1980s a small British company called Level 9, run by two brothers
(Mike and Pete Austin), produced a series of text adventure games for a
variety of computers. These games received considerable critical acclaim and
are probably the best text adventures written for the small cassette based 8
bit computers common in Britain in the 80s.

Level 9 wrote their games using a custom designed system known as "A-Code",
which evolved from games on the 8 bit computers such as the Acorn BBC Model
B, the Sinclair Spectrum and the Commodore 64 to the (then new) 16 bit
machines such as the Amiga and the Atari ST.

From disassembly of Level 9 games there are thought to be four variants of
A-Code, which are detailed below, and all of which are supported by this
interpreter. Thanks go to Paul David Doherty for analysing the games and
producing the table which follows.

  v1    This was used for the earliest games. Spectrum v1 games had
        black text on a grey background. Games known to be released in
        this format:

                Colossal Adventure
                Adventure Quest
                Dungeon Adventure
                Snowball
                Lords of Time

  v2    These releases were made between 1984 and 1985 (and usually say
        so in the initial copyright message). This version introduced
        the yellow text on a black background which became standard.
        Games in this format were:

                Adventure Quest
                Dungeon Adventure
                Lords of Time
                Snowball
                Return to Eden
                Erik the Viking
                Emerald Isle
                Red Moon

  v3    This format, dated 1986, was used by the largest number of
        releases. These were:

                Worm in Paradise
                The Price of Magick
                The Secret Diary of Adrian Mole
                The Growing Pains of Adrian Mole
                The Archers
                The Jewels of Darkness Trilogy (Colossal Adventure,
                Adventure Quest and Dungeon Adventure released as
                one package)
                The Silicon Dreams Trilogy
                (Snowball, Return to Eden and Worm in Paradise)

  v4    This was used for the Time and Magick Trilogy (Lords of Time,
        Red Moon and The Price of Magick), and all Level 9's new games
        from 1987 onwards:

                Knight Orc
                Gnome Ranger
                Ingrid's Back
                Lancelot
                Scapeghost


Supported Formats
-----------------

On several machines (such as the Amiga) Level 9 games were distributed as
an interpreter plus a data file, usually called "gamedata.dat" or something
similar. These games can be played with this interpreter simply by loading
the "gamedata.dat" file.

For the Amiga (and some other formats) the v4 games were released in three
parts, each in a separate data file:

        gamedat1.dat
        gamedat2.dat
        gamedat3.dat

Starting the first game gives a menu from which you can choose which part or
game to play. For this to work the files must have the same basic structure
with a number in it somewhere, e.g. file names

        TimeAndMagick1.dat
        TimeAndMagick2.dat
        TimeAndMagick3.dat

will work.

On other (especially older and smaller) computers the games were distributed
as a single file containing both an interpreter and the game data. Level9
can cope with these files as well, as it automatically searches files for
valid Level 9 games. This however requires that the file not be compressed
in any way. For example, there are several Spectrum snapshots of Level 9
games available which this interpreter can play, but these snapshots must
be in an uncompressed format (e.g. SNA). Commonly snapshots are available in
the compressed Z80 format, but these files can be converted to SNA using the
widely available conversion program "SPConv". Version 1.06 or higher of
"SPConv" is recommended.

Paul David Doherty has written "L9Cut", which can extract Level 9 games from
many different formats. L9Cut can also remove copy protection from Level 9
games. L9Cut can be downloaded from

  http://www.ifarchive.org/indexes/if-archiveXlevel9Xtools.html

This program has been tested on files obtained from releases for the Amiga,
Atari ST, IBM PC, C-64, Spectrum, Atari 800, BBC, Amstrad CPC, Apple 2,
Apple Mac and MSX computers.


Graphics
--------

The first games from Level 9 were text only, but later games included line-
drawn graphics, and then bitmap graphics for the last games. These graphics
are supported by some versions of the interpreter (The 32-bit DOS version
does support graphics, while the 16-bit DOS version does not.).

On some platforms the line-drawn graphics were placed into separate files
(For example, in the Amiga release of "Jewels of Darkness" the game is in
"gamedata.dat" and the graphics in "picture.dat".). In order to show these
pictures the graphics file can be passed as a second command line argument
when starting the interpreter. If no graphics file is specified in this
way, the interpreter will look for a file with the same name as the game
data, but with a file extension of ".pic", ".cga" or ".hrc" (the latter
two being used for graphics files in MS-DOS Level 9 releases).

If no line-drawn graphics file is specified, Level 9 will search the given
game data file for graphics data. This is useful when the game data is a
Spectrum SNA snapshot or a similar memory dump of an emulator.

The last Level 9 games use bitmap graphics. The interpreter can display the
bitmap graphics from C64, Amiga, Atari ST, MS-DOS, Apple Macintosh, BBC B,
Amstrad CPC and Spectrum +3 versions of the games (though for the last three,
there is currently no way to extract the A-code game data in a usable form).

The graphics files contain a number somewhere in the file name, and there
may also be a title picture with a different file name. The interpreter
searches for suitably named graphics files using the following rules. In
all cases copy the graphics and title files to the same directory as the
game.

Amiga, Macintosh and some Atari ST
  The graphics file name is just the number (e.g. "1", "2", etc.).
  The title file is called "title".

Later Atari ST
  The graphics file name is the number with a "squ" file extension
  (e.g. "1.squ", "2.squ", etc.). The title file is just one of the
  normal graphics files.

MS-DOS
  The graphics file name is the number with a "pic" file extension
  (e.g. "1.pic", "2.pic", etc.). The title file is just one of the
  normal graphics files.

C64
  The graphics file name is "pic" followed by the number (e.g.
  "pic1", "pic2", etc.). The title file is called "title mpic".

BBC B "Lancelot"
  As for C64, except that the title file is called "title".

BBC B except "Lancelot"
  The graphics file name is "P.Pic" followed by the number (e.g.
  "P.Pic1", "P.Pic2", etc.). The title file is called "P.Title".

Amstrad CPC and Spectrum +3
  All but the first graphic are contained in a single file called
  "allpics.pic". The first graphics file is "1.pic" and the title
  file is "title.pic".


Meta Commands
-------------

Level9 supports several meta commands, which can be entered on the input
line. These commands are handled by the interpreter rather than being passed
to the game. They are:

  #save         Saves out a game position directly, bypassing any
                prompting (such as for disk changes).

  #restore      Loads in a saved position directly, bypassing any
                protection code within the game.

  #quit         Quits the current game.

  #cheat        Tries to bypass the copy protection code which asks for
                a specific word. This is done by trying every word in
                the game's dictionary. On a slow machine, this can take
                a long time.

  #dictionary   Lists the game dictionary. Press a key to stop the
                listing and return to the input line.

  #picture      If graphics are available, shows the picture specified
                as a number after the picture command, e.g. "#picture 520".

  #seed         Sets the seed of the random number generator to the value
                given, e.g. "#seed 42". This will make randomness within
                the game predictable, which is useful for testing.

  #play         Prompts the user for a text file from which to read
                further input from. Input lines are read from the file
                until the end is reached, at which point the game reverts
                to asking the user for input.

The 32-bit DOS version of Level 9 also supports several hotkeys. Press
Alt-H when playing a game to view a list of the available hotkeys.


History
-------

  v5.1  The bitmap graphics from the US Macintosh release of Lancelot
        now display correctly.

  v5.0  V1 games are also now supported.
        The input logic now correctly handles commas and full stops
        in the user's input for v3 or later games.
        The input logic now allows hyphens and apostrophes to be
        input, which is needed for some v2 games.
        The dictionary listing for v2 games no longer has junk on the
        end.
        The graphics detection algorithm has been improved, so that it
        now correctly finds graphics in all known games.
        A difference in the logic between the v2 and v3 line-drawn
        graphics has been implemented, which corrects the scaling for
        some v2 graphics.
        Added #seed and #play meta commands.

  v4.1  Corrected a bug that made Lancelot unplayable.
        BBC B bitmaps are now shown as they appeared on the original
        computer.

  v4.0  Implemented support for bitmap graphics.

  v3.0  Implemented support for line-drawn graphics.
        Fixed a problem with v4 detection that stopped some versions of
        Scapeghost running correctly.
        Implemented an opcode used by the disk based versions of
        Time and Magick, which now means that saving from these games
        works.
        The interpreter now gives you a reasonable amount of time to
        enter the Lenslok code in protected games, and also tells you
        what the code should be.

  v2.0  Revised the description of v4 games to include all the post-1987
        games, which are now supported.
        V2 games are also now supported.
        Added meta commands.

  v1.0  First release.


Credits
-------

The Level9 interpreter was originally written by Glen Summers. The changes for
version 3.0 were made by David Kinder with additional code from Alan Staniforth
and Simon Baldwin.

For version 4.0, David Kinder integrated the various bitmap decoders, but all
the difficult work was done by Alan Staniforth and Dieter Baron. Alan also
supplied the BBC B bitmap changes for version 4.1.

David and Andreas Scherrer worked on version 5.0 to integrate script playback
from Andreas' .NET port of the interpreter. Andreas created a test harness to
play through all the games, and David and Andreas then worked through the
problems this showed up. Andreas also put much effort into painstakingly
checking all the graphics in the games, which revealed several issues.

Help, testing and information on the various Level 9 formats was provided by
Paul David Doherty. Testing of the fix for Lancelot in version 4.1 was
performed by Guido Mureddu.

If you have any comments or queries, contact David Kinder.
Web: http://www.davidkinder.co.uk/
Email: davidk.kinder@virgin.net


The Interactive Fiction Archive
-------------------------------

If you have access to the Internet and are interested in text adventures,
then you can find all sorts of programs and information at The Interactive
Fiction Archive:

  http://www.ifarchive.org/

The latest version of this program can always be found on this site, in

  http://www.ifarchive.org/indexes/if-archiveXlevel9XinterpretersXlevel9.html

