289 lines
7.0 KiB
Plaintext
289 lines
7.0 KiB
Plaintext
----------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------------------
|