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