

	Magnetic: An interpreter for Magnetic Scrolls adventures
		Written by Niclas Karlsson
			Version 2.3


    Magnetic is an interpreter for the games written between 1985 and
    1991 by Magnetic Scrolls, a text adventure producer based in London,
    England. Although they only produced seven games they have acquired
    legendary status for text adventures of as good quality as Infocom
    accompanied by exceptional graphics.

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

- WHAT YOU NEED FOR PLAYING -----------------------------------------------

    It is illegal to play Magnetic Scrolls games if you do not own the
    original packages. Their games, sadly enough, have been unavailable
    for years, and your only choice may be downloading them from the
    Internet. Having said this, you should get hold of the following:

	(1) the story files;
	(2) the graphics files (optional);
	(3) the title pictures (optional);
	(4) the hint files (optional);
	(5) documentation from the original packages;
	(6) the Magnetic interpreter.

    The best source for this material is Stefan Meier's Magnetic Scrolls
    Memorial web page, which is part of the IF Legends site at

	http://www.if-legends.org/

- THE STORY FILES ---------------------------------------------------------

    The Magnetic Scrolls games as originally distributed were in a
    somewhat complex data format, different for most platforms. The
    interpreter uses its own story file format, to be identified by the
    file name extension ".mag". You can download all story files from
    the Magnetic Scrolls Memorial site (see above).

    Magnetic has been successfully tested with story files created from
    Amstrad CPC, Acorn Archimedes, Commodore 64, MS-DOS, Spectrum and
    Spectrum +3 versions of the games. An alternative way to obtain the
    story files is to extract them from the original game files.

    Currently the Amiga, Atari ST, Apple Macintosh and Sinclair QL
    releases of the games are not supported. This is because the games
    were originally written in native machine code for Motorola 68000
    based systems (which all the above computers are). When porting to
    other systems Magnetic Scrolls implemented a limited subset of 68000
    machine code as an emulator on the target system; it is this limited
    subset which the Magnetic interpreter implements.

    Magnetic Scrolls also released versions for at least the Apple II
    and Atari XL. Currently, we have not developed any tools to extract
    the data from such versions, nor have we located all the versions for
    these machines. If you have an emulator image or an original version
    for one of these machines, please contact the Magnetic development
    team.

- EXTRACTING STORY FILES FROM C64 VERSIONS --------------------------------

    The Commodore 64 versions of the Magnetic Scrolls games can be
    extracted from C64 disk images (i.e. files representing the contents
    of the games released for the Commodore 64). These files are
    identified by having a file name ending with ".d64". Disk images for
    "The Pawn", "The Guild of Thieves", "Corruption", "Jinxter" and
    "Fish" can be found on the Internet on numerous C64 web sites.

    To convert these files to the interpreter's own format, the Xtract64
    program must be used. Run the program without any arguments to read
    a help screen describing its syntax. You'll find that Xtract64 is
    easy to use; for example, for "The Pawn", the command line might be

	Xtract64 pawn-1.d64 pawn-2.d64 pawn.mag

- EXTRACTING STORY FILES FROM MS-DOS VERSIONS -----------------------------

    Story files can be created by extracting the data from both the
    original MS-DOS releases and the later "Magnetic Windows" releases
    of "Wonderland" and "The Magnetic Scrolls Collection, Volume 1". The
    latter of these comprised new versions of "The Guild of Thieves",
    "Corruption" and "Fish!".

    To convert these files to the interpreter's own format the XtractPC
    (for the original releases) or XtractMW (for the "Magnetic Windows"
    releases) programs, which are included with the 16-bit DOS version
    of the interpreter, must be used. Run XtractPC or XtractMW without
    any arguments to read a help screen.

    The syntax for XtractPC is:

	XtractPC game game.mag

    where "game" is the full path to the data files, minus any trailing
    numbers. For example, the data files for "The Pawn" are called
    "pawn1" to "pawn6". If these files are in a directory
    "c:\Games\Magnetic\Pawn", the command line might be:

	XtractPC c:\Games\Magnetic\Pawn\pawn Pawn.mag

    The syntax for XtractMW is:

	XtractMW game.rdf game.mag

    where "game.rdf" is the full path to the game's main rdf file
    ("all.rdf" for "Wonderland"; "corr.rdf", "fish.rdf" and "guild.rdf"
    for the games in "Collection Volume 1"). For example, for
    "Wonderland", the command line might be:

	XtractMW c:\Games\Magnetic\Wonder\all.rdf Wonder.mag

- THE GRAPHICS FILES ------------------------------------------------------

    The Magnetic Scrolls adventures were as well known for the quality
    of their graphics as of their text. The Magnetic interpreter supports
    graphics files (".gfx") which can be created from the Amiga releases.
    You'll probably want to download the graphics files from the Magnetic
    Scrolls Memorial site.

    The format of Magnetic's graphics files differs between the original
    and Magnetic Windows ("Wonderland" and "Collection Volume 1")
    releases, therefore a story file created from an original release
    cannot be used with a graphics file from a Magnetic Windows release,
    and vice versa.

    Included with the 16-bit DOS version of the the interpreter is
    GfxLink, a tool to build graphics files from the original Amiga
    releases of the Magnetic Scrolls games. To use GfxLink, supply as
    arguments the directory containing the Amiga files and the output
    graphics file name, e.g.

	GfxLink C:\UAE\Games\ThePawn Pawn.gfx

    The graphics files needed for "Wonderland" and the games in
    "Collection Volume 1" are somewhat different from those produced by
    GfxLink; instead GfxLink2 must be used. Firstly, you need an Amiga
    hard-drive installation of the game, and during installation must
    have selected the option to expand the compacted graphics files. If
    you choose this option, two extra files ("user.rsc" and "user.rdf")
    are created by the installer. Then to use GfxLink2, supply as an
    argument the full path to the "user.rsc" file, e.g.

	GfxLink2 C:\UAE\Games\Wonder\user.rsc

    If GfxLink2 detects "Wonderland", the file "wonder.gfx" will be
    created; if "Collection Volume 1" is detected, the files
    "corrupt.gfx", "fish.gfx" and "guild.gfx" will be created.

- THE HINT FILES ----------------------------------------------------------

    The Magnetic Windows releases of the Magnetic Scrolls adventures
    ("Wonderland" and "Collection Volume 1") come with online hints,
    which can be accessed by entering "hint", "hints" or "help" at the
    input prompt. The Magnetic interpreter supports these hints by
    looking for a file with the same name as the story file, but with the
    extension ".hnt". The hint files can be obtained from Stefan Meier's
    Magnetic Scrolls Memorial site.

- THE TITLE SCREENS -------------------------------------------------------

    The Amiga versions of some of the games (as well as the MS-DOS and
    Archimedes versions of "Wonderland") featured colourful title
    screens. Magnetic supports these title pictures, the files for which
    can be obtained from the Magnetic Scrolls Memorial web page. The
    title files should have the same name as the game file, except that
    the title picture files must end in ".png".

- DOCUMENTATION FROM THE ORIGINAL PACKAGES --------------------------------

    To prevent software pirates from spreading their programs, Magnetic
    Scrolls added a password protection to most of their games. Although
    the extraction programs (Xtract64, etc.) offer you the chance to
    remove this type of protection while extracting the story file, most
    games still cannot be won without the original documentation which
    often contained vital clues. Stefan Meier's Magnetic Scrolls Memorial
    web page offers a growing amount of scanned material from the original
    packages. Further material is also available from the Magnetic Scrolls
    Gallery by Rochus Boerner (now maintained by David Sinclair)

	http://www.webpan.com/dsinclair/ms/mscrolls.html

- THE MAGNETIC INTERPRETER (32-BIT DOS VERSION) ---------------------------

    As you are reading this text file you have the Magnetic interpreter
    already. Its most recent release can always be found at

	http://www.ifarchive.org/

    which is a vast archive dedicated to text adventures ("interactive
    fiction").

    Installation is easy. Beside the executable there are only a few
    font files that can either be stored in the current directory or in
    the same directory as the executable. Run the program without any
    arguments to view its help screen. As an example, to play "Fish!"
    you would have to type

	magnetic fish

    The interpreter would display the title screen "fish.png", open the
    story file "fish.mag", the graphics file "fish.gfx", the hint file
    "fish.hnt" (if the game supports hints) and, if successful, run the
    game. If Magnetic is being run in MS-DOS under Windows 95, 98 or ME,
    long file names can be used. The graphics and hint files can
    optionally be specified as second and third arguments on the command
    line.

    Magnetic supports command line editing and history to make typing
    more convenient. All the common editing keys work as you would
    expect. Other features can be activated via hot keys, which are:

      Alt-C  show copyright and license info
      Alt-D  output screen dump
      Alt-H  help
      Alt-P  playback on
      Alt-R  recording on/off
      Alt-S  seed random numbers
      Alt-T  transcription on/off
      Alt-U  undo last turn
      Alt-X  exit game

    When a Magnetic Windows game is started, graphics are not initially
    visible. To turn the graphics on, enter the command "graphics on" at
    the input prompt.

    Magnetic makes use of the Allegro game library for graphics and
    keyboard input. Among other things, the "Allegro.cfg" configuration
    file which comes with Magnetic can be used to tell Magnetic which
    keyboard layout you have. Using keyboard layouts other than the
    standard US one also requires the file "keyboard.dat", which should
    also be included with Magnetic.

- CREDITS -----------------------------------------------------------------

    Niclas Karlsson <nkarlsso@abo.fi>
    Development of the Magnetic interpreter.

    David Kinder <davidk.kinder@virgin.net>
    Magnetic 2.x development, Windows, MS-DOS (32-bit) and Amiga ports.

    Stefan Meier <stefan.meier@if-legends.org>
    Magnetic 2.x development, JMagnetic Java port and the
    Magnetic Scrolls Memorial web site.

    Paul David Doherty <pdd@if-legends.org>
    Magnetic 2.x development, story file extraction, help and testing.

    Stefan Jokisch
    MS-DOS (16-bit) port.

    Torbjrn Andersson
    Unix/Gtk port.

    Simon Baldwin
    Glk port.

    Rochus Boerner
    Title screen pictures.

    For comments and bug reports, our thanks go to Toine de Greef,
    Jacob Gunness, Kai Hesse and Miron Schmidt.

    Dos32 Magnetic uses the following libraries:

      Allegro by Shawn Hargreaves and others.
      libpng by Guy Eric Schalnat, Andreas Dilger, Glenn Randers-Pehrson
        and others.
      zlib by Jean-loup Gailly and Mark Adler.

