ZAX v0.9
Z-Code Application Executor
Matt Kimmel
[email protected]
8/25/97
LEGAL STUFF
The Zax application, the ZMachine class package, the TextScreen widget,
and all accompanying documentation and source code (collectively
referred to as "the Zax Software") are copyright (c) 1997, Matthew E.
Kimmel. The Zax Software may be redistributed freely under the following
conditions: (1) That no profit is made from the sale or distribution of
the Zax Software (2) That the source code contained in the Zax Software,
or any portion thereof, not be modified in any way or incorporated into
any other software without pemission (3) That this legal statement be
distributed unmodified with the Zax Software, and that Matthew E. Kimmel
be credited for its authorship.
With that said, anyone who wishes to include any of my code in their own
or who wishes to base a new application on this code is encouraged to
contact me.
WHAT IS ZAX?
Zax is a Java 1.0.2 implementation of the Z-Machine. An explanation of
the Z-Machine is beyond the scope of this document, but in a nutshell,
it is a virtual machine that runs programs written in Z-code, which
includes all of Infocom's text adventures and a large number of text
adventures and other programs written using the Inform compiler.
Information about all of this is available at the Interactive Fiction
Archive, at
ftp://ftp.gmd.de/if-archive.
Zax is capable of running Z-code programs of versions 1 through 8, with
the exception of version 6 programs. It complies with the Z-Machine
standard v0.2 as specified by Graham Nelson (with a couple of
exceptions; see below). It runs all of the non-graphical Infocom games
except Beyond Zork (which exhibits some trouble with its on-screen map),
and all of the V5 and V8 Inform games that I've tried.
Zax is written entirely in Java 1.0.2, and should run on any
1.0.2-compliant Java Virtual Machine. It may also run on the Java 1.1
virtual machine, but I haven't tested this. Zax runs fine on the VM
supplied with Sun's JDK 1.0.2, and even better on a Just-In-Time
compiler such as Microsoft's or Symantec's. I have tested Zax and
verified its functionality on a number of platforms, including Windows
95 (with Sun, Symantec and Microsoft JVMs), Windows NT (with Microsoft's
JVM), and several varieties of Unix (with Sun's JVM or third-party ports
of it). I have not had the opportunity to try it on a Macintosh
platform; I'd be interested to hear the results if anyone tries it.
Please note that Zax is a Java application, not an applet, and is
therefore not suitable for running in a browser. An excellent Z-Machine
applet called ZPlet is available on the net.
USING ZAX
This section assumes that you have some knowledge of how to use a Java
virtual machine. To use Zax, follow these steps:
1. Extract Zax.zip from the Zax distribution.
2. Set your CLASSPATH to include Zax.zip, as well as the standard Java
1.0.2 classes.
3. Execute the class Zax.
Here's an example of the above steps on a Windows 95 machine with Sun's
JDK installed in C:\Java.
1. cd \
2. mkdir Zax
3. cd Zax
4. unzip -d ..\zax-0.9.zip Zax.zip
5. set CLASSPATH=C:\Java\Lib\Classes.zip;C:\Zax\Zax.zip
6. C:\Java\bin\java Zax
Once Zax is running, just select Play Story... under the File menu and
you're on your way.
HOW ZAX WORKS
Zax is composed of three components: A GUI front-end (Zax); a generic
Z-Machine implementation (package ZMachine); and a text-screen widget
used by the front-end. The ZMachine package is implemented in such a way
that the user interface is completely abstracted. When the CPU is
initialized, it is passed an instance of an object that implements the
interface ZUserInterface; this interface is a set of generic methods for
various fundamental user-interface functions (such as text output and
Z-Machine window management) which can be implemented in any way that
the interface programmer finds desirable. My front-end uses a custom AWT
widget designed to emulate an IBM Text-Mode-style screen, but pretty
much any user interface is possible.
The Zax user interface consists of two classes: Zax, which implements
both a high-level interface (providing functions such as "Play Story"),
and ZaxWindow, which is used by Zax to keep track of logical Z-Machine
windows. Zax is a subclass of java.awt.Frame. Zax uses the
kimmel.awt.TextScreen class to display and manipulate text.
The ZMachine package consists of several classes. ZMachine.ZCPU is the
heart of the Z-Machine; it implements the CPU and all of its opcodes.
ZMemory is the Z-Machine's memory manager; it is responsible for
initializing memory, encapsulating access to it, and dumping it to and
reading it from a stream. ZIOCard encapsulates the Z-Machine I/O streams
(in most cases passing read and write requests to and from the user
interface). ZObjectTable encapsulates the Z-Machine's object table
stuctures (including properties and attributes); it relies heavily on
ZMemory to access the internal Z-Machine data associated with these
structures. ZCallFrame is a class which represents a frame on the
Z-Machine call stack. Finally, as mentioned above, ZUserInterface is an
interface which must be implemented by user interface code.
Full source code is included in the Zax distribution. It is designed in
such a way that enhancements could be made by subclassing existing code,
rather than modifying it. As mentioned in the legal section, please
contact me before using this code in your own programs.
BUGS
I know of a few bugs and missing features in Zax. These include:
o Does not implement transcript or command script I/O streams (this
falls short of Nelson's v0.2 specification).
o Problems with window handling in the user interface make "Beyond Zork"
unplayable. Every other game I've tried has been fine, but then, I
haven't tried everything that's out there.
o Sometimes when the Zax window goes out of focus and then comes back
into focus, it will not accept keystrokes. This seems to be a bug in
the Java AWT; usually it can be fixed by clicking on the text window
a few times.
o Calling the user interface "minimal" wuld be an understatement. But it
works.
If you find any bugs, I'd like to hear about them. Please e-mail me with
details; in particular, let me know which game the bug occurs in, what
you do to cause the bug to happen, and, if possible, the version number
of the game.
FUTURE PLANS: This release is designated "0.9" because it doesn't quite
meet Nelson's v0.2 specification. It is, however, a full release. My
plans for future releases are as follows:
Version 1.0:
o Meet specification v0.2.
o Better user interface.
o Clean up code if possible.
o Better documentation.
Version 1.1:
o Meet the new specification v1.0.
o Comply with standardized save formats.
o Migrate to Java 1.1.
Version 2.0:
o Implement V6 graphics so that the graphical Infocom games are
playable.
o Implement the new graphics standard if it's completed.
Of course, I'm always happy to hear suggestions. If anyone else out
there would like to take part in implementing some of this, let's talk!
THE FINAL WORD
I wrote (and am writing) Zax because I think that the Interactive
Fiction Community can benefit from single Z-Machine that work
identically on a wide range of platforms. Java, with its (more or less)
total portability, makes that possible. Although it has been said that
any current platform that supports Java also has a full-featured, native
Z-Machine for it already (and this is probably true), I think that the
real potential of a Java-based Z-Machine will be unleashed when the
promised new generation of systems and OSes that include native Java
support are released, and/or when V6 and other graphics standards are
implemented in Zax.
I'd love to hear any comments, questions, bug reports, rants, harangues,
compliments, complaints, limericks, etc. Please feel free to send me
e-mail; my e-mail address is
[email protected]. I don't have a web site
yet, but maybe someday it will be at
http://www.javanet.com/~matt.
-Matt Kimmel
August 25, 1997.
