-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.txt
236 lines (173 loc) · 9.49 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
You actually want Banbury's fork of this version of Zag, which
has more features and cleaner code:
https://github.com/Banbury/zag
OLD README
---------
This is Zag, an implementation of glulx v3.1.2 for Java
© 2003-2004, Jon Zeppieri (see license/README-license.txt for details)
[jalfred97 @ yahoo . com]
© 2012, David Turner <novalis@novalis.org> (unicode, heap, floats,
misc fixes)
-------------------------------------------------------
Contents:
1. Introduction
2. Requirements
3. Contents of package
4. Using Zag as a Java Web Start application
5. Using Zag as a normal Java application
6. Glk
7. Features missing and present
8. Bugs
-------------------------------------------------------
1. Introduction:
Zag implements v3.1.2 of the glulx standard[1]. It is (to my
knowledge) fully compliant with the specification, and, moreover, it
is a feature complete implementation. Even SONG music is now supported.
Zag was developed under Mac OS 10.2.6 - 10.3.4 and has been tested
(though not enough) on that platform as well as on Linux (2.4.20
kernel) and Windows XP (very briefly).
[1] http://www.eblong.com/zarf/glulx/index.html
2. Requirements
Zag requires the JRE (Java Runtime Environment) version 1.4 or later,
or the JDK (Java Development Kit) version 1.4 or later. To run it as
a Java Web Start application (it cannot be run as an applet), you must
have Java Web Start, which basically means having a recent version of
the the Java Plugin for your web browser. (If you use Mac OS X, you
already have this.)
3. Contents
This package comes with a few things:
a. Complete source code, under the "org," "micromod", and "com"
directories. Please note the licensing differences between the three,
dicussed in the file license/README-license.txt.
b. Complete binary code, under the "bin" directory.
c. "Complete" API documentation, under the "doc" directory. There are
quotation marks around "complete," because my code is really
undocumented. You can browse the APIs, but unfortunately they are not
explained.
d. A signed jar file, containing all the binary code. The jar file
bears my digital signature, the authenticity of which is certified by
Thawte (an internationally trusted Certificate Authority). I have
signed the jar so as to make it easier to use the program with Java
Web Start, but see section 4 for details.
e. License files for both my code and for others' (the mod player and
PNG decoder), in the directory "license."
f. A "build.xml" file, for building the program from source, using
ant.
e. A "zag.jnlp" file, which can be used as a prototype for making
.jnlp files, in order to use Zag as a Java Web Start application.
(But see the next section.)
4. Using Zag as a Java Web Start application
Zag cannot be run as an applet. Applets can only access data by means
of streams; they have no method of randomly accessing data (except
for the contents of dynamic memory, of course). This restriction
makes handling blorb files (which contain graphic and sound resources)
impracticable.
So, the solution is to use Zag as a Web Start application. Now, since
Zag demands access to your file system, there are two possibilities.
Either Zag could use the special, restricted IO APIs designed for Web
Start applications, or it could use the normal APIs but require a
digital signature in order to run.
I chose the latter option. Had I chosen the former, it would have
been difficult to run the program as a normal application, as well,
and it was always my intention to allow both modes of operation.
The jar file that comes with this package is signed by me, and the
signature's validity is asserted by Thawte, a trusted certificate
authority. In other words, Thawte offers assurance that the code was
signed by the party who claims to have signed it and that the code has
not been in any way tampered with since it was signed.
To use a Java Web Start (JWS) application, the user must have JWS
installed. Generally, this means having a recent version of the Java
Plugin for one's web browser. If you use Windows, Solaris, or Linux,
the Java Plugin comes with the JDK and JRE, either of which you can
download from Sun [http://java.sun.com/].
A JWS application is launched when the user downloads a .jnlp file,
which is an XML file of a particular sort. An example is provided in
this package; see the file "zag.jnlp." When JWS runs, it will
download the jar file and note that it wants unresticted access to the
system and network. It will ask the user if he wants to give the
program such access. If the user grants access, Zag will run.
5. Using Zag as a normal Java application
Zag can be launched with the command:
java -jar zag-[version].jar
For instance, if you are running the 1.06 version:
java -jar zag-1.06.jar
You may optionally supply as an argument the path to a valid glulx or
blorb file, or you may supply a fully qualified URL (don't leave out
the protocol portion, e.g, http://, or ftp://, or file:///). Zag will
attempt to execute the specified file when it launches.
6. Glk
Since Zag implements Glulx (and does not implement it trivially), it
supports the glk opcode, which, in turn, means that it comes with
something like an implementation of Glk. This is Zing, which,
unfortunately, stands for "Zing is not Glk." I detest recursive
acronyms, but this was the very first thing that came to mind, and it
stuck. At any rate, the name is accurate, since, in a number of ways,
Zing really is *not* Glk. For one thing, it makes no attempt
whatsoever to keep holy the full 32-bit address range of Glk. Java
does not have unsigned integers, and it is fantastically annoying to
implement them usefully. (You cannot, for instance, index an array
with a Java long integer.) Additionally, Zing does not implement the
Glk dispatch system, since Java already supports interface discovery
through the reflection API. (I did, however, need to support the
notion of "in parameters" and "out parameters," but I did this with
extra type information.)
The org.p2c2e.zing.Glk class provides a set of static methods that map
directly onto the set of glk_ functions defined in the Glk spec.
Originally, I had intended this to be nothing more than a
compatibility layer on top of a fully object-oriented library. (The
idea being that Java programs would use zing directly, without going
through the Glk layer.) This ended up being rather messier than
intended and could probably stand to be cleaned up quite a bit.
Note that Zing does not support the interfaces proposed by Matthew
Russotto; it is not quite so faithful to the C API.
Zing, of course, comes with Zag, and is under the exact same license
(BSD), so you can use it for whatever purposes you desire.
7. Features missing and present
a. Missing: cut, copy and paste.
The most notable feature lacking in Zag (if you do not count speed) is
the ability to select, cut, and paste text. Zag (or rather Zing, the
Glk-alike library used by Zag) does not use the standard Java text
widgets for its story windows, so it does not get this ability "for
free," as it were. (I tried, long ago, to use the javax.swing.text
package for this purpose and failed miserably. Actually, I concluded
that it was possible, but that I would end up writing even more code
than if I worked from scratch.) For my own part, I almost never use
cut and paste while playing interactive fiction, so this doesn't
bother me, but I can imagine it being annoying to others. I apologize
for this. Maybe some day I'll implement it, though probably not. If
someone else wants to, however, I will be happy to incorporate his or
her patches back into the main code tree.
b. Present: command history
Athough it lacks cut & paste, Zag does have a command history buffer
for story windows (a separate history for each such window). Use the
up and down arrow keys to scroll backwards and forwards through the
history. Note that this feature is only present on story windows, not
on "status," or grid, windows.
c: Present: ability to load a file from a URL
Under the File menu, there is an option, "Load URL..." If you select
this, a dialog will pop up prompting you to enter a URL. You may, for
instance, enter the URL of a game file stored on the IF archive. The
file will be downloaded and then opened. The downloaded file will be
placed in temporary storage (e.g., under UNIX, it will be in the /tmp
directory; perhaps this should be configurable). Please note that you
must enter a fully qualified URL, including the protocol string (e.g.,
http://).
Many files on the archive, however, are not directly readable by Zag.
Zag understands glulx (.ulx) files and blorb (.blb) files, but it will
not delve into a .zip file to extract either of these. This feature
may be added in the future, if there is sufficient demand for it.
d. Present: emacs key bindings (not all of them, of course)
In buffer (story) windows, Ctrl-a will position the cursor at the
start of the input. Ctrl-e will position it at the end.
Ctrl-right-arrow will move the cursor forward one word;
Ctrl-left-arrow will move it back one word. Meta-backspace will erase
the previous word. (On a Mac, "Meta" is the Command, or Apple, key.
On Windows, it is the Alt key.)
8. Bugs
All software has bugs, and Zag is no different. Here I will describe
known issues with the program. Surely there are other issues I do not
know about-- likely many of them. *Please* report these. Even
better, fix them and send me a patch.
a. WindowMask (from the WinGlulxe configration file specification) is
implemented using an opaque, black background where it ought to be
transparent. Java isn't up to the task yet.