/* $Id: Jzip.txt,v 1.2 2000/10/05 16:29:32 jholder Exp $ */ ------------------- J z i p 2 . 1 ------------------- User's Manual By John Holder (j-holder@home.com) Contents: 1.0 Introduction 2.0 What is Jzip? 2.1 Description 2.2 How do I play Infocom/Inform Games? 2.3 What platforms does Jzip run on? 3.0 Features, and how to use them 3.1 Command line options 3.1.1 Setting the screen size 3.1.2 Setting the size of the command history 3.1.3 Getting version information 3.1.4 Using STRICTZ and why you would want to 3.1.5 DOS only features - Monochrome mode - EGA/VGA bigscreen mode 3.2 Using the command history buffer 3.2.1 Under DOS 3.2.2 Under UNIX/Atari ST 3.3 Using the INFOCOM_PATH environment variable 3.3.1 Under DOS 3.3.2 Under UNIX 3.3.3 Under Atari ST 3.4 Portable Save Game files 3.5 Compressed Game Files 4.0 Utilities for Jzip 4.1 Jzexe - make DOS native .exe game files 4.2 ckifzs - check a Quetzal save file's validity 5.0 Building Jzip 5.1 UNIX/BeOS 5.2 DOS 5.3 Atari ST 5.4 Bugs 6.0 Known Bugs 7.0 Credits 8.0 License Agreement / Disclaimer ___________________________________________________________ 1.0 Introduction Welcome to the Jzip User's manual. I hope this program is useful to you, and that it provides you with many hours of enjoyment. This release of Jzip has seen incredible amounts of improvement - ZSTRICT checking, Z-Spec 1.0 compliance, and Quetzal save files. ___________________________________________________________ 2.0 What is Jzip? 2.1 Description Jzip is a program that emulates a virtual machine created by Infocom, called the Zmachine. All Infocom games (including the famous Zork and many others) are designed to run on this virtual machine, and they are in a format called "Z-code". There are currently eight different versions of Z-code, and Jzip currently supports versions 1-5 and 8. What does this mean? It means Jzip can play any game written in one of these versions of Z-code. All games writtens by Infocom except for Zork Zero, Journey, Shogun, and Arthur (which are version 6 Z-code) can be played with Jzip, as can all games created with Graham Nelson's excellent adventure game compiler, Inform. For more on Inform, see section 6.3. 2.2 How do I play Infocom/Inform Games? All Infocom gamefiles end in .dat. These games are in "Z-code" versions 1-5. All Inform games end in either .z3, .z5, or .z8 (so far). These extensions mean that a file is a "Z-code" adventure game in version 3, version 5, or version 8. These files are not compressed, but are ordinary binary files, and should be downloaded by FTP in 'binary' mode. Jzip can also be combined with a gamefile to make a standalone DOS executable (that with still be playable by Jzip on OTHER platforms!). If you want to learn how to do this, see section 4.1. 2.3 What platforms does Jzip run on? Jzip is known to run on DOS, Windows NT/95, OS/2, UNIX (including DEC/OSF, FreeBSD, HP/UX, IBM/AIX, Linux, NeXT/Mach, SGI/IRIX, Solaris, and SunOS), BeOS and Atari ST machines. If you want to compile Jzip for a new port or just because, see section 5.0. ___________________________________________________________ 3.0 Features, and how to use them 3.1 Command line options Command line option are options that are entered on the command line after typing the name of the file to run. If you wanted to run Jzip with a 4K command history buffer and play the game Zork 1, you would enter it like this: > jzip -k 4096 zork1.dat The command line options for Jzip may be entered in any order, but they must all come before the name of the game file you wish to run. 3.1.1 Setting the screen size There are four command-line options that help set the screen size _if_your_machine_doesn't_do_it_automatically_. -l n tells Jzip there are n lines on your screen. -c n tells Jzip there are n columns on your screen. -r n tells Jzip how big of a right margin to use. The default is none, but if words get chopped off on the edges of the screen instead of wrap, set this to a higher number, like 5. -t n tells Jzip to leave n lines as a top margin. 3.1.2 Setting the size of the command history -k n tells Jzip to use n bytes to keep track of the the commands you have previously typed. The minimum is 1024 bytes(1K), and the maximum is 16384 bytes (16K). For information on how to use the command history, see section 3.2. 3.1.3 Getting version information -v tells Jzip to print a short blurb about the current version. 3.1.4 Using STRICTZ and why you would want to -s n The valid values for n are: 0: no strict checking 1: report only the first occurance of an error 2: report all occurances of an error 3: exit after any error STRICTZ is a method of reporting errors found in Zcode at execution time. This mechanism can be very useful to Inform developers to let them know when they have bugs in their code. 3.1.5 DOS only features Monochrome mode -m tells Jzip to run in black and white mode. 3.2 Using the command history buffer & what it is. The command history buffer of Jzip is a small portion of memory used to store your previous commands. You can easily access your previous commands and edit them, and submit them as new commands. This is a handy feature, especially to correct simple spelling mistakes. 3.2.1 Under DOS At the moment, DOS has the most comprehensive set of editing keys. Here is a list of them and their function: left arrow - move one character to the left right arrow - move one character to the right ctrl+left arrow - move one word to the left ctrl+right arrow - move one word to the right home - move to beginning of line end - move to end of line backspace - delete character to the left of the cursor delete - delete character below cursor cursor up - get previous command cursor down - get next command page up - get "oldest" command page down - display blank prompt (clears current line) esc - display blank prompt (clears current line) 3.2.2 Under UNIX/Atari ST These are the editing key under UNIX and Atari ST and their functions: left arrow - move one character to the left right arrow - move one character to the right backspace - delete character to the left of the cursor cursor up - get previous command cursor down - get next command 3.3 Using the INFOCOM_PATH environment variable Jzip has one environment variable associated with it called INFOCOM_PATH. If Jzip cannot find the gamefile that you specified on the command line, it will sequentially search every directory in this path for the gamefile to play. 3.3.1 Under DOS To use this variable under DOS, add a line that looks similar to the following one to your AUTOEXEC.BAT file. Of course, you will need to adjust it to point to the directories where your game files are! SET INFOCOM_PATH=D:\IF\LTOI1;D:\IF\LTOI2;D:\IF\INFORM; 3.3.2 Under UNIX Under UNIX, you need to set up your default shell initialization file to search in the right places. For csh and tcsh, you would edit your .cshrc / .tcshrc file to include the following: setenv INFOCOM_PATH /usr/games/zcode:/usr/users/jholder/zcode No matter which shell you use (which may mean you need to use set INFOCOM_PATH=/usr/games/zcode), you need to seperate multiple directories with a colon(:). 3.3.3 Under Atari ST I'm not sure, but I assume you would use the same process as you use for UNIX under MiNT. 3.4 Portable Save Game files 3.4.1 Quetzal Jzip now supports the Quetzel portable save file format. This means that save files made with Jzip can be used by any other Zmachine interpreter that supports this standard. 3.4.2 Old Jzip Portable Save files If you have old Jzip save game files, you will need to comment out the "USE_QUETZAL" line in ztypes.h and recompile Jzip to reenable Jzip to read those files. 3.5 Compressed Game Files If Jzip has been builtwith zlib support, Jzip can read zcode files that have been compressed with gzip. This can save a lot of disk space: 304640 Jigsaw.z8 214843 Jigsaw.z8.gz ___________________________________________________________ 4.0 Utilities for Jzip 4.1 JZexe - making stand-alone Infocom-format games for MS-DOS JZexe by Magnus Olsson (mol@df.lth.se) - see JZexe.txt 4.2 ckifzs - This executable checks the validity of Quetzal save files, and is included with the permission of Martin Frost. ___________________________________________________________ 5.0 Building Jzip ------------------------ This section is undergoing updates. The source tree now is different and these instructions may not do what you want. Email for help. ------------------------ 5.1 UNIX / BeOS Copy the file unix.mak to the name Makefile. Look at the makefile and set the flags as indicated for the type of system you have. At the moment, JZIP is known to compile on SunOS, Solaris, HPUX, AIX, NeXT MACH, DEC OSF, Irix, BeOS and Linux. Now type `make`. If the compile doesn't happen right, edit the Makefile and change the "-DPOSIX" to either "-DSYSTEM_FIVE" or "-DBSD". Ask your system administrator if you are not sure which flavour of UNIX you are running. If you still are getting errors, try changing "-ltermcap" to "-lcurses" on the LIBS line of the Makefile. If it still doesn't work, get help from a friend or email me. If your terminal can understand ANSI escape sequences, (a la the Linux console), you may wish to add "-DHARD_COLORS" to the CFLAGS line. 5.2 DOS (& windows, I suppose...) Borland C: copy bcc.mak makefile make Turbo C: Start the development environment, and close all files and projects. Open the "jzip.prj" project and compile. (Made with TC 3.0) (you may need to change the default directories to coincide with your Turbo C installation) 5.3 Atari ST The Makefile is atari.mak, and is targetted at GNU C. Likely you will get odd results by trying to compile the code with Borland TurboC or PureC. 5.4 Bugs Please report bugs and portability bugs to the author. ___________________________________________________________ 6.0 Known Bugs - At the moment, I believe everything works as advertised. Please mail me when (not if) you find bugs. ___________________________________________________________ 7.0 Credits For this release, I offer my most profound thanks to Zarf (Andrew Plotkin) for the ZSTRICT code and Martin Frost for the Quetzal code. My sincere thanks also go to John Menicelli, Dancer, Magnus Olsson, Andrew S. Benham, Mark Phillips, and Michael Phillips for help and bug fixes for past releases, and as always, to all the readers of rec.arts.int-fiction and the users of Jzip who have sent in bug reports and questions. ___________________________________________________________ 8.0 License Agreement / Disclaimer See License.txt, or run jzip -z