pitch-dark/docs/onbeyond.txt
2018-03-29 20:06:54 -04:00

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------------------