----------On Beyond Z-Machine!---------
A san inc hack               2018-02-21
---------------------------------------

A ProDOS port of Infocom's Z-Machine
interpreters for the 8-bit Apple II.

                   ~

          System Requirements


On Beyond Z-Machine! requires ProDOS.
It has been tested with ProDOS 2.4.2,
but it may work with classic versions.

Z1, Z2, and Z3 games require an Apple
II Plus or later with a minimum of 64K.

Z4 and Z5 games require an Apple //e
or later with a minimum of 128K and an
80-column card. (An unenhanced //e will
work, as long as it has 128K.)

On Beyond Z-Machine! is designed to be
run from a mass storage device like a
hard drive. In particular, Z4 and Z5
games WILL NOT RUN from a floppy disk,
because they use a custom driver to
read and write files on a ProDOS hard
drive.

It is compatible with modern devices
like the CFFA 3000 that provide mass
storage on real Apple II hardware. It
should also be compatible with all
emulators that emulate mass storage
devices. It is been tested specifically
on AppleWin, Virtual II, OpenEmulator,
Sweet16, KEGS, GSPort, and GSPlus.

The main ONBEYOND.SYSTEM file can be
anywhere on your ProDOS hard drive. The
other files must be in a LIB/
subdirectory beneath the main file:

  ONBEYOND.SYSTEM
  LIB/ONBEYONDZ1
  LIB/ONBEYONDZ2
  LIB/ONBEYONDZ3
  LIB/ONBEYONDZ4
  LIB/ONBEYONDZ5
  LIB/ONBEYONDZ5U

                   ~

              Basic Usage


On Beyond Z-Machine! is an interpreter.
It has no user interface per se. If you
launch it directly, it will simply quit
back to ProDOS. To play a game, you
need to pass it a filename using the
ProDOS startup program protocol, as
documented in the "ProDOS 8 Technical
Reference Manual."

http://www.easy68k.com/paulrsm/6502/
PDOS8TRM.HTM#5.1.5.1

Most Apple II program launchers, such
as ProSel and Bitsy Bye, support this
protocol.

ProSel users: you can create a ProSel
item that launches a specific game.
Assuming ONBEYOND.SYSTEM is located at
/HD/BIN/ONBEYOND.SYSTEM and your game
file is /HD/GAMES/ZORKI.Z3, your ProSel
item would look like this:

Screen title:     Zork I
Prefix:           ?BIN/
Application path: ONBEYOND.SYSTEM
Startup:          ?GAMES/ZORKI.Z3

Bitsy Bye users: rename ONBEYOND.SYSTEM
to BASIS.SYSTEM and put it in the root
directory of your startup disk. (Also
copy the LIB/ directory.) Then you can
select any supported game file in Bitsy
Bye to play it in On Beyond Z-Machine!

                   ~

      Of Suffixes and File Types


On Beyond Z-Machine! supports Z1, Z2,
Z3, Z4, and most Z5 games. It uses
ProDOS file metadata to determine which
interpreter to use. Furthermore, it
chops the suffix off the filename and
replaces it with various other suffixes
for things like saved games and script-
to-file logs. You should set all three
(filename suffix, filetype, auxtype)
unless you know what you're doing.

interpreter|suffix |filetype|auxtype
-----------+-------+--------+-------
    Z1     |  .Z1  |  $F5   | $8001
    Z2     |  .Z2  |  $F5   | $8002
    Z3     |  .Z3  |  $F5   | $8003
    Z4     |  .Z4  |  $F5   | $8004
    Z5     |  .Z5  |  $F5   | $8005
    Z5U    |  .Z5  |  $F5   | $8055 (*)

(*) Astute readers will notice there
are two interpreters available for Z5
files. Z5 was an evolving format while
Infocom was making games. Years later,
Graham Nelson et. al. would reverse
engineer the format and write a real
specification. Modern authoring tools
targeted this specification, and modern
authors created an order of magnitude
more games with these tools than
Infocom ever published themselves.

We are left in a peculiar state, where
Infocom's own Z5 interpreters are "non-
standard," despite them inventing the
format in the first place. (To be
precise, the "standard_interpreter"
library variable returns 0, which may
cause some games to complain or even
refuse to run.)

On Beyond Z-Machine! includes two Z5
interpreters. The first, labeled "Z5",
is highly compatible with all classic
Infocom games and many modern games.
The second, labeled "Z5U", has better
compatibility with some modern games
that use advanced Z-Machine features.

                   ~

                Options


By default, On Beyond Z-Machine! will
enter the most advanced mode that your
machine supports, start the game, and
do nothing else. This means

  - 80 columns if your machine supports
    it, or 40 columns otherwise
  - mixed case on Apple //e or later,
    or uppercase otherwise
  - do not auto-restore from any slot
  - do not change the behavior of the
    SCRIPT command
  - do not automatically turn on SCRIPT
  - warn if required files are missing
    (Z4 and Z5 games only, see below)

You can change this default behavior by
putting an options struct at $0300. If
you want to set any option, you must
set ALL options. There is a checksum
byte that must also be set properly,
otherwise all options will be ignored.

$0300 - 40/80 columns
  #$CE ("N") = 40 columns
  #$D9 ("Y") = 80 columns

  Supported: Z3, Z4, Z5, Z5U

  Z1, Z2 always display in 40 columns

  Z4, Z5 games were originally designed
  to run in 80 columns. Games may have
  display glitches in 40 columns.

$0301 - case
  #$00 = uppercase only
  #$01 = mixed case

  Supported: all

$0302 - auto-restore
  #$00..#$07 = restore game from slot
  #$FF = do not auto-restore

  Supported: all

  Z1, Z2: slot 0 only
  Z3: slots 0-7
  Z4, Z5: slots 0-2 only

$0303 - script to file
  #$00 = "SCRIPT" command outputs to
         printer
  #$01 = "SCRIPT" writes to a file in
         the same directory as the game

  Supported: all

$0304 - auto-script
  #$00 = do not turn on "SCRIPT"
  #$01 = turn on "SCRIPT" as soon as
         the game starts

  Supported: all

$0305 - warn on missing .SAV files
  #$00 = do not warn
  #$01 = warn if .SAV file is missing

  Supported: Z4, Z5, Z5U

  SAVE and RESTORE commands put your
  saved games in a .SAV file in the
  same directory as the game file. Z1,
  Z2, and Z3 interpreters will create
  this file the first time you "SAVE" a
  game. Due to memory constraints, Z4,
  Z5, and Z5U interpreters can not
  automatically create the .SAV file;
  it must already exist.

  On the other hand, if you are opening
  a Z4 or Z5 file and don't care about
  "SAVE"/"RESTORE" (perhaps because the
  game itself doesn't support it), you
  can skip the .SAV file and turn off
  the warning by setting this to 0.

$0306 - "funny complement" checksum
  must be $0300 EOR $0301 EOR $0302 EOR
  $0303 EOR $0304 EOR $0305 EOR #$A5

In other words, after setting all the
other options, do this:

  LDA #$A5
  EOR $0300
  EOR $0301
  EOR $0302
  EOR $0303
  EOR $0304
  EOR $0305
  STA $0306

otherwise all options will be ignored.

                   ~

              Provenance


On Beyond Z-Machine! comprises patched
interpreters from original Infocom
games.

Z1 - Zork I r5
Z2 - Zork II r7 / UG3AU5
Z3 - Stationfall r107 / 870430
     (a.k.a. "Interpreter M")
Z4 - Nord & Bert Couldn't Make Head Or
     Tail Of It r19 / 870722
Z5 - Sherlock r26 / 880127
Z5U- Beyond Zork r57 / 871221

                   ~

                History


2018-02-21

- revision 1

------------------EOF------------------
