1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 package org.zmpp.vm;
24
25 import org.zmpp.base.MemoryAccess;
26
27 /***
28 * This interface gives the instructions an abstract access to the current
29 * Z-machine's state.
30 *
31 * @author Wei-ju Wu
32 * @version 1.0
33 */
34 public interface Machine {
35
36 /***
37 * The possible variable types.
38 */
39 enum VariableType { STACK, LOCAL, GLOBAL };
40
41 /***
42 * Returns the story file header.
43 *
44 * @return the story file header
45 */
46 StoryFileHeader getStoryFileHeader();
47
48 /***
49 * Returns true, if the checksum validation was successful.
50 *
51 * @return true if checksum is valid
52 */
53 boolean hasValidChecksum();
54
55 /***
56 * Returns the current program counter.
57 *
58 * @return the current program counter
59 */
60 int getProgramCounter();
61
62 /***
63 * Sets the program counter to a new address.
64 *
65 * @param address the new address
66 */
67 void setProgramCounter(int address);
68
69
70
71
72 /***
73 * Returns the global stack pointer.
74 *
75 * @return the stack pointer
76 */
77 int getStackPointer();
78
79 /***
80 * Sets the global stack pointer to the specified value.
81 *
82 * @param stackpointer the new stack pointer value
83 */
84 void setStackPointer(int stackpointer);
85
86 /***
87 * Returns the value at the top of the stack without removing it.
88 *
89 * @return the stack top element
90 */
91 short getStackTopElement();
92
93 /***
94 * Sets the value of the element at the top of the stack without
95 * incrementing the stack pointer.
96 *
97 * @param value the value to set
98 */
99 void setStackTopElement(short value);
100
101 /***
102 * Returns the reference to the memory access object.
103 *
104 * @return the reference to the MemoryAccess object
105 */
106 MemoryAccess getMemoryAccess();
107
108 /***
109 * Returns the value of the specified variable. 0 is the stack pointer,
110 * 0x01-0x0f are local variables, and 0x10-0xff are global variables.
111 * If the stack pointer is read from, its top value will be popped off.
112 *
113 * @param variableNumber the variable number
114 * @return the value of the variable
115 * @throws IllegalStateException if a local variable is accessed without
116 * a subroutine context or if a non-existent local variable is accessed
117 */
118 short getVariable(int variableNumber);
119
120 /***
121 * Sets the value of the specified variable. If the stack pointer is written
122 * to, the stack will contain one more value.
123 *
124 * @param variableNumber the variable number
125 * @param value the value to write
126 * @throws IllegalStateException if a local variable is accessed without
127 * a subroutine context or if a non-existent local variable is accessed
128 */
129 void setVariable(int variableNumber, short value);
130
131 /***
132 * Pushes a new routine context onto the routine context stack.
133 *
134 * @param routineContext the routine context object
135 */
136 void pushRoutineContext(RoutineContext routineContext);
137
138 /***
139 * Pops the current routine context from the stack. It will also
140 * restore the state before the invocation of the routine, i.e. it
141 * will restore the program counter and the stack pointers and set
142 * the specfied return value to the return variable.
143 *
144 * @param returnValue the return value
145 * @throws IllegalStateException if no RoutineContext exists
146 */
147 void popRoutineContext(short returnValue);
148
149 /***
150 * Returns the current routine context without affecting the state
151 * of the machine.
152 *
153 * @return the current routine context
154 */
155 RoutineContext getCurrentRoutineContext();
156
157 /***
158 * Returns the dictonary.
159 *
160 * @return the dictionary
161 */
162 Dictionary getDictionary();
163
164 /***
165 * Returns the object tree.
166 *
167 * @return the object tree
168 */
169 ObjectTree getObjectTree();
170
171 /***
172 * Sets the output stream to the specified number.
173 *
174 * @param streamnumber the stream number
175 * @param stream the output stream
176 */
177 void setOutputStream(int streamnumber, OutputStream stream);
178
179 /***
180 * Enables or disables the specified output stream.
181 *
182 * @param streamnumber the output stream number
183 * @param flag true to enable, false to disable
184 */
185 void enableOutputStream(int streamnumber, boolean flag);
186
187 /***
188 * Sets an input stream to the specified number.
189 *
190 * @param streamnumber the input stream number
191 * @param stream the input stream to set
192 */
193 void setInputStream(int streamnumber, InputStream stream);
194
195 /***
196 * Selects an input stream.
197 *
198 * @param streamnumber the input stream number to select
199 */
200 void selectInputStream(int streamnumber);
201
202 /***
203 * Reads a string from the selected input stream.
204 *
205 * @param address the start address in memory
206 * @param bufferlen the length of the buffer
207 */
208 void readLine(int address, int bufferlen);
209
210 /***
211 * Prints the ZSCII string at the specified address to the active
212 * output streams.
213 *
214 * @param stringAddress the address of an ZSCII string
215 */
216 void printZsciiString(int stringAddress);
217
218 /***
219 * Prints the specified string to the active output streams.
220 *
221 * @param str the string to print
222 */
223 void print(String str);
224
225 /***
226 * Prints a newline to the active output streams.
227 */
228 void newline();
229
230 /***
231 * Prints the specified ZSCII character.
232 *
233 * @param zchar the ZSCII character to print
234 */
235 void printZchar(short zchar);
236
237 /***
238 * Prints the specified signed number.
239 *
240 * @param num the number to print§
241 */
242 void printNumber(short num);
243
244 /***
245 * Translates a packed address into a byte address.
246 *
247 * @param packedAddress the packed address
248 * @return the translated byte address
249 */
250 int translatePackedAddress(int packedAddress);
251
252 /***
253 * Generates a number in the range between 1 and range. If range is
254 * negative, the random generator will be seeded to abs(range), if
255 * range is 0, the random generator will be initialized to a new
256 * random seed. In both latter cases, the result will be 0.
257 *
258 * @param range the range
259 * @return a random number
260 */
261 short random(short range);
262
263
264
265
266
267 /***
268 * Updates the status line.
269 */
270 void updateStatusLine();
271
272 /***
273 * Sets the Z-machine's status line.
274 *
275 * @param statusline the status line
276 */
277 void setStatusLine(StatusLine statusline);
278
279 /***
280 * Initialization function.
281 *
282 * @param memaccess the MemoryAccess object
283 * @param fileheader the story file header
284 */
285 void initialize(MemoryAccess memaccess, StoryFileHeader fileheader);
286
287 /***
288 * Halts the machine with the specified error message.
289 *
290 * @param errormsg the error message
291 */
292 void halt(String errormsg);
293
294 /***
295 * Saves the current state.
296 */
297 boolean save();
298
299 /***
300 * Restores a previously saved state.
301 */
302 boolean restore();
303
304 /***
305 * Restarts the virtual machine.
306 */
307 void restart();
308
309 /***
310 * Starts the virtual machine.
311 */
312 void start();
313
314 /***
315 * Exists the virtual machine.
316 */
317 void quit();
318
319 /***
320 * Indicates if the virtual machine is running.
321 *
322 * @return true if the machine is running, false, otherwise
323 */
324 boolean isRunning();
325 }