13 |
14 | Older interpreters, such as ITF, are extremely curt when an error condition 17 | is reached (for example, an illegal opcode). It was assumed that 18 | Infocom's shipped story files were bug-free, which is mostly true, 19 | so that errors could only arise through a bug elsewhere in the 20 | interpreter. 21 |
22 | 23 |In debugging Inform games, though, many error conditions can arise and it is 24 | extremely helpful to report these as fully as possible. These include: 25 |
26 | 27 |As mentioned in § 3, it's helpful to screen out any illegal ZSCII 52 | characters between 0 and 31 which are accidentally printed: crashes 53 | can be very mysterious when they cause interpreters to send control 54 | codes to the terminal. 55 |
56 | 57 |In addition, an interpreter might provide options for keeping track of 58 | maximum stack usage and the typical number of opcodes executed between 59 | each read from the keyboard. (But watching these is a time-wasting 60 | activity, so they should be options.) 61 |
62 | 63 |Finally, infinite loops fairly often happen, as in any programming 64 | language. On a system without pre-emptive multi-tasking, this may lock 65 | up the whole machine, as the usual way that porters implement multi-tasking 66 | is to return control to the host operating system only when the keyboard 67 | is read. This can be avoided by providing a point in the code which 68 | could return control to the OS from time to time (say, every 2000 69 | instructions). 70 |
71 | 72 |A number of post-Infocom games have been released which contain 75 | errors, most often trying to perform illegal operations on object 0. 76 | Many interpreters silently ignored these errors, which can make it 77 | very difficult to notice and track down bugs. 78 |
79 | 80 |It is desirable for modern interpreters to be able to notify players 81 | about these bugs, but this can also ruin gameplay. It is highly recommended, 82 | then, that interpreters have four levels of error checking, selectable by 83 | the user (through a command-line or menu option, or similar): 84 |
85 | 86 | 87 |99 | Contents / 100 | Preface / 101 | Overview 102 |
103 | 104 |Section 105 | 1 / 2 / 106 | 3 / 4 / 107 | 5 / 6 / 108 | 7 / 8 / 109 | 9 / 10 / 110 | 11 / 12 / 111 | 13 / 14 / 112 | 15 / 16 113 |
114 | 115 |Appendix 116 | A / B / 117 | C / D / 118 | E / F 119 |
120 | 121 |
13 |
14 | The header table in section 11 17 | details everything the interpreter needs to know 18 | about the header's contents. A few other slots in the header are meaningful 19 | but only by convention (since existing Infocom and Inform games write them). 20 | These additional slots are described here. 21 |
22 | 23 |As in § 11, "Hex" means the address, in hexadecimal; "Len" the length in bytes; "V" the 24 | earliest version in which the feature appeared; "Dyn" means that the byte 25 | or bit may legally be changed by the game during play (no others may legally 26 | be changed by the game); "Int" means that the interpreter may (in some 27 | cases must) do so. 28 |
29 | 30 || Hex | Len | V | Dyn | Int | Contents | 34 | 35 |
|---|---|---|---|---|---|
| 1 | 1 | 1 | Flags 1: | ||
| 3 | * | Bit 3: The legendary "Tandy" bit (see note) | |||
| 2 | 2 | 1 | Release number (word) | ||
| 10 | 2 | 1 | * | Flags 2: | |
| 3 | 41 | | Bit 4: Set in the Amiga version of The Lurking Horror so presumably to do with sound effects? | 42 ||||
| ? | ? | * | 45 |10: Possibly set by interpreter to indicate an error with the printer during transcription | 46 |||
| 12 | 6 | 2 | Serial code (six characters of ASCII) | ||
| 3 | Serial number (ASCII for the compilation date in the form YYMMDD) | ||||
| 38 | 8 | 6 | * | 52 |Infocom used this as 8 bytes of ASCII: the player's user-name on their own mainframe, 53 | useful to identify which person played a saved-game 54 | (however, the bytes are all 0 in shipped story files) 55 | | 56 ||
| 3C | 4 | 59 | | Inform 6 stores 4 bytes of ASCII here, giving the 60 | version of Inform used to compile the file: 61 | for instance, "6.11". | 62 |
78 | In 'The Witness', the Tandy Flag can be set while playing the game, 79 | by typing $DB and then $TA. 80 | If it is set, some of the prose will be 81 | less offensive. For example, "private dicks" become "private eyes", 82 | "bastards" are only "idiots", and all references to "slanteyes" and 83 | "necrophilia" are removed. 84 |85 | We live in an age of censorship. 86 |
114 | Contents / 115 | Preface / 116 | Overview 117 |
118 | 119 |Section 120 | 1 / 2 / 121 | 3 / 4 / 122 | 5 / 6 / 123 | 7 / 8 / 124 | 9 / 10 / 125 | 11 / 12 / 126 | 13 / 14 / 127 | 15 / 16 128 |
129 | 130 |Appendix 131 | A / B / 132 | C / D / 133 | E / F 134 |
135 | 136 |
13 |
14 | 18 |23 | 24 |...the dead hand of the academy had yet to stifle the unbridled 19 | enthusiasms of a small band of amateurs in Europe and America. 20 |
21 |Michael D. Coe, Breaking the Maya Code
22 |
[Note: these links have not been updated since the 20th June 1997 revision of 25 | this document, and as such are very likely to be incorrect.] 26 |
27 | 28 |The resources below are mainly available from the 29 | if-archive 30 | at the anonymous FTP site ftp.gmd.de in Germany, 31 | maintained by Volker Blasius. [Some mirrors of this site 32 | are listed at the 33 | Inform home page. 34 |
35 | 36 |At least eleven essentially different 41 | interpreters 42 | are publically available, of which six are in modern use: 43 |
44 | 45 |The other four interpreters are obsolescent and now hardly used, but 125 | ought not to be forgotten, if only for their contribution to the gradual 126 | process of decipherment. 127 |
128 | 129 |Andrew Plotkin has written a story file to torture interpreters into 155 | revealing non-Standard behaviour, with the appropriately contrived 156 | name of 157 | TerpEtude [an archive containing the source code and compiled 158 | story file]. It supersedes the handful of smaller programs 159 | previously attached to versions of this document. 160 |
161 | 162 |Infocom's original compiler Zilch no longer exists: nor is any of its 167 | language, ZIL, documented anywhere 168 | (though this is similar to MDL, which 169 | is documented): no continuous part of the source code of any of 170 | Infocom's games is in the public domain [but see 171 | 172 | Stu Galley's chapter of an Infocom history article, and the IEEE 173 | article, for fragments]. 174 |
175 | 176 |Inform 177 | is the only other compiler to have existed. It is freeware and 178 | comes with full documentation (of which this document is a part). 179 |
180 | 181 |A source-level debugger for Inform games, called Infix, has been 186 | on the drawing boards for some years now. A group of authors is 187 | currently developing an implementation. 188 |
189 | 190 |Mark Howell has written a toolkit of 195 | 196 | Ztools, or utility programs (1991-5, updated 1997), which includes: 197 |
198 | 199 |These continue to be maintained (by Matthew Russotto) and the first two 222 | are extremely useful. Infodump largely supersedes Mike Threepoint's vocabulary 223 | dumper Zorkword (1991-2), which was important in its day (and 224 | which this author found extremely helpful when writing Inform 1). 225 |
226 | 227 |Most of the Infocom games exist in 265 | several different releases, and some 266 | were written for one Version and then ported to later ones. 'Zork I', for 267 | instance, has at least 11 releases, 2 early, 8 in Version 3 268 | (with release numbers between 5 to 88 in chronological order) and one in 269 | Version 5 (release 52 -- the releases go back to 1 when the version changes). 270 |
271 | 272 |Version 1 and 2 games are extinct, though there are a few fossils 273 | in the hands of collectors. 274 |
275 | 276 |The definitive guide to all Infocom story files known to exist, and an 281 | indispensable reference for anyone interested in Infocom, is Paul David 282 | Doherty's 283 | 284 | Infocom fact sheet, which is regularly updated, concise and 285 | precise. This supersedes Paul Smith's "Infocom Game Information" file. 286 |
287 | 288 |Stefan Jokisch has written a 289 | 290 | brief specification of Infocom-format sound effects files. 291 |
292 | 293 |Martin Frost is the author of the 294 | Quetzal 295 | standard for saved-game files. Patches to adapt Zip-based 296 | interpreters to use Quetzal are now available. 297 |
298 | 299 |Andrew Plotkin is drafting the Blorb standard for packaging up 300 | images and sounds with new Z-machine games. 301 |
302 | 303 |The 304 | Inform Technical Manual documents the format of parsing tables 305 | used in Inform games. 306 |
307 | 308 |Most of the contents of the original Infocom game manuals are still on 309 | sale with the games themselves: the "samplers" (sample transcripts of 310 | play) are not, but an 311 | 312 | archive of them is publically available. So is 313 | 314 | an interesting historical archive of magazine articles concerning 315 | Infocom, and articles from Infocom's own publicity magazine 316 | [indexed 317 | 318 | here]. 319 |
320 | 321 |A Z-Machine mailing list, organised by 326 | Marnix Klooster (marnix@worldonline.nl), 327 | enables debates on this document, discussion of what interpreters 328 | should do, collaboration on new programs and so on. 329 |
330 | 331 |334 | Contents / 335 | Preface / 336 | Overview 337 |
338 | 339 |Section 340 | 1 / 2 / 341 | 3 / 4 / 342 | 5 / 6 / 343 | 7 / 8 / 344 | 9 / 10 / 345 | 11 / 12 / 346 | 13 / 14 / 347 | 15 / 16 348 |
349 | 350 |Appendix 351 | A / B / 352 | C / D / 353 | E / F 354 |
355 | 356 |
13 |
14 | Infocom made six main Versions of the Z-machine and several minor variant 17 | forms. These are recognisably similar but with labyrinthine differences, 18 | like different archaic dialects of the same language. (The archaeological 19 | record stops sharply in 1989 when the civilisation in question collapsed.) 20 |
21 | 22 |Broadly, these fall into two groups: early (Versions 1 to 3) and late 23 | (4 to 6). More fully: 24 |
25 | 26 |27 | Version 1 Early Apple II and TRS-80 Model I games 28 | Version 2 Early Apple II and TRS-80 Model I games 29 | Version 3 "Standard" series games 30 | Version 4 "Plus" series games 31 | Version 5 "Advanced" series games, or, as the marketing division would 32 | have it, "Solid Gold Interactive Fiction" -- a reference to 33 | the colour (though not composition) of the boxes they came in 34 | Version 6 Later games with graphics, mouse support, etc. 35 |36 |
Infocom called their own interpreters ZIP (versions 1 to 3), EZIP/LZIP 37 | (V4), XZIP (V5) and YZIP (V6). They speculated on the possibility of an 38 | interpreter capable of running all Versions, but never published one. 39 |
40 | 41 |The original purpose of the Z-machine was simply to implement as much as 42 | possible of the mainframe game "Zork" on the first popular wave of home 43 | computers. 44 |
45 | 46 |(Apparently "zork" was a nonsense word used at MIT for the current 47 | uninstalled program in progress, and stuck. Just as this document uses the 48 | term "Z-machine" for both the machine and its loaded program (which is also 49 | sometimes called the "story file"), so ZIP (Zork Implementation Program) 50 | was used to mean either the interpreter or the object code it interpreted. 51 | Code was written in ZIL (Zork Implementation Language), which was derived 52 | from MDL (informally called "muddle"), a particularly unhelpful form of 53 | LISP. It was then compiled by ZILCH to assembly code which was passed to 54 | ZAP to make the ZIP.) 55 |
56 | 57 |The Z-machine as originally constructed was surprisingly similar to that in 58 | use today. Version 1 (by Joel Berez and Marc Blank, in Autumn 1979) 59 | contained essentially all of the main architecture: the header, the memory 60 | divided into three, the variables and stack, the object tree, the 61 | dictionary, the instruction format. It used "shift lock" 62 | characters (a text compression trick which did not survive, though it was 63 | more efficient on long sequences of capital letters or punctuation 64 | characters than the technique which replaced it). The first micro 65 | interpreters were for the TRS-80 Model I (by Scott Cutler) and the Apple II 66 | (by Bruce K. Daniels). (A TRS-80 Model II interpreter was written but never 67 | actually shipped.) 68 |
69 | 70 |Version 2 was only a minor enhancement. Abbreviations (used to help 71 | text compression) appeared, but only in one 32-word bank, and the 72 | six-digit serial number appeared in the header, though it wasn't always the 73 | date in those days: Release 7 of 'Zork II', for instance, is numbered 74 | UG3AU5. (Other bizarre serial numbers, such as 000000, appear on fakes 75 | or beta-test releases.) 76 |
77 | 78 |In Version 3, the text encoding alphabets changed again, and the old "shift 79 | lock" codes were dropped in favour of expanding the abbreviations bank to 96 80 | entries. The "verify" opcode and checksums appeared; and a new opcode to 81 | reprint the status line at the top of the screen was introduced. 82 | (Previously, this had been updated only when input was taken from the 83 | keyboard.) The earliest Version 3 releases ('Deadline', then reissues of 84 | 'Zork I' and 'II') were in March and April 1982; the last (the 'Minizork', a 85 | cassette-based Commodore-64 sample of 'Zork') was in November 1987. 86 |
87 | 88 |The idea of widespread portability finally came of age as (between 1982 and 89 | 1985) interpreters were developed for the Atari 400/800, CP/M, the IBM PC, 90 | the TRS-80 Model III, the NEC APC, the DEC Rainbow, the Commodore 64, the TI 91 | Professional, the DECmate, the Tandy-2000, the Kaypro II, the Osborne 1, 92 | MS-DOS, the TI 99/4a, the Apple Macintosh, the Epson QX-10, the Apricot, the 93 | Atari ST and the Amiga. Infocom's middle period coincided with the bubble 94 | in home computers, before the market collapsed to its present apparently 95 | stable state (in which IBM and Apple share almost the entire market), and 96 | the Z-machine's portability gave Infocom a unique advantage over its 97 | competitors. Also, it was an expertly marketed quality brand at a time when 98 | standards of workmanship were very variable; and text-only games did not 99 | seem so dull at a time when graphics were on the whole crude and slow. These 100 | factors combined to give Infocom considerable (though never enormous) 101 | commercial success. 102 |
103 | 104 |By 1982, then, the Z-machine had stabilised to a clean design which was to 105 | remain in use for six years. It was very portable, contained everything 106 | reasonably necessary and most of its complications were badly-needed space 107 | optimisations. (Although Version 3 can fit 128K of story file, the 108 | practical limit in 1982-4 was about 110K, that being the typical disc 109 | capacity on target machines.) The ZAP assembler was cleverly written to 110 | exploit these optimisations, though the Zilch compiler's code generator was 111 | much less efficient. (Interestingly, Infocom did not develop any generic 112 | central library, and Infocom's authors worked fairly independently of each 113 | other: each new game would inherit a small core of code from a previous one, 114 | but this would make up only about 10K of code (about a third of the size of 115 | the Inform library) and would end up being hacked about to suit the new 116 | game. Without a central library, Infocom games waste a fair amount of space 117 | in duplicating code for routine operations many times over. For this 118 | reason, Inform games tend to squash appreciably more design into the 119 | format.) 120 |
121 | 122 |"Verify" and checksum data were quickly introduced. However, the first 123 | serious variant on Version 3 was made in 1984 when a primitive form of 124 | screen-splitting was invented to give 'Seastalker' a sonar display. This 125 | design (perhaps accidentally) became the foundation for the graphics systems 126 | of later versions. 127 |
128 | 129 |Much later (in 1987) sound effects were added to Version 3 for 'The Lurking 130 | Horror', though by that time it was really a Version 5 feature being 131 | passed down to the old model (and only to the Amiga interpreter in any case). 132 | ('TLH' is contemporaneous with 'Sherlock' (in Version 5), the only other game 133 | to actually use the sound effects features.) 134 |
135 | 136 | 137 |During 1983-5, Infocom poured resources into an ambitious pet project of its 138 | founders: 'Cornerstone', a database which used some of the same portable 139 | virtual machine ideas as the Z-machine. The business market, however, was 140 | not nearly as diverse as the home computer market: 'Cornerstone' probably was 141 | the best database available on the Atari ST, but it made no impression on 142 | the IBM PC market. The result was a commercial failure which compounded the 143 | company's over-expansion problems (driving it into a merger with 144 | Activision), though it certainly did not destroy Infocom's viability. 145 |
146 | 147 |By 1985, Infocom had begun to write interpreters in C for the sake of 148 | portability (previously, a different assembly-language program had to be 149 | maintained for every model of computer). The main motivation to keep the 150 | format stable was therefore largely removed: it became possible to upgrade 151 | the Z-machine for every new game, if need be. 152 |
153 | 154 |There were two basic pressures for change. One was that home computers were 155 | larger, and several fundamental restrictions (the game size being only 128K, 156 | the number of objects only 255, the attributes only 32, the properties only 157 | 31) were beginning to bite. The other was the drive for more gimmicks - 158 | character graphics, flashier status lines, sound effects, different 159 | typefaces, and so on. The former led to logical, easy to understand 160 | structural changes in the machine (designed by Marc Blank). The latter, in 161 | contrast, made a mess of the system of opcodes (designed by committee). 162 |
163 | 164 |More does not mean better (halving the price of paper does not double the 165 | quality of the novel). The relieving of size restrictions only increased 166 | design time -- or endangered the quality of the designs being produced. The 167 | Version 3 games have a spare, concise literary style which is absent from 168 | the later games. (But Inform authors have certainly found Version 3 169 | slightly too small for comfort, and it's useful to be able to spill over its 170 | boundaries.) 171 |
172 | 173 |In August the first Version 4 game ('A Mind Forever Voyaging') reached 174 | production. Opinions vary as to whether it was brilliant or awful, but it 175 | was certainly a departure (and could not have been written under Version 3). 176 | In retrospect there is no doubt about 'Trinity', now generally considered 177 | the finest game written: it had previously been shelved as too ambitious 178 | for the Version 3 format. Still, most of the new 1985/6 games remained in 179 | Version 3: there were still plenty of 8-bit home computers around which were 180 | too small for Version 4 games. Despite critical acclaim, the new games 181 | consequently did not sell as well. (Brian Moriarty commented that 'Trinity' 182 | "sold tolerably well. Better than we'd hoped." But his previous game, the 183 | more modest 'Wishbringer', had sold rather better.) 184 |
185 | 186 |Version 5 games began to appear in September 1987 with 'Beyond Zork' and 187 | 'Border Zone'. Both of these games needed new features -- character graphics 188 | run wild in the case of the former, and real-time keyboard interaction in 189 | the latter. The number of opcodes grew ever faster as a result. 190 |
191 | 192 |Although five old games were re-released in Version 5 editions (with an 193 | in-game hints system added, and benefiting from 9-letter word dictionaries, 194 | but otherwise as written), the direction was all too clearly away from the 195 | old text game into graphics: 'Beyond Zork' can look like a parody of an 196 | early mainframe maze game, for instance. Version 6 completed the process 197 | during something of a hiatus in 1988, after which the last few 198 | increasingly-unrecognisable Infocom games appeared: 'Zork Zero', 'Shogun', 199 | 'Journey' and 'Arthur'. 200 |
201 | 202 |It would be wrong, though, to suggest that Infocom regarded text and 203 | graphics as incompatible opposites. Infocom had never been puritanically 204 | opposed to graphics -- 205 |
206 | 207 |208 |214 | 215 |We have nothing against graphics per se. However, given the quality of 209 | graphics currently available on home computers, we would rather use that 210 | disk space for additional puzzles and richer descriptions. 211 |
212 |The New Zork Times (Spring 1984)
213 |
(and, after all, the same author wrote both 'Trinity' and 'Beyond 216 | Zork'). Although the old Infocom parser was considered to have passed its 217 | sell-by date, Version 6 did not drop textual input in favour of some inane 218 | point-and-click interface. Instead, an entirely new parser was devised from 219 | scratch ("using the theory of computational linguistics", according to a 220 | puff by Stu Galley: broadly an LALR(1) parser). 221 |
222 | 223 |Infocom gradually ceased to exist during 1987-9 as its financial problems 224 | grew. But its products were increasingly regarded as anachronistic and 225 | most of its staff had left since the middle years: if Infocom had not 226 | finally been wound up, whether it would have continued to release text games 227 | of the classical style is arguable. 228 |
229 | 230 |Two new formats, versions 7 and 8, have recently been devised to cope with 231 | large Inform games. 232 |
233 | 234 |237 | Contents / 238 | Preface / 239 | Overview 240 |
241 | 242 |Section 243 | 1 / 2 / 244 | 3 / 4 / 245 | 5 / 6 / 246 | 7 / 8 / 247 | 9 / 10 / 248 | 11 / 12 / 249 | 13 / 14 / 250 | 15 / 16 251 |
252 | 253 |Appendix 254 | A / B / 255 | C / D / 256 | E / F 257 |
258 | 259 |
13 |
14 | 17 |23 | 24 |LORD DIMWIT FLATHEAD: "It must have two hundred thousand rooms, four 18 | million takeable objects, and understand a vocabulary of every single word 19 | ever spoken in every language ever invented." 20 |
21 |The New Zork Times (Winter 1984)
22 |
[Note: the information below has not been updated since the 20th June 1997 revision of 25 | this document.] 26 |
27 | 28 |To give some idea of the sizes found in typical story files, here are a few 29 | statistics, mostly gathered by Paul David Doherty, whose "Infocom fact 30 | sheet" file is the definitive reference. 31 |
32 | 33 | 34 |(i) Length
35 |The shortest files are those dating from the time of the 'Zork' 36 | trilogy, at about 85K; middle-period Version 3 games are typically 105K, 37 | and only the latest use the full memory map. In Versions 4 and 5, only 38 | 'Trinity', 'A Mind Forever Voyaging' and 'Beyond Zork' use the full 256K. 39 | 'Border Zone' and 'Sherlock', for instance, are about 180K. (The author's 40 | short story 'Balances' is about 50K, an edition of 'Adventure' takes 80K, 41 | and 'Curses' takes 256K (it's padded out to the maximum size with 42 | background information; the actual game comprises only about 245K). Under 43 | Inform, the library occupies about 35K regardless of the size of game.) 44 |
45 | 46 | 47 |(ii) Code size
48 |'Zork I' uses only about 5500 opcodes, but the number rises 49 | steeply with later games; 'Hollywood Hijinx' has 10355 and, e.g. 50 | 'Moonmist' has 15900 (both these being Version 3). Against this, 'A Mind 51 | Forever Voyaging' has only 18700, and only 'Trinity' and 'Beyond Zork' 52 | reach 32000 or so. (Inform games are more efficiently compiled and make 53 | better use of common code -- the library -- so perform much better here: 54 | the old Version 3, release 10 of 'Curses' (128K long, and a larger game 55 | than any Infocom Version 3 game) has only 6720 opcodes.) 56 |
57 | 58 |(iii) Objects and rooms
59 |This varies greatly with the style of game. 60 | 'Zork I' has 110 rooms and 60 takeable objects, but several quite 61 | complex games have as few as 30 rooms (the mysteries, or 'Hitch-hikers'). 62 | The average for Version 3 games is 69 rooms, 39 takeable objects. 63 |
64 |'A Mind Forever Voyaging' contains many rooms (178) but few objects (30). 65 | 'Trinity', a more typical style of game, contains 134 rooms and 49 66 | objects: the Version 5 'Curses' has a few more of each. Of the Version 6 67 | games, only 'Zork Zero' scores highly here, with 215 rooms and 106 68 | objects. The average for Version 4/5 games is 105 rooms and 54 objects. 69 |
70 |The total number of objects tends to be close to the limit of 255 in 71 | Version 3 games. 'Curses' contains 508. 72 |
73 | 74 | 75 | 76 |(iv) Dictionary
77 |Early games such as 'Zork I' know about 600 words, but 78 | again this rises steeply to about 1000 even in Version 3. 79 | Later games know 1569 ('Beyond Zork') to the record, 2120 ('Trinity'). 80 | (This is achieved by heroic inclusion of unlikely synonyms: e.g. the 81 | Japanese lady with the umbrella can be called WOMAN, LADY, CRONE, 82 | MADAM, MADAME, MATRON, DAME or FACE with any of the adjectives 83 | OLD, AGED, ANCIENT, JAP, JAPANESE, ORIENTAL or YELLOW.) 84 | Version 6 games have smaller dictionaries. So has 'Curses', at 1364. 85 |
86 | 87 | 88 |(v) Opcodes
89 |(a) Of the 1426854 opcodes in the shipped Infocom story files in Paul David 90 | Doherty's collection, here are the top and bottom ten most popular. 91 | (Leaving out those which never occur and so score 0: 92 | nop, art_shift, piracy and the two post-Infocom opcodes, 93 | print_unicode and check_unicode.) 94 |
95 | 96 |97 | Top Ten Opcodes Chart Bottom Ten Opcodes Chart 98 | 1. je 195959 1. print_form 2 99 | 2. print 142755 2. erase_picture 3 100 | 3. jz 112016 3. read_mouse 3 101 | 4. call_vs 104075 4. encode_text 7 102 | 5. print_ret 80870 5. make_menu 9 103 | 6. store 71128 6. not 14 104 | 7. rtrue 66125 7. scroll_window 16 105 | 8. jump 56534 8. pop_stack 17 106 | 9. new_line 52553 9. restore_undo 18 107 | 10. test_attr 46627 10. mouse_window 22 108 |109 | 110 |
So about 2/3rds of all opcodes are those in the top ten; 1 in 8 opcodes is a 111 | je, and only 1 in 710000 is a print_form. 112 |
113 | 114 |(b) An experiment (conducted with the help of Kevin Bracey) sheds some 115 | light on the opcodes most frequently interpreted in typical play. Two 116 | very different games ('Zork I', Version 5 "solid gold" edition; 117 | 'Museum of Inform', a complex Inform example game) were played for 118 | about 50000 cycles of the Z-machine (about 20 moves in 'Zork I', rather 119 | less in the 'Museum'). The following table records all opcodes with 120 | a frequency of at least 1% (i.e., 0.01): 121 |
122 |123 | Zork I Solid Gold (Infocom) Museum of Inform (Inform) 124 | 0.116110 loadb 0.104952 je 125 | 0.103990 storeb 0.101151 jz 126 | 0.101616 jz 0.092727 jump 127 | 0.074979 dec_chk 0.080985 jg 128 | 0.066375 add 0.079039 jl 129 | 0.066283 je 0.070550 inc 130 | 0.060760 store 0.070139 store 131 | 0.053867 loadw 0.047058 loadw 132 | 0.038095 storew 0.034137 get_prop_addr 133 | 0.036428 mul 0.024105 jin 134 | 0.032069 inc_chk 0.022734 rtrue 135 | 0.030243 jump 0.021583 storew 136 | 0.029170 test_attr 0.020075 add 137 | 0.020634 call_vs 0.018485 call_vs 138 | 0.011184 get_sibling 0.016731 and 139 | 0.016082 loadb 140 | 0.012061 call_vn 141 | 0.011879 test_attr 142 | 0.011824 dec 143 | 0.011687 ret 144 |145 |
Adventure games spend most of the time parsing, and the differences 146 | between these tables reflect different parser designs (byte arrays 147 | versus word arrays and arrays stored in properties) as well as 148 | different compiler code generators (Inform does not use inc_chk 149 | or dec_chk, so it uses inc, dec, jl and jg correspondingly 150 | more). In the case of 'Zork I', about a third of all opcodes are 151 | branches: in the case of 'Museum', almost half. 152 |
153 | 154 |157 | Contents / 158 | Preface / 159 | Overview 160 |
161 | 162 |Section 163 | 1 / 2 / 164 | 3 / 4 / 165 | 5 / 6 / 166 | 7 / 8 / 167 | 9 / 10 / 168 | 11 / 12 / 169 | 13 / 14 / 170 | 15 / 16 171 |
172 | 173 |Appendix 174 | A / B / 175 | C / D / 176 | E / F 177 |
178 | 179 |
13 |
14 | Story files are mechanically best identified by their release number 19 | and serial code, which are written into the header information 20 | at the bottom of Z-machine memory. The release number can be anything 21 | between 0 and 65535 but is usually between 1 and 100. 22 | The serial code can consist of any six textual characters but is 23 | usually the date of compilation, arranged YYMMDD: 24 | thus 970619 refers to June 19th, 1997. The notation 25 |
26 | 27 |Release number.Serial code
28 | 29 |identifies particular story files: for example the first production 30 | copy of 'Enchanter' is 10.830810. 31 |
32 | 33 |Paul David Doherty's investigations into Infocom's released games 34 | have resulted in the following list of all known story files compiled 35 | by Zilch, the Infocom compiler: 36 |
37 | 38 || Zork I | 5. (no serial code) |
| Zork I | 15.UG3AU5 |
| Zork II | 7.UG3AU5 |
| Ballyhoo | 97.851218 |
| Cutthroats | 23.840809 |
| Deadline | 18.820311, 19.820427, 21.820512, 26.821108, 27.831005 |
| Enchanter | 10.830810, 15.831107, 16.831118, 24.851118, 29.860820 |
| Four-In-One Sampler I | 26.840731, 53.850407, 55.850823 |
| Four-In-One Sampler II | 97.870601 |
| The Hitch Hiker's Guide To The Galaxy | 47.840914, 56.841221, 58.851002, 59.851108 |
| Hollywood Hijinx | 37.861215 |
| Infidel | 22.830916 |
| Leather Goddesses of Phobos | 118.860325? (beta), 50.860711?, 59.860730, 59.861114 |
| Lurking Horror | 203.870506, 219.870912 (s), 221.870918 (s) |
| Mini-Zork I | 34.871124 |
| Moonmist | 4.860918, 9.861022 |
| Planetfall | 20.830708, 29.840118, 37.851003 |
| Plundered Hearts | 26.870730 |
| Seastalker | 86.840320 (beta), 15.840501, 15.840522, 16.850515, 16.850603 |
| Sorcerer | 67.000000? (beta), 4.840131, 6.840508, 13.851021, 15.851108, 18.860904 |
| Spellbreaker | 63.850916, 87.860904 |
| Starcross | 15.820901, 17.821021 |
| Stationfall | 107.870430 |
| Suspect | 14.841005 |
| Suspended | 5.830222, 7.830419, 8.830521, 8.840521 |
| Wishbringer | 68.850501, 69.850920 |
| Witness | 13.830524, 18.830910, 20.831119, 21.831208, 22.840924 |
| Zork I | 23.820428, 25.820515, 26.820803, 28.821013, 30.830330, 75.830929, 76.840509, 88.840726 |
| Zork II | 17.820427, 18.820512, 18.820517, 19.820721, 22.830331, 23.830411, 48.840904, ?.841220? |
| Zork III | 10.820818, 15.830331, 16.830410, 15.840518, 17.840727 |
Note that the two samplers and the mini-Zork are in the public 87 | domain and may be downloaded from Internet archive sites. 88 | One form of 'Zork I' can be downloaded freely from Activision's 89 | Web pages promoting the Zork brand name. 90 |
91 | 92 |The two problem children here are 'Seastalker', a submarine game 93 | which produces a sonar display across the top of the screen 94 | (and thus needs more sophisticated screen control features than 95 | the other Version 3 games) and 'The Lurking Horror', which uses 96 | sound effects (hence the "(s)" notation). 97 |
98 | 99 || A Mind Forever Voyaging | 77.850814, 79.851122 |
| Bureaucracy | 86.870212, 116.870602 |
| Nord and Bert Couldn't Make Head Nor Tail Of It | 19.870722 |
| Trinity | 11.860509, 12.860926 |
| Beyond Zork | 47.870915, 49.870917, 51.870923, 57.871221 |
| Border Zone | 9.871008 |
| The Hitch Hiker's Guide To The Galaxy SG | 31.871119 |
| Leather Goddesses of Phobos SG | 4.880405 |
| Planetfall SG | 10.880531 |
| Sherlock | 21.871214, 26.880127 (s) |
| Wishbringer SG | 23.880706 |
| Zork I SG | 52.871125 |
| Zork I German | 3.880113 (beta) |
The "SG" games were "solid gold" revisions of existing Version 3 125 | games, adding on-line hints and an UNDO command. Regrettably 126 | these are not the versions distributed by Activision on their recent 127 | re-releases of the Infocom back catalogue. 128 |
129 | 130 |One form of 'Sherlock' uses sound effects. 'Border Zone' introduces 131 | timed input. 'Beyond Zork' features a character-graphics font. 132 | But the most interesting file is the German translation of 'Zork I', 133 | which was never commercially released, introducing an alphabet table 134 | to the format. 135 |
136 | 137 || Game | Mac | Amiga | Apple II | IBM |
| Arthur | 54.890606 | same as Mac | 63.890622? | 74.890714 |
| Journey | 26.890316 | 30.890322 | 77.890616? | 83.890706 |
| Shogun | 292.890314 | 295.890321 | 311.890510? | 322.890706 |
| Zork Zero | 296.881019 | 366.890323 | 383.890602? | 393.890714 |
The rule that story files should be independent of their target 149 | computers was dropped for Version 6 games and this leads to copious 150 | footnotes and exceptions in sections 8.8 and 16 of the standard. 151 | Story files for a particular game are substantially similar to each 152 | other but use fonts, pictures and so on slightly differently. 153 |
154 | 155 |Note that a new Infocom game, Zork: The Undiscovered Underground 158 | was published by Activision in 1997. 16.970828 is the only public 159 | version I know of: however, note that this file was compiled by Inform 160 | and not by Zilch. It is therefore not useful as a witness to Z-machine 161 | rules. 162 |
163 | 164 |167 | Contents / 168 | Preface / 169 | Overview 170 |
171 | 172 |Section 173 | 1 / 2 / 174 | 3 / 4 / 175 | 5 / 6 / 176 | 7 / 8 / 177 | 9 / 10 / 178 | 11 / 12 / 179 | 13 / 14 / 180 | 15 / 16 181 |
182 | 183 |Appendix 184 | A / B / 185 | C / D / 186 | E / F 187 |
188 | 189 |
12 |
13 | 22nd June 1997
18 | 19 |two misprints corrected, 9th August
20 |resources appendix updated and discovery added to header table, 4th September
21 |resources appendix updated and annexe covering Quetzal added, 30th September
22 |corrections and clarifications added, 21th February 2014 - David Fillmore
23 | 24 |This version of the Standard has been superseded.
25 |The latest version of this document can be found at 26 | 27 | https://www.inform-fiction.org/zmachine/standards/current/ 28 |
29 |
13 |
14 | 
19 |
20 | The Z-machine is a design for an imaginary computer: Z is for 'Zork', 21 | the adventure game it was originally designed to play. Like any 22 | computer, it stores its information (mostly) in an array of variables 23 | numbered from 0 up to some large number: this is called its memory. 24 | A stock of some 240 memory locations are set aside for easy and 25 | quick access, and these are called global variables (since they 26 | are available to any part of the program which is running, at any 27 | time).
28 | 29 |The two important pieces of information not stored in memory 30 | are the program counter (PC) and the stack. 31 | The Z-machine continuously runs a program by getting the 32 | instruction stored at position PC in memory, acting on the 33 | instruction and then moving the PC forward to the next. The 34 | instruction set of the Z-machine (the range of possible 35 | actions and how they are encoded as numbers in memory) 36 | occupies much of this document.
37 | 38 |Programs are divided into routines: the Z-machine is always 39 | executing a particular routine, the one which the PC currently 40 | points inside. However, some instructions cause the Z-machine 41 | to call a new routine and then to return where the first 42 | routine left off. The Z-machine therefore needs to remember 43 | details of where to go back, and it stores these on the stack.
44 | 45 |The stack is a second bank of memory, quite separate from the 46 | main one, which has variable size: initially it is empty. 47 | From time to time values are added to, or taken from, the top 48 | of the stack. As well as being used to keep 49 | return details, the stack is also used to store local 50 | variables (values needed only by a particular routine) and, 51 | for short periods only, the partial results of calculations.
52 | 53 |Thus, whereas most physical processors (e.g. Z80 or 6502) have 54 | a number of quick-access variables outside of memory (called 55 | "registers") and a stack inside memory, the Z-machine has the 56 | reverse: it has global variables inside memory and a stack 57 | kept outside.
58 | 59 |There is no access to hardware except by executing particular 60 | Z-machine instructions. For instance, read and 61 | read_char allow use of the keyboard; print and 62 | draw_picture allow use of the screen. The screen's 63 | image is not stored anywhere in memory. Conversely, hardware 64 | can cause the Z-machine to interrupt, that is, to 65 | make a spontaneous call to a particular routine, interrupting 66 | what it was previously working on. This happens only if 67 | the program has previously requested it: for example, by 68 | setting a sound effect playing and asking for a routine to 69 | be called when it finishes; or by asking for an interrupt if 70 | thirty seconds pass while the player is thinking what to type.
71 | 72 |This simple architecture is overlaid by a number of 75 | special structures which the Z-machine maintains inside 76 | memory. There are around a dozen of these but the most 77 | important are:
78 | 79 |The Z-machine is primarily used for adventure games, where the 89 | dictionary holds names of items and verbs that the player might 90 | type, and the objects tend to be the places and artifacts which 91 | make up the game. Each object in the tree may have a parent, 92 | a sibling and a child. For instance, in the start 93 | position of 'Zork I':
94 | 95 |96 | West of House 97 |104 | 105 |You are standing in an open field west of a white house, 98 | with a boarded front door. There is a small mailbox here.
99 | 100 |>open mailbox
101 | 102 |Opening the small mailbox reveals a leaflet.
103 |
At this point (part of) the game's object tree looks like this:
106 | 107 |108 | [ 41] "" 109 | . [ 68] "West of House" 110 | . . [ 21] "you" 111 | . . [239] "small mailbox" 112 | . . . [ 80] "leaflet" 113 | . . [127] "door" 114 |115 | 116 |
Note that objects are numbered from 1 upward. (Object 41 is a 117 | dummy object being used by the game to contain all the "rooms" 118 | or locations, and it has many more children besides object 68.) 119 | The parent of the player is "West of House", whose parent is 41, 120 | which has no parent. The sibling of the player is the mailbox; 121 | the child of the mailbox is the leaflet; the sibling of the 122 | mailbox is the door and so on.
123 | 124 |Objects are bundled-up collections of variables, which come in 125 | two kinds: attributes and properties. Attributes 126 | are simply flags, that is, they can be set or unset, but have no 127 | numerical value. Properties hold numbers, which may in turn 128 | represent pieces of text or other information. For instance, 129 | one of the properties of the mailbox object above contains the 130 | information that the English word "mailbox" refers to it. 131 | One of the attributes of the mailbox object is set to indicate 132 | that it's a container, whereas the same attribute for the 133 | leaflet object is unset. Here is a breakdown of the state of 134 | the mailbox:
135 | 136 |137 | 239. Attributes: 30, 34 138 | Parent object: 68 Sibling object: 127 Child object: 80 139 | Property address: 2b53 140 | Description: "small mailbox" 141 | Properties: 142 | [49] 00 0a 143 | [46] 54 bf 4a c3 144 | [45] 3e c1 145 | [44] 5b 1c 146 |147 | 148 |
So the only set attributes are 30 and 34: all others are unset. 149 | Values are given for properties 44, 45, 46 and 49. The Z-machine 150 | itself does not know or care what this information means: that 151 | is for the program to sort out.
152 | 153 |As a final example, here is part of one of the routines in 154 | 'Zork I':
155 |156 | l0006: print_ret "Suicide is not the answer." 157 | l0007: je g57 #84 ~l0008 158 | je g48 #15 ~rfalse 159 | print_ret "Why don't you just walk like normal people?" 160 | l0008: je g57 #63 ~l0009 161 | print_ret "How romantic!" 162 | l0009: je g57 #3b ~rfalse 163 | get_parent "mirror" local0 164 | get_parent "mirror" sp 165 | je g6b local0 sp ~l0010 166 | print_ret "Your image in the mirror looks tired." 167 | l0010: print_ret "That's difficult unless your eyes are prehensile." 168 |169 | 170 |
Z-machine programs are stored on disc, or archived 173 | on the Internet, in what are called story files. 174 | (Since they were introduced to hold interactive stories.) 175 | A story file consists of a snapshot of main memory only. 176 | The processor begins to run a story file by starting with an 177 | empty stack and a PC value set according to some information 178 | in the story file's header. Note that the story file has to be 179 | set up with many of the structures in memory, such as the 180 | dictionary and the object tree, already created and with 181 | sensible contents.
182 | 183 |The first byte of any story file, and so the byte at 184 | memory address 0, always contains the version number 185 | of the Z-machine to be used. The design was evolutionary 186 | over a period of a decade: as version number increases, the 187 | instruction set grows and tables are reformatted to allow 188 | more room for larger games. All of Infocom's games can be 189 | played using versions between 3 (the majority) and 6. 190 | Games compiled by Inform in the 1990s mainly use versions 5 191 | or 8.
192 | 193 |196 | Contents / 197 | Preface / 198 | Overview 199 |
200 | 201 |Section 202 | 1 / 2 / 203 | 3 / 4 / 204 | 5 / 6 / 205 | 7 / 8 / 206 | 9 / 10 / 207 | 11 / 12 / 208 | 13 / 14 / 209 | 15 / 16 210 |
211 | 212 |Appendix 213 | A / B / 214 | C / D / 215 | E / F 216 |
217 | 218 |
13 |
14 | The Z-machine was created on a coffee table in Pittsburgh in 1979. It 19 | is an imaginary computer whose programs are adventure games, and is 20 | well-adapted to its task, implementing complex games remarkably compactly. 21 | They were still perhaps 100K long, too large for the memory of the home 22 | computers of their day, and the Z-machine seems to have made the first 23 | usage of virtual memory on a microcomputer. Further ahead of its time 24 | was the ability to efficiently save and restore the entire execution state. 25 |
26 | 27 |The design's cardinal principle is that any game is 100% portable to 28 | different computers: that is, any legal program exactly determines its 29 | behaviour. This portability is largely made possible by a willingness to 30 | constrain maximum as well as minimum levels of performance (for instance, 31 | dynamic memory allocation is impossible). 32 |
33 | 34 |Infocom's catalogue continues to be sold and to be played under 35 | interpreter programs, either original Infocom ones or more recent and 36 | generally better freeware ones. About 37 | 130 story files compiled by Infocom's compiler 38 | Zilch survive and since 1993 very many more story files have 39 | been created with the Inform design system. 40 |
41 | 42 |Eight Versions of the Z-machine exist, and the first byte of any 43 | "story file" (that is: any Z-machine program) gives the Version number 44 | it must be interpreted under. 45 |
46 | 47 |The opcode names used in this document were agreed between 1994 and 1995 51 | as a standard set by Mark Howell, author of the disassembler Txd 52 | (part of the Ztools suite of utility programs), and Graham Nelson, 53 | author of the assembly level of Inform. They do not correspond to 54 | Infocom's unpublished opcode names. 55 |
56 | 57 |This Standard was drawn up in November 1995, drawing on a rougher 58 | description written in 1993 and, before that, sketches of table 59 | formats by Mike Threepoint and others. It has formalised 60 | what different interpreter writers regard as the Z-machine, 61 | guaranteeing a reliable and well-featured platform for writers 62 | of new games. The first formal Standard was numbered 0.2, and 63 | this is the second, containing some corrections and clarifications 64 | but also two new features. The following changes are worth noting: 65 |
66 | 67 |Also, the "character set table" is now called the 98 | "alphabet table" (for clarity) and the "mouse data table" has 99 | been renamed the "header extension table." 100 |
101 | 102 |A companion document to this one, by Martin Frost, defines a standard 103 | format called Quetzal for saved-game files. Standard interpreters 104 | are not required to use Quetzal, since choice of saved-game 105 | format does not affect Z-Machine behaviour, but interpreter-writers 106 | are strongly encouraged to consider it. 107 |
108 | 109 |Andrew Plotkin has created a standard format called Blorb 110 | for a "resources" file to accompany or encapsulate 111 | a Z-machine game, neatly packaging up sound and graphics in modern 112 | formats. Again, since the Z-Machine has no formal knowledge of the 113 | means of storage of sound or graphics, interpreters are not required 114 | to support Blorb but as a growing number of games are 115 | contained in Blorb files, it is highly recommended that interpreters 116 | support at least basic Blorb capabilities. 117 |
118 | 119 |To call itself "Standard", an interpreter should (as far as anyone knows) 123 | obey this document exactly for every Version of the Z-machine it claims to 124 | interpret. Interpreters need not provide optional features suggested in 125 | the "remarks" sections, and need not make their source code public. 126 | Each edition of this document has a Revision number, somewhat like the JFIF 127 | identification number used by the JPEG standard. A standard interpreter 128 | should communicate its revision number in three ways: 129 |
130 | 131 | 132 |Few arbitrary choices have been made in writing this document. 147 | Where Infocom's own shipped interpreters disagree, or contain manifest 148 | bugs, it has usually been possible to decide which was "correct". 149 | Elsewhere, minimum levels of performance have been 150 | invented where necessary. (For example, a minimum call-stack size 151 | is needed for programmers to be sure of what level of recursion is safe.) 152 |
153 | 154 |Those few paragraphs which genuinely extend the Infocom format are 155 | marked ***. In any event, Infocom's original shipped interpreters do 156 | not conform to this standard document, because of bugs or because of 157 | slight variations between the Inform output format and Infocom's. 158 |
159 | 160 | 161 |Hexadecimal numbers are written with an initial dollar, as in $ff, 166 | while binary numbers are written with a double-dollar as in $$11011, 167 | according to Inform conventions. The bits in a byte are numbered 0 to 7, 168 | 0 being the least significant and the top bit, 7, the most. 169 |
170 | 171 |Story files are mechanically best identified by their release number 172 | and serial code, which are written into the header information 173 | at the bottom of Z-machine memory. The release number can be anything 174 | between 0 and 65535 but is usually between 1 and 100. 175 | The serial code can consist of any six textual characters but is 176 | usually the date of compilation, arranged YYMMDD: 177 | thus 970619 refers to June 19th, 1997. 178 |
179 | 180 |Paul David Doherty, in his extensive investigations into Infocom's 181 | released games, introduced the notation 182 |
183 | 184 |Release number.Serial code
185 | 186 |to identify particular story files: for example the first production 187 | copy of 'Enchanter' is 10.830810. This notation is used throughout 188 | the Standard when individual Infocom files need to be referred to. 189 |
190 | 191 |The Z-machine has some lexical acuity but it doesn't contain a full parser: 195 | it's like a computer without an operating system. A game program has to 196 | contain its own parser and the tables this uses are not part of the formal 197 | Z-machine specification. (Many Infocom games have similar parsing 198 | table formats simply because, until Version 6, they used an evolving 199 | version of the 'Zork I' parser. A quite different parser was used 200 | in Version 6.) Inform's parsing table formats are documented in the 201 | Inform Technical Manual. For the usual format of Infocom's parsing 202 | tables, see the Ztools utility Infodump. 203 |
204 | 205 |210 |219 | 220 |There is an obvious resemblance between an unreadable script 211 | and a secret code; similar methods can be employed to break 212 | both. But the differences must not be overlooked. The code is 213 | deliberately designed to baffle the investigator; the script 214 | is only puzzling by accident. 215 |
216 | 217 |John Chadwick, The Decipherment of Linear B
218 |
The Z-machine was originally devised by Joel Berez and Marc Blank in 1979. 221 | Marc Blank made most of the Version 4 extensions, and Version 5 was created 222 | by Dave Lebling (with contributions from others including Brian Moriarty, 223 | Duncan Blanchard and Linde Dynneson). Version 6 was largely the work of Tim 224 | Anderson and Dave Lebling. 225 |
226 | 227 |In the reverse direction, decipherment is mostly due to the InfoTaskForce 228 | (David Beazley, George Janczuk, Peter Lisle, Russell Hoare and Chris Tham), 229 | Matthias Pfaller, Mike Threepoint, Mark Howell, Paul David Doherty and 230 | Stefan Jokisch. Only a few of the pieces in the jigsaw were placed by 231 | myself. 232 |
233 | 234 |I gratefully acknowledge the help of Paul David Doherty and Mark Howell, who 235 | each read drafts of this paper and sent back detailed corrections; also, of 236 | Stefan Jokisch and Marnix Klooster who have put a great deal of work into 237 | the fine detail of the specification; and of all those who commented on 238 | the circulated draft. Mistakes and misunderstandings remain my own.
239 |Graham Nelson
240 | 241 |15 November 1995
242 | 243 |Kevin Bracey and Stefan Jokisch discovered most of the mistakes in 244 | Standard 0.2, in developing the first Version 6 interpreters of the 245 | modern age: Zip2000 and Frotz. Matthew Russotto 246 | and Mark Knibbs supplied helpful information about Infocom's own 247 | Version 6 interpreters. Stefan also kindly read and commented on 248 | numerous drafts of the present revision. Finally, discussion about 249 | this document was greatly assisted by the Z-Machine Mailing 250 | List, organised by Marnix Klooster.
251 |Graham Nelson
252 | 253 |22 June 1997
254 | 255 |The majority of the clarifications and updates in this latest revision 256 | are the work of Kevin Bracey and Jason C. Penney. Thanks go also to the 257 | members of the (now defunct) Z-Machine Mailing List, and those of the 258 | intfiction.org forum, especially Dannii Willis, for bringing to light 259 | issues with my initial revision. Special thanks to Andrew Plotkin 260 | for his notes, advice and general help while working on this revised document. 261 |
262 |David Fillmore
263 | 264 |21 February 2014
265 | 266 |269 | Contents / 270 | Preface / 271 | Overview 272 |
273 | 274 |Section 275 | 1 / 2 / 276 | 3 / 4 / 277 | 5 / 6 / 278 | 7 / 8 / 279 | 9 / 10 / 280 | 11 / 12 / 281 | 13 / 14 / 282 | 15 / 16 283 |
284 | 285 |Appendix 286 | A / B / 287 | C / D / 288 | E / F 289 |
290 | 291 |
13 |
14 | 1.1 Regions of memory / 19 | 1.2 Addresses
20 | 21 |The memory map of the Z-machine is an array of bytes with 25 | "byte addresses" running from 0 upwards. This is divided into 26 | three regions: "dynamic", "static" and "high". Dynamic 27 | memory begins from byte address $00000 and runs up to the byte 28 | before the byte address stored in the word at $0e in the header. 29 | (Dynamic memory must contain at least 64 bytes.) Static memory 30 | follows immediately on. Its extent is not defined in the header 31 | (or anywhere else), though it must end by the last byte of the 32 | story file or by byte address $0ffff (whichever is lower). 33 | High memory begins at the "high memory mark" (the byte address 34 | stored in the word at $04 in the header) and continues to the 35 | end of the story file. The bottom of high memory may overlap with 36 | the top of static memory (but not with dynamic memory). 37 |
38 | 39 |Dynamic memory can be read or written to (either directly, 41 | using loadb, loadw, 42 | storeb and storew, 43 | or indirectly with opcodes such as insert_obj and 44 | remove_obj). 45 |
46 | 47 |By tradition, the first 64 bytes are known as the 49 | "header". The contents of this are given later but note that games 50 | are not permitted to alter many bits inside it. 51 |
52 | 53 |It is legal for games to alter any of the tables stored 55 | in dynamic memory above the header, provided they leave the tables 56 | in legal states. 57 |
58 | 59 |Static memory can be read using the opcodes loadb and 61 | loadw. It is illegal for a game to attempt to write to static 62 | memory. 63 |
64 | 65 |Except for its (possible) overlap with static memory, 67 | high memory cannot be directly accessed at all by a 68 | game program. It contains routines, which can be called, 69 | and strings, which can be printed using print_paddr. 70 |
71 | 72 |The maximum permitted length of a story file depends 74 | on the Version, as follows: 75 |
76 | 77 |78 | V1-3 V4-5 V6-8 79 | 128K 256K 512K 80 |81 | 82 | 83 |
There are three kinds of address in the Z-machine, all of 85 | which can be stored in a 2-byte number: byte addresses, word 86 | addresses and packed addresses. 87 |
88 | 89 |A byte address specifies a byte in memory in the range 0 91 | up to the last byte of static memory. 92 |
93 | 94 |A word address specifies an even address in the bottom 96 | 128K of memory (by giving the address divided by 2). (Word addresses 97 | are used only in the abbreviations table.) 98 |
99 | 100 |*** 102 | A packed address specifies where a routine or string begins 103 | in high memory. Given a packed address P, the formula to obtain the 104 | corresponding byte address B is: 105 |
106 | 107 |108 | 2P Versions 1, 2 and 3 109 | 4P Versions 4 and 5 110 | 4P + 8R_O Versions 6 and 7, for routine calls 111 | 4P + 8S_O Versions 6 and 7, for print_paddr 112 | 8P Version 8 113 |114 | 115 |
R_O and S_O are the routine and strings offsets 116 | (specified in the header as words at $28 and $2a, 117 | respectively). 118 |
119 | 120 |*** 122 | Throughout the specification, Versions 7 and 8 are identical 123 | to Version 5 except as stated at § 1.1.4 and 124 | § 1.2.3 above, and in the constant used to 125 | find the file length, as stated in § 11.1.6. 126 |
127 | 128 || Dynamic | 00000 | header |
| 00040 | abbreviation strings | |
| 00042 | abbreviation table | |
| 00102 | property defaults | |
| 00140 | objects | |
| 002f0 | object descriptions and properties | |
| 006e3 | global variables | |
| 008c3 | arrays | |
| Static | 00b48 | grammar table |
| 010a7 | actions table | |
| 01153 | preactions table | |
| 01201 | adjectives table | |
| 0124d | dictionary | |
| High | 01a0a | Z-code |
| 05d56 | static strings | |
| 06ae6 | end of file |
Inform never compiles any overlap between static and high memory 155 | (it places all data tables in dynamic memory). However, many 156 | Infocom games group tables of static data just above the high 157 | memory mark, before routines begin; some, such as 'Nord 'n' 158 | Bert...', interleave static data between routines, so that static 159 | memory actually overlaps code; and a few, such as 'Seastalker' 160 | release 15, even contain routines placed below the high memory 161 | mark. (The original idea behind the high memory mark was that 162 | everything below it should be stored in the interpreter's RAM, while 163 | what was above could reasonably be kept in "virtual memory", i.e., 164 | loaded off disc as needed.) 165 |
166 | 167 |Note that the total of dynamic plus static memory must not exceed 64K. 168 | (In fact, 64K minus 2 bytes.) This is the most serious limitation 169 | on the Z-machine. 170 |
171 | 172 |175 | Contents / 176 | Preface / 177 | Overview 178 |
179 | 180 |Section 181 | 1 / 2 / 182 | 3 / 4 / 183 | 5 / 6 / 184 | 7 / 8 / 185 | 9 / 10 / 186 | 11 / 12 / 187 | 13 / 14 / 188 | 15 / 16 189 |
190 | 191 |Appendix 192 | A / B / 193 | C / D / 194 | E / F 195 |
196 | 197 |
13 |
14 | 2.1 Numbers / 19 | 2.2 Signed operations / 20 | 2.3 Arithmetic errors / 21 | 2.4 Random number generator 22 |
23 | 24 |In the Z-machine, numbers are usually stored in 2 bytes 28 | (in the form most-significant-byte first, then least-significant) 29 | and hold any value in the range $0000 to $ffff (0 to 65535 30 | decimal). 31 |
32 | 33 |These values are sometimes regarded as signed, in the range 35 | -32768 to 32767. In effect -n is stored as 65536-n 36 | and so the top bit is the sign bit. 37 |
38 | 39 |The operations of numerical comparison, multiplication, 41 | addition, subtraction, division, remainder-after-division and 42 | printing of numbers are signed; bitwise operations are unsigned. 43 | (In particular, since comparison is signed, it is unsafe to compare 44 | two addresses using simply jl 45 | and jg.) 46 |
47 | 48 |Arithmetic errors:
51 | 52 |It is illegal to divide by 0 (or to ask for remainder after 54 | division by 0) and an interpreter should halt with an error message 55 | if this occurs. 56 |
57 | 58 |Formally it has never been specified what the result of an 60 | out-of-range calculation should be. The author suggests that the 61 | result should be reduced modulo $10000. 62 |
63 | 64 |The Z-machine needs a random number generator which at any time 66 | has one of two states, "random" and "predictable". When the game 67 | starts or restarts the state becomes "random". Ideally the generator 68 | should not produce identical sequences after each restart. 69 |
70 | 71 |When "random", it must be capable of generating a uniformly 73 | random integer in the range 1 <= x <= n, for any value 74 | 1 <= n <= 32767. Any method can be used for this (for instance, 75 | using the host computer's clock time in milliseconds). The uniformity 76 | of randomness should be optimised for low values of n (say, up to 77 | 100 or so) and it is especially important to avoid regular patterns 78 | appearing in remainders after division (most crudely, being alternately 79 | odd and even). 80 |
81 | 82 |The generator is switched into "predictable" state with a 84 | seed value. On any two occasions when the same seed is sown, identical 85 | sequences of values must result (for an indefinite period) until 86 | the generator is switched back into "random" mode. The generator 87 | should cope well with very low seed values, such as 10, and should not 88 | depend on the seed containing many non-zero bits. 89 |
90 | 91 |The interpreter is permitted to switch between these states 93 | on request of the player. (This is useful for testing purposes.) 94 |
95 | 96 |It is dangerous to rely on the older ANSI C random number routines (rand() and srand()), as some 100 | implementations of these are very poor. This has made some games (in 101 | particular, 'Balances') unwinnable on some Unix ports of Zip. 102 |
103 | 104 |The author suggests the following algorithm:
105 | 106 |1. In "random" mode, the generator uses the host computer's 107 | clock to obtain a random sequence of bits.
108 | 109 |2. In "predictable" mode, the generator should store the 110 | seed value S. If S < 1000 it should then internally generate 111 |
112 | 113 |1, 2, 3, ..., S, 1, 2, 3, ..., S, 1, ...
114 | 115 | 116 |so that random n produces the next entry in this sequence modulo n. 117 | If S >= 1000 then S is used as a seed in a standard seeded 118 | random-number generator. 119 |
120 | 121 |(The rising sequence is useful for testing, since it will 122 | produce all possible values in sequence. On the other hand, a seeded 123 | but fairly random generator is useful for testing entire scripts.) 124 |
125 | 126 |Note that version 0.2 of this standard mistakenly asserted that division 127 | and remainder are unsigned, a myth deriving from a bug in Zip. Infocom's 128 | interpreters do sign division (this is relied on when calculating 129 | pizza cooking times for the microwave oven in 'The Lurking Horror'). Here 130 | are some correct Z-machine calculations: 131 |
132 |133 | -11 / 2 = -5 -11 / -2 = 5 11 / -2 = -5 134 | -13 % 5 = -3 13 % -5 = 3 -13 % -5 = -3 135 |136 | 137 |
140 | Contents / 141 | Preface / 142 | Overview 143 |
144 | 145 |Section 146 | 1 / 2 / 147 | 3 / 4 / 148 | 5 / 6 / 149 | 7 / 8 / 150 | 9 / 10 / 151 | 11 / 12 / 152 | 13 / 14 / 153 | 15 / 16 154 |
155 | 156 |Appendix 157 | A / B / 158 | C / D / 159 | E / F 160 |
161 | 162 |
13 |
14 | 17 |21 | 22 |We do but teach bloody instructions
18 |Which, being taught, return to plague th' inventor
19 |Shakespeare, Macbeth
20 |
4.1 Instructions / 25 | 4.2 Operand types / 26 | 4.3 Form and operand count / 27 | 4.4 Specifying operand types / 28 | 4.5 Operands / 29 | 4.6 Stores / 30 | 4.7 Branches / 31 | 4.8 Text opcodes 32 |
33 | 34 |A single Z-machine instruction consists of the following 38 | sections (and in the order shown): 39 |
40 | 41 |42 | Opcode 1 or 2 bytes 43 | (Types of operands) 1 or 2 bytes: 4 or 8 2-bit fields 44 | Operands Between 0 and 8 of these: each 1 or 2 bytes 45 | (Store variable) 1 byte 46 | (Branch offset) 1 or 2 bytes 47 | (Text to print) An encoded string (of unlimited length) 48 |49 | 50 |
Bracketed sections are not present in all opcodes. (A few opcodes 51 | take both "store" and "branch".) 52 |
53 |There are four 'types' of operand. These are often specified 55 | by a number stored in 2 binary digits: 56 |
57 | 58 |59 | $$00 Large constant (0 to 65535) 2 bytes 60 | $$01 Small constant (0 to 255) 1 byte 61 | $$10 Variable 1 byte 62 | $$11 Omitted altogether 0 bytes 63 |64 | 65 |
Large constants, like all 2-byte words of data in the Z-machine, 67 | are stored with most significant byte first (e.g. $2478 is stored as 68 | $24 followed by $78). A 'large constant' may in fact be a small 69 | number. 70 |
71 | 72 |Variable number $00 refers to the top of the stack, 74 | $01 to $0f mean the local variables of the current routine 75 | and $10 to $ff mean the global variables. It is illegal to 76 | refer to local variables which do not exist for the current routine 77 | (there may even be none). 78 |
79 | 80 |The type 'Variable' really means "variable by value". Some 82 | instructions take as an operand a "variable by reference": for instance, 83 | inc has one operand, the 84 | reference number of a variable to increment. This operand usually has type 85 | 'Small constant' (and Inform automatically assembles a line like 86 | @inc turns by writing the operand turns as 87 | a small constant with value the reference number of the variable 88 | turns). 89 |
90 | 91 |Each instruction has a form (long, short, extended or variable) 93 | and an operand count (0OP, 1OP, 2OP or VAR). 94 | If the top two bits of the opcode are $$11 the form is variable; 95 | if $$10, the form is short. If the opcode is 190 ($BE in hexadecimal) 96 | and the version is 5 or later, the form is "extended". Otherwise, the 97 | form is "long". 98 |
99 | 100 |In short form, bits 4 and 5 of the opcode byte give an operand 102 | type as above. If this is $11 then the operand count is 103 | 0OP; otherwise, 1OP. In either case the opcode number is 104 | given in the bottom 4 bits. 105 |
106 | 107 |In long form the operand count is always 2OP. The opcode number 109 | is given in the bottom 5 bits. 110 |
111 | 112 |In variable form, if bit 5 is 0 then the count is 2OP; 114 | if it is 1, then the count is VAR. The opcode number is given 115 | in the bottom 5 bits. 116 |
117 | 118 |In extended form, the operand count is VAR. The opcode number 120 | is given in a second opcode byte. 121 |
122 | 123 |Next, the types of the operands are specified.
125 | 126 |In short form, bits 4 and 5 of the opcode give the type.
128 | 129 |In long form, bit 6 of the opcode gives the type of 131 | the first operand, bit 5 of the second. A value of 0 means a small 132 | constant and 1 means a variable. (If a 2OP instruction needs a 133 | large constant as operand, then it should be assembled in variable 134 | rather than long form.) 135 |
136 | 137 |In variable or extended forms, a byte of 4 operand types is 139 | given next. This contains 4 2-bit fields: bits 6 and 7 are the first 140 | field, bits 0 and 1 the fourth. The values are operand types as above. 141 | Once one type has been given as 'omitted', all subsequent ones must 142 | be. Example: $$00101111 means large constant followed by variable 143 | (and no third or fourth opcode). 144 |
145 | 146 |In the special case of the "double variable" VAR opcodes 148 | call_vs2 and 149 | call_vn2 (opcode 150 | numbers 12 and 26), a second byte of types is given, containing the types 151 | for the next four operands. 152 |
153 | 154 | 155 |The operands are given next. Operand counts of 0OP, 1OP or 2OP 157 | require 0, 1 or 2 operands to be given, respectively. If the count is VAR, 158 | there must be as many operands as there were types other than 'omitted'. 159 |
160 | 161 |Note that only call_vs2 and 163 | call_vn2 can have more than 4 164 | operands, and no instruction can have more than 8. 165 |
166 | 167 |Opcode operands are always evaluated from first to last - this order is 169 | important when the stack pointer appears as an argument. Thus
170 |@sub sp sp -> i;171 |
subtracts the second-from-top stack item from the topmost 172 | stack item. 173 |
174 | 175 | 176 |"Store" instructions return a value: e.g., 178 | mul multiplies 179 | its two operands together. Such instructions must be followed by a 180 | single byte giving the variable number of where to put the result. 181 |
182 | 183 |Instructions which test a condition are called "branch" 185 | instructions. The branch information is stored in one or two bytes, 186 | indicating what to do with the result of the test. If bit 7 of 187 | the first byte is 0, a branch occurs when the condition was false; 188 | if 1, then branch is on true. If bit 6 is set, then the branch 189 | occupies 1 byte only, and the "offset" is in the range 0 to 63, 190 | given in the bottom 6 bits. If bit 6 is clear, then the offset is 191 | a signed 14-bit number given in bits 0 to 5 of the first byte 192 | followed by all 8 of the second. 193 |
194 | 195 |An offset of 0 means "return false from the current 197 | routine", and 1 means "return true from the current routine". 198 |
199 | 200 |Otherwise, a branch moves execution to the instruction at 202 | address 203 |
204 |205 | Address after branch data + Offset - 2. 206 |207 | 208 | 209 |
Two opcodes, print and 211 | print_ret, are followed 212 | by a text string. This is stored according to the usual rules: in particular 213 | execution continues after the last 2-byte word of text (the one with top bit 214 | set). 215 |
216 | 217 |Some opcodes have type VAR only because the available codes for 221 | the other types had run out; print_char, 222 | for instance. Others, especially call, 223 | need the flexibility to have between 1 and 4 operands. 224 |
225 | 226 |The Inform assembler can assemble branches in either form, though 227 | the programmer should always use long form unless there's a good 228 | reason. Inform automatically optimises branch statements so as to 229 | force as many of them as possible into short form. (This optimisation 230 | will happen to branches written by hand in assembler as well as 231 | to branches compiled by Inform.) 232 |
233 | 234 |The disassembler Txd numbers locals from 0 to 14 and globals from 235 | 0 to 239 in its output (corresponding to variable numbers 1 to 15, and 236 | 16 to 255, respectively). 237 |
238 | 239 |The branch formula is sensible because in the natural implementation, 240 | the program counter is at the address after the branch data when the branch 241 | takes place: thus it can be regarded as 242 |
243 | 244 |245 | PC = PC + Offset - 2. 246 |247 | 248 |
If the rule were simply "add the offset" then, since the offset couldn't 249 | be 0 or 1 (because of the return-false and return-true values), we would 250 | never be able to skip past a 1-byte instruction (say, a 0OP like 251 | quit), or specify the 252 | branch "don't branch at all" (sometimes useful to ignore the result of 253 | the test altogether). Subtracting 2 means that the only effects we can't 254 | achieve are 255 |
256 | 257 |258 | PC = PC - 1 and PC = PC - 2 259 |260 | 261 |
and we would never want these anyway, since they would put the program 262 | counter somewhere back inside the same instruction, with horrid 263 | consequences. 264 |
265 | 266 |Briefly, the first byte of an instruction can be decoded 271 | using the following table: 272 |
273 | 274 |275 | $00 -- $1f long 2OP small constant, small constant 276 | $20 -- $3f long 2OP small constant, variable 277 | $40 -- $5f long 2OP variable, small constant 278 | $60 -- $7f long 2OP variable, variable 279 | $80 -- $8f short 1OP large constant 280 | $90 -- $9f short 1OP small constant 281 | $a0 -- $af short 1OP variable 282 | $b0 -- $bf short 0OP 283 | except $be extended opcode given in next byte 284 | $c0 -- $df variable 2OP (operand types in next byte) 285 | $e0 -- $ff variable VAR (operand types in next byte(s)) 286 |287 | 288 |
Here is an example disassembly:
289 | 290 |291 | @inc_chk c 0 label; 05 02 00 d4 292 | long form; count 2OP; opcode number 5; operands: 293 | 02 small constant (referring to variable c) 294 | 00 small constant 0 295 | branch if true: 1-byte offset, 20 (since label is 296 | 18 bytes forward from here). 297 | @print "Hello.^"; b2 11 aa 46 34 16 45 9c a5 298 | short form; count 0OP. 299 | literal string, Z-chars: 4 13 10 17 17 20 5 18 5 7 5 5. 300 | @mul 1000 c -> sp; d6 2f 03 e8 02 00 301 | variable form; count 2OP; opcode number 22; operands: 302 | 03 e8 long constant (1000 decimal) 303 | 02 variable c 304 | store result to stack pointer (var number 00). 305 | @call_1n Message; 8f 01 56 306 | short form; count 1OP; opcode number 15; operand: 307 | 01 56 long constant (packed address of routine) 308 | .label; 309 |310 | 311 |
314 | Contents / 315 | Preface / 316 | Overview 317 |
318 | 319 |Section 320 | 1 / 2 / 321 | 3 / 4 / 322 | 5 / 6 / 323 | 7 / 8 / 324 | 9 / 10 / 325 | 11 / 12 / 326 | 13 / 14 / 327 | 15 / 16 328 |
329 | 330 |Appendix 331 | A / B / 332 | C / D / 333 | E / F 334 |
335 | 336 |
13 |
14 | 5.1 Start position / 19 | 5.2 Header / 20 | 5.3 First instruction / 21 | 5.4 Main routine (V6) / 22 | 5.5 Initial execution point (other versions) 23 |
24 |A routine is required to begin at an address in memory which 29 | can be represented by a packed address (for instance, in Version 5 30 | it must occur at a byte address which is divisible by 4). 31 |
32 | 33 |A routine begins with one byte indicating the number of local 35 | variables it has (between 0 and 15 inclusive). 36 |
37 | 38 |In Versions 1 to 4, that number of 2-byte words follows, 40 | giving initial values for these local variables. In Versions 5 and 41 | later, the initial values are all zero. 42 |
43 | 44 |Execution of instructions begins from the byte after this 46 | header information. There is no formal 'end-marker' for a routine 47 | (it is simply assumed that execution eventually results in a return 48 | taking place). 49 |
50 | 51 |In Version 6, there is a "main" routine (whose packed address 53 | is stored in the word at $06 in the header) called when the game 54 | starts up. It is illegal to return from this routine. 55 |
56 | 57 |In all other Versions, the word at $06 contains the 59 | byte address of the first instruction to execute. The Z-machine 60 | starts in an environment with no local variables from which, again, 61 | a return is illegal. 62 |
63 | 64 |Note that it is permissible for a routine to be in dynamic memory. 68 | Marnix Klooster suggests this might be used for compiling code at 69 | run time! 70 |
71 | 72 |In Versions 3 and 4, Inform always stores 0 as the initial values 73 | for local variables. 74 |
75 | 76 |79 | Contents / 80 | Preface / 81 | Overview 82 |
83 | 84 |Section 85 | 1 / 2 / 86 | 3 / 4 / 87 | 5 / 6 / 88 | 7 / 8 / 89 | 9 / 10 / 90 | 11 / 12 / 91 | 13 / 14 / 92 | 15 / 16 93 |
94 | 95 |Appendix 96 | A / B / 97 | C / D / 98 | E / F 99 |
100 | 101 |
12 |
13 | 6.1 Saved states / 18 | 6.2 Storage of global variables / 19 | 6.3 The stack / 20 | 6.4 Routine calls / 21 | 6.5 Stack frames / 22 | 6.6 User stacks (V6) 23 |
24 |The "state of play" is defined as the following: the contents 28 | of dynamic memory; the contents of the stack; the value of the program 29 | counter (PC), and the "routine call state" (that is, the chain of routines 30 | which have called each other in sequence, and the values of their local 31 | variables). Note that the routine call state, the stack and the PC 32 | must be stored outside the Z-machine memory map, in the interpreter's 33 | private memory. 34 |
35 | 36 |The entire state of play must be stored when the game is saved.
38 | 39 |The format of a saved game file is not specified.
41 | 42 |An internal saved game for "undo" purposes (if there is one) is 44 | not part of the state of play. This is important: if a saved game file also 45 | contained the internal saved game at the time of saving, it would be 46 | impossible to undo the act of restoration. It also prevents internal 47 | saved games from growing larger and larger as they include their 48 | predecessors. 49 |
50 | 51 |It is illegal to save the game (either with 53 | save or 54 | save_undo) during an "interrupt routine" 55 | (one coming about through timed input, sound effect termination or 56 | newline interrupts). Therefore saved games need not store information 57 | capable of restoring such a position. 58 |
59 | 60 |On a "restore" or "undo" (which restores a game saved into 62 | internal memory), the entire state of play is written back except that 63 | 'Flags 2' in the header is preserved. (This information includes whether 64 | the game is being transcribed to printer and whether a fixed-pitch 65 | font is being used.) 66 |
67 | 68 |Before a "restore", an interpreter should check that the 70 | file to be used has been saved from the same game currently being played. 71 | (See remark below.) 72 |
73 | 74 |After a "restore" or "undo", an interpreter should reset 76 | the header values marked Rst in the header table of 77 | § 11. (It should 78 | not be assumed that the game was saved by the same interpreter.) 79 |
80 | 81 |A "restart" is similar: the entire state is restored from the 83 | original story file, and the stack is emptied; but 'Flags 2' is 84 | preserved; and the interpreter should reset the Rst parts of the header. 85 |
86 | 87 |In Versions 5 and later, an interpreter unable to save the game 89 | state into internal memory (for "undo" purposes) must clear bit 4 of 90 | 'Flags 2' in the header. 91 |
92 | 93 |Global variables (variable numbers $10 to $ff) are stored 95 | in a table in the Z-machine's dynamic memory, at a byte address given in 96 | word 6 of the header. The table consists of 240 2-byte words and the 97 | initial values of the global variables are the values initially contained in 98 | the table. (It is legal for a program to alter the table's contents 99 | directly in play, though not for it to change the table's address.) 100 |
101 | 102 |Writing to the stack pointer (variable number $00) pushes a 104 | value onto the stack; reading from it pulls a value off. Stack entries 105 | are 2-byte words as usual. 106 |
107 | 108 |The stack is considered as empty at the start of each routine: 110 | it is illegal to pull values from it unless values have first been pushed 111 | on. 112 |
113 | 114 |The stack is left empty at the end of each routine: when a 116 | return occurs, any values pushed during the routine are thrown away. 117 |
118 | 119 |The absolute minimum standard for stack size is defined as:
121 |let the 'usage' of a routine call be 4 plus the number of local 122 | variables it has. During a game the total of the usages for each 123 | routine in the recursive chain of routines being called, plus the 124 | game's own stack usage, can be assumed to never reach 1024. 125 |
126 | 127 |However, more recent games have required a much larger stack 128 | size than this allows for. It is advised that allow for these games 129 | by having a larger stack size if at all possible. 130 |
131 | 132 |Two examples of modern interpreters with increased stack size are 133 | Windows Frotz, with 32768, 134 | and nfrotz with 61440. 135 |
136 | 137 | 138 |In the seven opcodes that take indirect variable references 140 | (inc, 141 | dec, 142 | inc_chk, 143 | dec_chk, 144 | load, 145 | store, 146 | pull), 147 | an indirect reference to the stack pointer does not push or pull the top 148 | item of the stack - it is read or written in place. 149 |
150 | 151 |Routine calls occur in the following circumstances: when one 153 | of the call... opcodes is executed; in Versions 4 and later, when 154 | timed keyboard input is being monitored; in Versions 5 and later, 155 | when a sound effect finishes; in Version 6, when the game begins 156 | (to call the "main" routine); in Version 6, when a "newline 157 | interrupt" occurs. 158 |
159 | 160 |A routine call may have any number of arguments, from 0 to 162 | 3 (in Versions 1 to 3) or 0 to 7 (Versions 4 and later). All 163 | routines return a value (though sometimes this value is thrown away 164 | afterward: for example by opcodes in the form call_vn*). 165 |
166 | 167 |Routine calls preserve local variables and the stack 169 | (except when the return value is stored in a local variable or onto 170 | the top of the stack). 171 |
172 | 173 |A routine call to packed address 0 is legal: it does nothing 175 | and returns false (0). Otherwise it is illegal to call a packed 176 | address where no routine is present. 177 |
178 | 179 |When a routine is called, its local variables are created 181 | with initial values taken from the routine header (Versions 1 to 182 | 4) or with initial value 0 (Versions 5 and later). Next, the 183 | arguments are written into the local variables (argument 1 into 184 | local 1 and so on). 185 |
186 | 187 |It is legal for there to be more arguments than local 189 | variables (any spare arguments are thrown away) or for there to 190 | be fewer. 191 |
192 | 193 |The return value of a routine can be any Z-machine number. 195 | Returning 'false' means returning 0; returning 'true' means 196 | returning 1. 197 |
198 | 199 |A "stack frame" is an index to the routine call state 201 | (that is, the call-stack of return addresses from routines currently 202 | running, and values of local variables within them). This index 203 | is a Z-machine number. The interpreter must be able to produce the 204 | current value and to set a value further down the call-stack than 205 | the current one, effectively throwing away its recent history 206 | (see catch and 207 | throw). 208 |
209 | 210 |In Version 6, the Z-machine understands a third kind of stack: a 212 | "user stack", which is a table of words in dynamic memory. The first word 213 | in this table always holds the number of spare slots on the stack (so the 214 | initial value is the capacity of the stack). The Z-machine makes no 215 | check on stack under-flow (i.e., pulling more values than were pushed) 216 | which would over-run the length of the table if the program allowed it 217 | to happen. 218 |
219 | 220 |Some interpreters store the whole of dynamic memory to disc as part of their 224 | saved game files, which can make them as much as 45K or so long. A player 225 | making a serious attack on a game may end up wasting a whole megabyte, more 226 | than convenient without a hard disc. A technique invented by Bryan 227 | Scattergood, taken up by most modern interpreters, greatly reduces file size 228 | by only saving bytes of dynamic memory which differ from the initial 229 | state of the game. 230 |
231 | 232 |It is unspecified how an interpreter should decide whether a saved game file 233 | belongs to the game currently being played. It is normal to insist that the 234 | release numbers, serial codes and checksums all match. The Pinfocom 235 | interpreter deliberately checks only the release number, so that saved games 236 | can be exchanged between different editions of 'Seastalker' (presumably 237 | compiled to handle the sonarscope differently). 238 |
239 | 240 |These issues are taken up in great detail in Martin Frost's 241 | Quetzal 242 | standard for saved game files, created to allow different interpreters 243 | to exchange saved games. This Standard doesn't require compliance with 244 | Quetzal, but interpreter writers are urged to consider it: it can only 245 | help authors if players can send them saved games where bugs seem to 246 | have appeared. 247 |
248 | 249 |Given the existence of Quetzal, it is quite 250 | possible that after loading, the game may be running on a different 251 | interpreter to that on which the game started. As a result, it is strongly 252 | advisable for games to recheck any interpreter capabilities (eg Standard version, 253 | unicode support, etc) after loading. 254 |
255 | 256 |The stack is stored in the interpreter's own memory, not anywhere in the 257 | Z-machine. The game program has no direct access to the stack memory or 258 | stack pointer; on some implementations the game's main stack is also used to 259 | store the routine call state (i.e. the game stack and the call-stack are the 260 | same) but this need not be true. 261 |
262 | 263 |The stack size specification guarantees in particular that if the game 264 | itself never uses more than 32 stack entries at once then it can have 265 | a recursive depth of at least 90 routine calls. The author believes 266 | that old Infocom games will all run with a stack size of 512 words. 267 |
268 | 269 |Note that the "state of play" does not include numerous input/output 270 | settings (the current window, cursor position, splitness or otherwise, 271 | which streams are selected, etc.): neither does it include the state 272 | of the random-number generator. (Games with elaborate status lines 273 | must redraw them after a restore has taken place.) 274 |
275 | 276 |Zip provides "undo" but most versions of the ITF 277 | interpreter do not (and save_undo returns 0, unfortunately). 278 | This is probably its greatest 279 | failing. Some Infocom-written interpreters will only provide "undo" to a 280 | game which has bit 4 of 'Flags 2' set: but Inform 5.5 doesn't set this bit, 281 | so modern interpreters should be more generous. 282 |
283 | 284 |287 | Contents / 288 | Preface / 289 | Overview 290 |
291 | 292 |Section 293 | 1 / 2 / 294 | 3 / 4 / 295 | 5 / 6 / 296 | 7 / 8 / 297 | 9 / 10 / 298 | 11 / 12 / 299 | 13 / 14 / 300 | 15 / 16 301 |
302 | 303 |Appendix 304 | A / B / 305 | C / D / 306 | E / F 307 |
308 | 309 |
13 |
14 | 7.1 Output streams / 19 | 7.2 Buffering / 20 | 7.3 Selection (V1 and V2) / 21 | 7.4 Selection (later versions) / 22 | 7.5 Dealing with Unicode or invalid characters / 23 | 7.6 File handling 24 |
25 | 26 |At any given time text is being output through a selection of 30 | "output streams" (possibly none, possibly several at once). 31 |
32 | 33 |Two output streams are common to all Versions: 35 | number 1 (the screen) and 2 (the game transcript, usually printed 36 | to a printer or a file). 37 |
38 |In Versions 1 to 5, the player's input to the 40 | read 41 | opcode should be echoed to output streams 1 and 2 (if stream 2 42 | is active), so that text typed in appears in any transcript. 43 | In Version 6 input should be sent only to stream 1 and it is 44 | the game's responsibility to write to the transcript. 45 |
46 | 47 |In Infocom's Version 4 game 'A Mind Forever Voyaging', 49 | which anticipated a printer rather than a file to receive the 50 | transcript, stream 2 is turned off and on again several times in 51 | quick succession. Thus if an interpreter decides where to send 52 | the transcript by asking the player for a filename, this question 53 | should only be asked once per game session, not every time stream 54 | 2 is selected. 55 |
56 | 57 |Versions 3 and later supply these and two other output streams, 59 | numbered 3 (Z-machine memory) and 4 (a script file of the player's whole 60 | commands and of individual keypresses as read by 61 | read_char). 62 |
63 | 64 |Output stream 3 writes to a table in dynamic memory. When the 66 | stream is selected, the table may have any contents (even the initial 'size' 67 | word will be ignored by the interpreter). While the stream is selected, the 68 | table's contents are unspecified (and a game cannot safely read or write 69 | to it). When the stream is deselected, the initial word of the table holds 70 | the number of characters printed and subsequent bytes hold those characters. 71 | (It is the programmer's responsibility to make the table large enough: the 72 | interpreter performs no overflow checking.) 73 |
74 |In Version 6, the total width of printing (in units) will then be stored in 75 | the word at $30 in the header. The game should not attempt any 76 | operation that will change the width of the font (such as changing from a 77 | proportional to a fixed width font) while output stream 3 is active, and the 78 | interpreter need not store an accurate width of the resulting string if a game does 79 | do this. 80 |
81 | 82 |*** It is possible for stream 3 to be selected while 84 | it is already on. If this happens, the previous table address is 85 | remembered and the previous table is resumed when the new one is 86 | finished. This nesting can reach a depth of up to 16: if stream 3 87 | is opened for a seventeenth time, the interpreter should halt with 88 | an error message. 89 |
90 | 91 |Output stream 3 is unusual in that, while it is selected, no 93 | text is sent to any other output streams which are selected. (However, 94 | they remain selected.) 95 |
96 | 97 |Newlines are written to output stream 3 as ZSCII 13. (A game 99 | should never print_char 100 | the value 10, or any other value which is undefined as a ZSCII output code.) 101 |
102 | 103 |Output stream 4 is unusual in that, when it is selected, 105 | the only text printed to it is that of the player's commands and 106 | keypresses (as read by read_char). 107 | (Each command is written, in one go, when it has been finished. Time delays and mouse-clicks 108 | should ideally be recorded. For suggestions on how this might be achieved, see the 109 | remarks section below. Mistypes and uses of 'delete' are 110 | not written.) 111 |
112 | 113 |On output streams 1 and 2 (only), text printing may be "buffered" 115 | in that new-lines are automatically printed to ensure that no word 116 | (of length less than the width of the screen) spreads across two lines 117 | (if the interpreter is able to control this). 118 | (This process is sometimes called "word-wrapping".) 119 |
120 | 121 |In Versions 1 to 3, buffering is always on. In Versions 4 123 | and later it is on by default (at the start of a game) and a game can 124 | switch it on or off using the buffer_mode 125 | opcode. 126 |
127 | 128 |In Version 6, each of the eight windows has its own "buffering 130 | flag". In Versions 3 to 5, the buffer_mode 131 | applies only to the lower window, and buffering never happens in the upper window. 132 |
133 | 134 |In Versions 1 and 2, output stream 1 is always selected and 136 | stream 2 can be selected or deselected by the game, by setting or clearing 137 | bit 0 of 'Flags 2'. 138 |
139 | 140 |In Versions 3 and later, all four output streams can be selected 142 | or deselected using the 143 | output_stream opcode. In addition, stream 2 144 | can be selected or deselected by setting or clearing bit 0 of 'Flags 2'. 145 | Whichever method is used, the interpreter must ensure that this flag 146 | holds the current status of stream 2. ('A Mind Forever Voyaging' 147 | requires this.) 148 |
149 | 150 |*** 152 | Because of the print_unicode opcode, it is possible for 153 | arbitrary Unicode characters to be sent to the output streams: that is, 154 | for characters which are not in the ZSCII set at all, even in the 155 | "extra characters" range. 156 |
157 | 158 |See § 3.8.5.4 for rules on printing Unicode to stream 1.
160 | 161 |Interpreters are free to use any representation of non-ASCII 163 | Unicode characters in stream 2. For example, they might print 164 | "[1a05]" to signify Unicode character $1a05; or they might be 165 | configurable to write transcript files which conform to any chosen 166 | ISO 8859 set. 167 |
168 | 169 |When printed to stream 3, Unicode characters should be 171 | converted to ZSCII if possible. If this is not possible, a question 172 | mark should be printed to stream 3. 173 |
174 | 175 |Non-ZSCII characters never need to be printed to stream 4.
177 | 178 |*** In Versions 5 and later, the Z-machine has the ability to load 180 | and save files (using optional operands with the 181 | save and 182 | restore 183 | opcodes: these operands were not used in Infocom's Version 5 games, 184 | but I wish to specify them as in Version 5 anyway). 185 |
186 | 187 |*** Filenames have the following format (approximately the MS-DOS 189 | 8.3 rule): one to eight alphanumeric characters, a full stop and zero to 190 | three alphanumeric characters (the "file extension"). 191 |
192 | 193 |The interpreter must convert all filenames to upper case before 195 | use. If no full stop is given, ".AUX" should be appended. 196 |
197 | 198 |Games should avoid the extensions ".INF", ".H", ".Z" 200 | followed by a number or ".SAV": otherwise they may be in danger of erasing 201 | their own object code, source code or saved game files. 202 |
203 | 204 |*** Saved files are not associated with any particular session 206 | of a game. They are not part of the "state of play". 207 |
208 | 209 |*** A game may depend on having up to 32 auxiliary files (with 211 | different names). 212 |
213 | 214 |File-handling errors such as "disc corrupt" and "disc full" 216 | should be reported directly to the player by the interpreter. The error 217 | "file not found" should only cause a failure return code from 218 | restore. 219 |
220 | 221 |Interpreters are allowed to not support access to external files (such as with 223 | output_stream 2, or the extra features of save and restore), or to only support 224 | some methods of access. Interpreters should support these features if possible, 225 | as some games may rely on external files, and in any case transcripts are very 226 | useful for testing, but in some environments such access is not feasible. 227 |
228 | 229 |An attempt by the game to use save or restore in a manner not supported by the 231 | interpreter should simply return 0 as with any failure, and the game should 232 | notice and take appropriate actions. 233 |
234 | 235 |An attempt by the game to use streams to access external files which is not 237 | supported by the interpreter should ideally print a warning to the user that 238 | the functionality is not available, and otherwise do nothing. 239 |
240 | 241 | 242 | 243 | 244 |The ITF interpreter incorrectly applies buffering when printing to 248 | the upper window. 249 |
250 | 251 |Note that the requirement in § 252 | 253 | 7.1.2.1.1, that usages of stream 3 can be 254 | 'nested', is new in Standard 1.0. This is potentially important for 255 | Inform games, as stream 3 is often used to examine text before printing, 256 | for instance to choose between the articles "a" and "an" in front 257 | of an object name. But the process of printing an object name may 258 | itself require a usage of stream 3, and so on. 259 |
260 | 261 |An ambiguous point about output stream 4 is whether it should contain 262 | the answers to interpreter questions like "what file name should your 263 | saved game have?": it can actually be quite useful to be able to include 264 | such answers in test script files. (When running a long script, I often 265 | save the game at several places during it, in order to save time in 266 | re-running passages.) 267 |
268 | 269 |An interpreter should be able to write time delays (for timed input), 270 | accented characters or mouse clicks into stream 4 (i.e., to a script file). 271 | One possible style to record this information might be: 272 |
273 |274 | take lamp an ordinary command 275 | turn it on.[154] command, full stop, then keypad 9 276 | (which might abbreviate for NE) 277 | look unde[0] timed out input 278 | look under the rock the same input continuing 279 | [254][10][6] mouse-click at (10,6) 280 |281 | 282 |
A typical auxiliary file might be one containing the player's preferred 283 | choices. This would be created when he first changed any of the default 284 | settings, and loaded (if present) whenever the game started up. 285 |
286 | 287 |290 | Contents / 291 | Preface / 292 | Overview 293 |
294 | 295 |Section 296 | 1 / 2 / 297 | 3 / 4 / 298 | 5 / 6 / 299 | 7 / 8 / 300 | 9 / 10 / 301 | 11 / 12 / 302 | 13 / 14 / 303 | 15 / 16 304 |
305 | 306 |Appendix 307 | A / B / 308 | C / D / 309 | E / F 310 |
311 | 312 |
13 |
14 | 9.1 Sound effects / 19 | 9.2 Numbering of / 20 | 9.3 Volume / 21 | 9.4 Sound playing autonymously 22 |
23 | 24 |Some games, from Version 3 onward, have sound effects attached. 28 | These are not stored in the story files (or the Z-machine) itself, 29 | and the interpreter is simply expected to know where to find them. 30 | Other games have only one sound effect, usable in a much more restricted 31 | way: a beep or bell sound, which we shall call a "bleep". 32 |
33 | 34 |In Version 6, the interpreter should set bit 5 of 'Flags 1' 36 | if it can provide sound effects beyond a bleep. 37 |
38 | 39 |In Version 5 and later, a game should have bit 7 of 'Flags 2' 41 | set in its story file if it wants to use sound effects beyond a bleep. 42 | The interpreter should then clear this bit if it cannot oblige. 43 |
44 | 45 | 46 |Sound effects are numbered upwards from 1. Number 1 is a 48 | high-pitched bleep, number 2 a low-pitched one and effects from 3 upward 49 | are supplied by the interpreter somehow for the particular game in 50 | question. 51 |
52 | 53 |Sound effects (other than bleeps) can be played at any volume 55 | level from 1 to 8 (8 being loudest of these). The volume level -1 56 | should be implemented as "loudest possible". 57 |
58 | 59 | 60 |Bleeps are immediate and brief. Other sound effects take place 62 | in the background, while normal operation of the Z-machine is going on. 63 | Control is via the sound_effect opcode, allowing the game to prepare, 64 | start, stop or finish with an effect. 65 |
66 | 67 |The game may (but need not) "prepare" a sound effect before 69 | use. This would indicate to the interpreter that the game intends 70 | to use the effect soon: an interpreter might act on this information by 71 | loading the sampled sound off disc and into a memory cache. 72 |
73 | 74 |A sound effect (other than a bleep) can then be "stopped" or 76 | "started". Only one sound effect is playing at any given time, and 77 | starting a new sound effect automatically stops any current one. 78 |
79 | 80 |In Versions 5 and later, a sound effect may repeat any specified 82 | number of times, or repeat forever (until stopped). 83 |
84 | 85 |Eventually, though, if it has not been stopped, it may end by itself. 87 | A routine (specified at start time) can then be called. The intention is that 88 | this routine may implement effects such as fading in and out, by replaying 89 | the sound effect at a different volume. (A game should not place any important 90 | code in such a routine.) The routine is only called when the sound has played the requested 91 | number of times. If manually stopped or interrupted by another sound, the 92 | routine is not called. 93 |
94 | 95 |The game may, but need not, explicitly "finish with" 97 | any sound effect which is not likely to occur again for a while: 98 | the interpreter can then throw it out of memory. 99 |
100 | 101 |The safest way an Inform program can try to produce a bleep is by 105 | executing @sound_effect 1. Some ports of Zip believe that the 106 | first operand of this is the number of bleeps to make (so that 107 | @sound_effect 2 bleeps twice), but this is incorrect. 108 |
109 | 110 |Several Infocom games bleep (using sound_effect with only one 111 | operand, always equal to 1 or 2). Two provided sampled sound effects 112 | but did not bleep: 'The Lurking Horror' and 'Sherlock'. 113 | Their story files contain the following usages of sound_effect: 114 |
115 | 116 |117 | sound_effect number 2 volume (in TLH) 118 | sound_effect number 2 volume/repeats function (in Sherlock) 119 | sound_effect 0 3 120 | sound_effect number 3 121 | sound_effect 0 4 122 |123 | 124 |
except that, probably due to a bug in its own code, 'TLH' can also 125 | generate 126 |
127 | 128 |129 | sound_effect 4 8 130 | sound_effect 4095 2 15 131 |132 | 133 |
A further difficulty with 'TLH' is that it assumes the interpreter is 134 | as slow as Infocom's Amiga interpreter was: it fires off several sound 135 | effects in one game round, assuming there will be time for it to play 136 | most of each one. To simulate this, sound_effect must be rewritten 137 | to pause sometimes: 138 |
139 | 140 |if a new sound effect is begun while there is still one 141 | playing which was started since the last keyboard input, 142 | then wait until that earlier one finishes one cycle before 143 | replacing it with the new sound effect. 144 |
145 | 146 |Infocom's MS-DOS interpreters for V4 to V6 set bit 5 of 'Flags 1' in 147 | all circumstances (i.e., whether or not sound effects are available). 148 | This would be incorrect behaviour for a standard interpreter. 149 |
150 | 151 |Infocom implemented sound effects differently on different machines. 152 | The format of Infocom's shipped sound effects files has been 153 | documented by Stefan Jokisch and his notes are available from 154 | the Interactive Fiction Archive. 155 |
156 | 157 |However, modern interpreters are strong encouraged to support Andrew Plotkin's 158 | Blorb format, which is a more modern way to make sound effects 159 | available to newer games. Blorb files have been made available for the Infocom 160 | sound effects, so that modern interpreters need no longer support the Infocom format. 161 |
162 | 163 |The Blorb specification contains some revisions to sound features, which are not 164 | formally part of this Standard. Future versions of the Standard will likely 165 | incorporate these revisions. In the meantime, Standard 1.0 compliant interpreters 166 | which support Blorb should follow those revisions, rather than the precise letter 167 | of this Standard. We apologise for the ugliness. 168 |
169 | 170 |When using Blorb resources, the default interpreter behaviour (unless over- 173 | ridden by the player) should be for samples played at maximum volume (64), in 174 | one channel of a SONG or MOD played at volume 8, to be of equal volume to 175 | samples played at maximum volume (8) as an effect. This will be the natural 176 | behaviour if effects use one physical channel and MODs/SONGs use four 177 | physical channels. 178 |
179 | 180 |Ideally, a sound played at volume n in a SONG played at volume m should 181 | sound the same as when played as an effect at volume n*m/64. This mandates 182 | that the volume scale for effects be equivalent to the scale defined for 183 | samples in the MOD specification. 184 |
185 | 186 |If multi-channel effects are used, the overall volume should be independent 187 | of the number of channels used in the sound. Thus a stereo AIFF containing 188 | the same samples for left and right should sound as loud as a mono AIFF 189 | containing the same data. This will need adjustment of volume if stereo AIFFs 190 | use two physical channels and mono AIFFs use one. No adjustment would be 191 | required if an interpreter reduced all AIFFs to mono. 192 |
193 | 194 | 195 |198 | Contents / 199 | Preface / 200 | Overview 201 |
202 | 203 |Section 204 | 1 / 2 / 205 | 3 / 4 / 206 | 5 / 6 / 207 | 7 / 8 / 208 | 9 / 10 / 209 | 11 / 12 / 210 | 13 / 14 / 211 | 15 / 16 212 |
213 | 214 |Appendix 215 | A / B / 216 | C / D / 217 | E / F 218 |
219 | 220 |
12 |
13 | 10.1 Keyboard only in V1 / 18 | 10.2 Input streams / 19 | 10.3 Mouse support / 20 | 10.4 Menu support / 21 | 10.5 Terminating characters and timed input / 22 | 10.6 Single keypresses / 23 | 10.7 Reading ZSCII from the keyboard 24 |
25 | 26 |In Versions 1 and 2, the player's commands can only be 30 | drawn from the keyboard. 31 |
32 | 33 |In Versions 3 and later, the player's keypresses are drawn 35 | from the current "input stream". There are two input streams: 36 | numbered 0 (the keyboard) and 1 (a file containing commands). 37 | Other inputs (mouse clicks or menu selections), if available, 38 | are also implemented as keypresses (see below). 39 |
40 | 41 |The format of a file containing commands must be the same as 43 | that written in output stream 4. 44 |
45 | 46 |The game can change the current input stream itself, using 48 | the opcode input_stream. It has no way of finding out which input 49 | stream is currently in use. An interpreter is free to change the 50 | input stream whenever it likes (e.g. at the player's request) or, 51 | indeed, to run the entire game under input stream 1 (for testing 52 | purposes). 53 |
54 | 55 |When input stream 1 is first selected, the interpreter may 57 | use any method of choosing a file name for the file of commands. (Good 58 | practice is to use the same conventions as when choosing a filename 59 | for output to stream 4.) 60 |
61 | 62 |When the the current stream is stream 1, the interpreter 64 | should not hold up long passages of text (by printing "[MORE]" 65 | and waiting for a keypress, for instance). 66 |
67 | 68 |Mouse support is optional but can be provided in Versions 5 and 70 | later. 71 |
72 | 73 |In a game which wishes to use the mouse, bit 5 of 'Flags 2' 75 | in the header should be set in the story file. If it wishes to read 76 | the mouse position after clicks, it must provide at least the first 77 | two words of a header extension table. (Note that Inform 6.12 and 78 | later always provide a header extension table at least this large, 79 | but Inform 6.11 and earlier never provide an extension table at all.) 80 |
81 | 82 |If the interpreter cannot offer mouse support, then it 84 | should clear bit 5 of 'Flags 2' to signal this to the game. 85 |
86 | 87 |Whenever a mouse click takes place (and provided the header 89 | extension table exists and contains at least 2 words) the interpreter 90 | should update the coordinates as follows: 91 |
92 | 93 |94 | Word 1: x coordinate where click took place 95 | Word 2: y coordinate where click took place 96 |97 | 98 |
The mouse is presumed to have between 0 and 16 buttons. 100 | The state of these buttons can be read by the read_mouse opcode 101 | in Version 6. Otherwise, mouse clicks are treated as keyboard 102 | input codes (see below). 103 |
104 | 105 |In Version 6, the mouse can either be free or constrained 107 | to one of the 8 windows: if so, clicks outside the 'mouse window' 108 | must be ignored, and the interpreter is at liberty to confine the 109 | mouse's movement to the boundary of its window. 110 |
111 | 112 |Menu support can optionally be provided in Version 6.
114 | 115 |In a game which wishes to use menus, bit 8 of 'Flags 2' 117 | in the header should be set in the story file. 118 |
119 | 120 |If the interpreter cannot offer menu support, then it 122 | should clear bit 8 of 'Flags 2' to signal this to the game. 123 |
124 | 125 |Menus are numbered from 0 upwards. 0, 1 and 2 are reserved for 127 | the interpreter to manage (this system has only been implemented on 128 | the Macintosh, wherein 0 is the Apple menu, 1 the File menu and 2 the 129 | Edit menu). Menus numbered 3 and upwards can be created or removed with 130 | the make_menu opcode. 131 |
132 | 133 |Menu selection is reported to the game as a keypress 135 | (see below). Details of what selection has been made are read with 136 | read_mouse. 137 |
138 | 139 |Whole commands are read from the input stream using the read 141 | opcode. (Note that this has two different internal names in Inform, 142 | sread for Versions 1 to 4 and aread subsequently.) 143 |
144 | 145 |In Versions 1 to 3, the interpreter must redisplay the status 147 | line before it begins accepting input. 148 |
149 | 150 |Commands are normally terminated by a new-line (a carriage 152 | return or a line feed as appropriate for the machine's keyboard or 153 | file format). 154 |
155 | 156 |In Versions 5 and later, the game may provide a 158 | "terminating characters table" by giving its byte address in 159 | the word at $2e in the header. This table is a zero-terminated 160 | list of input character codes which cause aread to finish the 161 | command (in addition to new-line). Only function key codes are 162 | permitted: these are defined as those between 129 and 154 163 | inclusive, together with 252, 253 and 254. The special value 164 | 255 means "any function key code is terminating". 165 |
166 | 167 |*** 169 | In Versions 4 and later, an interpreter should ideally 170 | be able to time input and to call a (game) routine at periodic 171 | intervals: see the read opcode. If it is able to do this, it 172 | should set bit 7 of 'Flags 1' in the header. 173 |
174 | 175 |In Versions 4 and later, individual characters can be read 177 | from the current input stream, using read_char. Again, the interpreter 178 | should ideally be able to time input and to call a (game) routine at 179 | periodic intervals. If it is able to do this, it should set bit 7 of 'Flags 180 | 1' in the header. 181 |
182 | 183 |The only characters which can be read from the keyboard 185 | are ZSCII characters defined for input (see § 3). 186 |
187 | 188 |Every ZSCII character defined for input can be returned 190 | by read_char. 191 |
192 | 193 |Only ZSCII characters defined for both input and output can 195 | be stored in the text buffer supplied to the read opcode. 196 |
197 | 198 |The "escape" code is optional: that is, an interpreter 200 | need not provide an escape key. (The Inform library clears and 201 | quits menus if this code is returned to read_char.) 202 |
203 | 204 |Menus in 'Beyond Zork' define cursor up and cursor down as terminating 208 | characters, and make use of read in the upper window. 209 |
210 | 211 |Mouse co-ordinates, whether returned by read_mouse or written 212 | into the header during input, are always relative to the top of the display 213 | at (1,1), regardless of the position of the current mouse window. 214 |
215 | 216 |read_mouse is realtime. When called it must read the current mouse 217 | location, whether or not the mouse is inside the current mouse window. Interpreters 218 | are allowed to show positions and button states outside the 219 | Z-machine screen if the pointer is outside the interpreter's own user 220 | interface (using negative values if needed). 221 |
222 | 223 |Programs must be prepared to cope with this. For example in a painting 224 | program you might want to ignore all buttons down outside the screen. When 225 | dragging something you might want to keep trying to follow the pointer, even 226 | outside the screen, until the buttons are released. 227 |
228 | 229 |Interpreters may constrain the pointer to the screen as long as buttons are 230 | held down - this might aid dragging operations - although this is not 231 | required. 232 |
233 | 234 |237 | Contents / 238 | Preface / 239 | Overview 240 |
241 | 242 |Section 243 | 1 / 2 / 244 | 3 / 4 / 245 | 5 / 6 / 246 | 7 / 8 / 247 | 9 / 10 / 248 | 11 / 12 / 249 | 13 / 14 / 250 | 15 / 16 251 |
252 | 253 |Appendix 254 | A / B / 255 | C / D / 256 | E / F 257 |
258 | 259 |
13 |
14 | The header table summarises those locations in the Z-machine's 18 | header which an interpreter must deal with. (For further notes on 19 | traditional usage, see Appendix B.) 20 | "Hex" means the address, in hexadecimal; 21 | "Len" means the length in bytes; 22 | "V" the earliest Version to which the rule is applicable; 23 | "Dyn" means that the byte or bit may legally be changed by the game 24 | during play; "Int" means that the interpreter may change it; "Rst" 25 | means that the interpreter must set it correctly after loading the game, 26 | after a restore or after a restart. 27 |
28 | 29 |Where Flags occupy two bytes, "Bit 0" refers to bit 0 of the second byte, "Bit 8" refers to bit 0 of the first byte. 30 |
31 | 32 || Hex | Len | V | Dyn | 35 |Int | Rst | Contents | 36 |
|---|---|---|---|---|---|---|
| 0 | 1 | 1 | Version number (1 to 8) | 38 ||||
| 1 | 1 | 3 | Flags 1 (in Versions 1 to 3): | |||
| Bit 1: Status line type: 0=score/turns, 1=hours:mins | ||||||
| 2: Story file split across two discs? | ||||||
| * | * | 4: Status line not available? | ||||
| * | * | 5: Screen-splitting available? | ||||
| * | * | 6: Is a variable-pitch font the default? | ||||
| 4 | Flags 1 (from Version 4): | |||||
| 5 | * | * | Bit 0: Colours available? | |||
| 6 | * | * | 1: Picture displaying available? | |||
| 4 | * | * | 2: Boldface available? | |||
| 4 | * | * | 3: Italic available? | |||
| 4 | * | * | 51 |4: Fixed-space style available? | 52 ||||
| 6 | * | * | 5: Sound effects available? | |||
| 4 | * | * | 7: Timed keyboard input available? | |||
| 4 | 2 | 1 | Base of high memory (byte address) | |||
| 6 | 2 | 1 | Initial value of program counter (byte address) | |||
| 2 | 6 | Packed address of initial "main" routine | ||||
| 8 | 2 | 1 | Location of dictionary (byte address) | |||
| A | 2 | 1 | Location of object table (byte address) | |||
| C | 2 | 1 | Location of global variables table (byte address) | |||
| E | 2 | 1 | Base of static memory (byte address) | |||
| 10 | 2 | 1 | Flags 2: | |||
| 1 | * | * | * | Bit 0: Set when transcripting is on | ||
| 3 | * | * | 67 |1: Game sets to force printing in fixed-pitch font | 68 ||||
| 6 | * | * | 71 | | 2: Int sets to request screen redraw: game clears when it complies with this. | 72 |||
| 5 | * | * | 3: If set, game wants to use pictures | |||
| 5 | * | * | 4: If set, game wants to use the UNDO opcodes | |||
| 5 | * | * | 5: If set, game wants to use a mouse | |||
| 5 | 6: If set, game wants to use colours | |||||
| 5 | * | * | 7: If set, game wants to use sound effects | |||
| 6 | * | * | 8: If set, game wants to use menus | |||
| 82 | | (For bits 3,4,5,7 and 8, Int clears again if it cannot provide the requested effect.) | 83 ||||||
| 18 | 2 | 2 | Location of abbreviations table (byte address) | |||
| 1A | 2 | 3+ | Length of file (see note) | |||
| 1C | 2 | 3+ | Checksum of file | |||
| 1E | 1 | 4 | * | * | Interpreter number | |
| 1F | 1 | 4 | * | * | Interpreter version | |
| 20 | 1 | 4 | * | * | Screen height (lines) | |
| 21 | 1 | 4 | * | * | Screen width (characters) | |
| 22 | 2 | 5 | * | * | Screen width in units | |
| 24 | 2 | 5 | * | * | Screen height in units | |
| 26 | 1 | 5 | * | * | Font width in units (defined as width of a '0') | |
| 6 | * | * | Font height in units | |||
| 27 | 1 | 5 | * | * | Font height in units | |
| 6 | * | * | Font width in units (defined as width of a '0') | |||
| 28 | 2 | 6 | Routines offset (divided by 8) | |||
| 2A | 2 | 6 | Static strings offset (divided by 8) | |||
| 2C | 2 | 5 | * | * | Default background colour | |
| 2D | 2 | 5 | * | * | Default foreground colour | |
| 2E | 2 | 5 | Address of terminating characters table (bytes) | |||
| 30 | 2 | 6 | * | Total width in pixels of text sent to output stream 3 | ||
| 32 | 2 | 1 | * | * | Standard revision number | |
| 34 | 2 | 5 | Alphabet table address (bytes), or 0 for default | |||
| 36 | 2 | 5 | Header extension table address (bytes) |
Some early Version 3 files do not contain length and checksum 111 | data, hence the notation 3+. 112 |
113 | 114 |It is illegal for a game to alter those 116 | fields not marked as "Dyn". An interpreter is therefore free to 117 | store values of such fields in its own variables. 118 |
119 | 120 |The state of the transcription bit 122 | (bit 0 of Flags 2) can 123 | be changed directly by the game to turn transcribing on or off 124 | (see § 7.3, § 7.4). The interpreter must also alter it if 125 | stream 2 is turned on or off, to ensure that the bit always 126 | reflects the true state of transcribing. Note that the 127 | interpreter ensures that its value survives a restart or restore. 128 |
129 | 130 |Infocom used the interpreter numbers:
132 | 133 |134 | 1 DECSystem-20 5 Atari ST 9 Apple IIc 135 | 2 Apple IIe 6 IBM PC 10 Apple IIgs 136 | 3 Macintosh 7 Commodore 128 11 Tandy Color 137 | 4 Amiga 8 Commodore 64 138 |139 | 140 |
(The DECSystem-20 was Infocom's own in-house mainframe.) An interpreter 141 | should choose the interpreter number most suitable for the machine it 142 | will run on. In Versions up to 5, the main consideration is that the 143 | behaviour of 'Beyond Zork' depends on the interpreter number (in terms 144 | of its usage of the character graphics font). In Version 6, the 145 | decision is more serious, as existing Infocom story files depend 146 | on interpreter number in many ways: moreover, some story files 147 | expect to be run only on the interpreters for a particular machine. 148 | (There are, for instance, specifically Amiga versions.) 149 |
150 | 151 |Interpreter versions are conventionally ASCII codes for 153 | upper-case letters in Versions 4 and 5 (note that Infocom's Version 6 154 | interpreters just store numbers here). 155 |
156 | 157 |Modern games are strongly discouraged from testing the interpreter number or interpreter version 158 | header information for any game-changing behaviour. It is rarely meaningful, and a Standard interpreter 159 | provides many better ways to query the interpreter for information. 160 |
161 | 162 |*** 164 | The use of bit 7 in 'Flags 1' to signal whether timed 165 | input is available is new in this document: see the preface. 166 |
167 | 168 |*** 170 | If an interpreter obeys Revision n.m of this document 171 | perfectly, as far as anyone knows, 172 | then byte $32 should be written with 173 | n and byte $33 with m. 174 | If it is an earlier (non-standard) 175 | interpreter, it should leave these bytes as 0. 176 |
177 | 178 |The file length stored at $1a is actually divided by a constant, 180 | depending on the Version, to make it fit into a header word. This constant 181 | is 2 for Versions 1 to 3, 4 for Versions 4 to 5 or 8 for Versions 6 and 182 | later. 183 |
184 | 185 |The header extension table provides potentially unlimited 187 | room for further header information. It is a table of word entries, 188 | in which the initial word contains the number of words of data to follow. 189 |
190 | 191 |If the interpreter needs to read a word which is beyond the 193 | length of the extension table, or the extension table doesn't exist at 194 | all, then the result is 0. 195 |
196 | 197 |If the interpreter needs to write a word which is beyond the 199 | length of the extension table, or the extension table doesn't exist at 200 | all, then the result is that nothing happens. 201 |
202 | 203 |*** 205 | Words in the header extension table have been allocated 206 | as follows: 207 |
208 | 209 || Word | V | Dyn | Int | 213 |Rst | Contents | 214 |
|---|---|---|---|---|---|
| 0 | 5 | Number of further words in table | |||
| 1 | 5 | * | X-coordinate of mouse after a click | ||
| 2 | 5 | * | Y-coordinate of mouse after a click | ||
| 3 | 5 | Unicode translation table address (optional) |
In the Infocom period, the larger Version 3 story files would 226 | not entirely fit on a single Atari 800 disc (though they would fit 227 | on a single Apple II, or a single PC disc). Atari versions were 228 | therefore made which were identical to the normal ones except for 229 | having Flags 1 bit 2 set, and were divided into the resident part 230 | on one disc and the rest on another. (This discovery was announced 231 | by Stefan Jokisch on 26 August 1997 and sees the end of one of the 232 | very few Z-machine mysteries left when Standard 1.0 was first published.) 233 |
234 | 235 |See the "Infocom fact sheet" for numbers and letters of the known 236 | interpreters shipped by Infocom. Interpreter versions are conventionally 237 | the upper case letters in sequence (A, B, C, ...). At present most ports 238 | of Zip use interpreter number 6, and most of ITF use number 2. 239 |
240 | 241 |The unusual behaviour of 'Beyond Zork' concerns its character graphics: 242 | see the remarks to § 16. 243 |
244 | 245 |The Macintosh story file for 'Zork Zero' erroneously does not set 246 | the pictures bit (Flags 2, bit 3). 247 |
248 | 249 |The bit in the header described as "requesting screen redraw" may be set by 250 | modern interpreters after, for example, resizing the "screen"; games should 251 | ideally redraw the screen if they see this bit set. This will usually mean 252 | the game clears the screen contents and rearranges borders, etc, so the bit 253 | should not be set except when necessary. 254 |
255 | 256 |The (Version 6) sound and picture bits in Flags 1 indicate general 257 | availability of sound and graphics - ie whether the associated opcodes are 258 | available and functional. 259 |
260 | 261 |The bits in Flags 2 should ideally be set reflecting current 262 | availability, rather than general support. In other words, if no Blorb (or 263 | other) resources for this story file have been found, or if the Blorb file 264 | contains no graphics or no sound, the corresponding bits should be cleared. 265 |
266 | 267 |Also, it is recommended that interpreters that would prompt for an auxiliary 268 | Blorb file should do so immediately on start up if any of the "game wants to 269 | use sound/music/graphics" bits are set; this allows the bits to be cleared if 270 | no file is forthcoming, before the game starts execution. The game can then 271 | take appropriate action. 272 |
273 | 274 |277 | Contents / 278 | Preface / 279 | Overview 280 |
281 | 282 |Section 283 | 1 / 2 / 284 | 3 / 4 / 285 | 5 / 6 / 286 | 7 / 8 / 287 | 9 / 10 / 288 | 11 / 12 / 289 | 13 / 14 / 290 | 15 / 16 291 |
292 | 293 |Appendix 294 | A / B / 295 | C / D / 296 | E / F 297 |
298 | 299 |
13 |
14 | 12.1 Storage / 19 | 12.2 Property defaults table / 20 | 12.3 Object tree / 21 | 12.4 Property tables / 22 | 12.5 Well-foundedness of the tree 23 |
24 | 25 |The object table is held in dynamic memory and its byte address 29 | is stored in the word at $0a in the header. (Recall that objects 30 | have flags attached called attributes, numbered from 0 upward, and 31 | variables attached called properties, numbered from 1 upward. An 32 | object need not provide every property.) 33 |
34 | 35 |The table begins with a block known as the property defaults table. 37 | This contains 31 words in Versions 1 to 3 and 63 in Versions 4 and later. 38 | When the game attempts to read the value of property n for an object 39 | which does not provide property n, the n-th entry in this table 40 | is the resulting value. 41 |
42 | 43 |Next is the object tree. Objects are numbered consecutively from 45 | 1 upward, with object number 0 being used to mean "nothing" (though 46 | there is formally no such object). The table consists of a list of 47 | entries, one for each object. 48 |
49 | 50 |In Versions 1 to 3, there are at most 255 objects, each having 52 | a 9-byte entry as follows: 53 |
54 | 55 |56 | the 32 attribute flags parent sibling child properties 57 | ---32 bits in 4 bytes--- ---3 bytes------------------ ---2 bytes-- 58 |59 | 60 |
parent, sibling and child must all hold valid object numbers. 61 | The properties pointer is the byte address of the list of 62 | properties attached to the object. Attributes 0 to 31 are flags 63 | (at any given time, they are either on (1) or off (0)) and are stored topmost 64 | bit first: e.g., attribute 0 is stored in bit 7 of the first byte, 65 | attribute 31 is stored in bit 0 of the fourth. 66 |
67 | 68 |In Version 4 and later, there are at most 65535 objects, each 70 | having a 14-byte entry as follows: 71 |
72 | 73 |74 | the 48 attribute flags parent sibling child properties 75 | ---48 bits in 6 bytes--- ---3 words, i.e. 6 bytes---- ---2 bytes-- 76 |77 | 78 | 79 |
Each object has its own property table. Each of these can be 81 | anywhere in dynamic memory (indeed, a game can legally change an object's 82 | properties table address in play, provided the new address points to 83 | another valid properties table). 84 | The header of a property table is as follows: 85 |
86 | 87 |88 | text-length text of short name of object 89 | -----byte---- --some even number of bytes--- 90 |91 | 92 |
where the text-length 93 | is the number of 2-byte words making up the text, 94 | which is stored in the usual format. (This means that an object's short 95 | name is limited to 765 Z-characters.) After the header, the properties 96 | are listed in descending numerical order. (This order is essential and 97 | is not a matter of convention.) 98 |
99 | 100 |In Versions 1 to 3, each property is stored as a block
102 | 103 |104 | size byte the actual property data 105 | ---between 1 and 8 bytes-- 106 |107 | 108 |
where the size byte is arranged as 32 times the number of data bytes 109 | minus one, plus the property number. A property list is terminated by 110 | a size byte of 0. (It is otherwise illegal for a size byte to be a 111 | multiple of 32.) 112 |
113 | 114 |In Versions 4 and later, a property block instead has the form
116 | 117 |118 | size and number the actual property data 119 | --1 or 2 bytes--- --between 1 and 64 bytes-- 120 |121 | 122 |
The property number occupies the bottom 6 bits of the first size byte.
123 | 124 |If the top bit (bit 7) of the first size byte is set, then there are 126 | two size-and-number bytes as follows. In the first byte, bits 0 to 127 | 5 contain the property number; bit 6 is undetermined (it is clear in 128 | all Infocom or Inform story files); bit 7 is set. In the second byte, 129 | bits 0 to 5 contain the property data length, counting in bytes; 130 | bit 6 is undetermined (it is set in Infocom story files, but clear 131 | in Inform ones); bit 7 is always set. 132 |
133 | 134 |*** 136 | A value of 0 as property data length (in the second 137 | byte) should be interpreted as a length of 64. (Inform can compile 138 | such properties.) 139 |
140 | 141 |If the top bit (bit 7) of the first size byte is clear, then there is 143 | only one size-and-number byte. Bits 0 to 5 contain the property number; 144 | bit 6 is either clear to indicate a property data length of 1, or 145 | set to indicate a length of 2; bit 7 is clear. 146 |
147 | 148 |It is the game's responsibility to keep the object tree 150 | well-founded: the interpreter is not required to check. 151 | "Well-founded" means the following: 152 |
153 | 154 |(a) An object with a sibling also has a parent.
155 | 156 |(b) An object is the parent of exactly those objects 157 | in the sibling list of its child. 158 |
159 | 160 |(c) Each object can be given a level n, such that 161 | parentless objects have level 0 and all children of a level 162 | n object have level n+1. 163 |
164 | 165 |The largest valid object number is not directly stored anywhere 169 | in the Z-machine. Utility programs like Infodump deduce this 170 | number by assuming that, initially, the object entries end where 171 | the first property table begins. 172 |
173 | 174 |Infocom's 'Sherlock' contains a bug making it try to set and 175 | clear attribute 48. 176 |
177 | 178 |The reason why the second property size byte needs to have top bit 179 | set is that the size field must be parsable either forwards or 180 | backwards -- the Z-machine needs to be able to reconstruct the 181 | length of a property given only the address of the first byte 182 | of its data. (There are very many (e.g. 2000) property entries 183 | in a story file, so optimising size into one byte most of the 184 | time is worthwhile.) 185 |
186 | 187 |Bit 6 in the second byte is presently wasted, which is a pity as 188 | it could be used to allow up to 128 bytes of property data. But such 189 | a change would cause Infocom's story files to fail (since they 190 | set this bit, unlike Inform story files). 191 |
192 | 193 |Inform can only construct well-founded object trees as the initial game 194 | state, but it is easy to compile sequences of code like "move red box to 195 | blue box" followed by "move blue box to red box" which leave the object 196 | tree in an ill-founded state. (The Inform library protects the standard 197 | object-movement verbs against this.) 198 |
199 | 200 |203 | Contents / 204 | Preface / 205 | Overview 206 |
207 | 208 |Section 209 | 1 / 2 / 210 | 3 / 4 / 211 | 5 / 6 / 212 | 7 / 8 / 213 | 9 / 10 / 214 | 11 / 12 / 215 | 13 / 14 / 216 | 15 / 16 217 |
218 | 219 |Appendix 220 | A / B / 221 | C / D / 222 | E / F 223 |
224 | 225 |
13 |
14 | 13.1 Storage / 19 | 13.2 Header / 20 | 13.3 Entries (V1 to V3) / 21 | 13.4 Entries (later versions) / 22 | 13.5 Ordering / 23 | 13.6 Lexical analysis 24 |
25 | 26 |The dictionary table is held in static memory and its byte 30 | address is stored in the word at $08 in the header. 31 |
32 | 33 |The table begins with a short header:
35 | 36 |37 | n list of keyboard input codes entry-length number-of-entries 38 | byte ------n bytes----------------- byte 2-byte word 39 |40 | 41 |
The keyboard input codes are "word-separators": typically (and under 42 | Inform mandatorily) these are the ZSCII codes for full stop, comma and 43 | double-quote. Note that a space character (32) should never be a 44 | word-separator. The "entry length" is the length of each word's 45 | entry in the dictionary table. (It must be at least 4 in Versions 46 | 1 to 3, and at least 6 in later Versions.) 47 |
48 | 49 |Note that the word-separators table can only contain codes 51 | which are defined in ZSCII for both input and output. 52 |
53 | 54 |In Versions 1 to 3, each word has an entry in the form
56 | 57 |58 | encoded text of word bytes of data 59 | ------- 4 bytes ------ (entry length-4) bytes 60 |61 | 62 |
The interpreter ignores the bytes of data (presumably the game's parser will 63 | use them). The encoded text contains 6 Z-characters (it is always padded 64 | out with Z-character 5's to make up 4 bytes: see § 3). 65 | The text may include spaces or other word-separators 66 | (though, if so, the interpreter will never match any text to the 67 | dictionary word in question: surprisingly, this can be useful and is 68 | a trick used in the Inform library). 69 |
70 | 71 |In Versions 4 and later, the encoded text has 6 bytes and 73 | always contains 9 Z-characters. 74 |
75 | 76 |The word entries follow immediately after the dictionary header 78 | and must be given in numerical order of the encoded text (when the encoded 79 | text is regarded as a 32 or 48-bit binary number with most-significant 80 | byte first). It must not contain two entries with the same encoded text. 81 |
82 | 83 |Lexical analysis takes place in two circumstances: on request 85 | of a tokenise opcode (in which case it can use any dictionary table 86 | it likes, in the format above) and during acceptance of a game command 87 | (in which case the standard dictionary is used). 88 |
89 | 90 |First, the text is broken up into words. Spaces divide up 92 | words and are otherwise ignored. Word separators also divide words, 93 | but each one of them is considered a word in its own right. Thus, 94 | the erratically-spaced text "fred,go fishing" is divided into four 95 | words: 96 |
97 | 98 |99 | fred / , / go / fishing 100 |101 | 102 |
Each word is then encoded as a Z-machine string in 104 | dictionary form, and searched for in the dictionary. 105 |
106 | 107 |A "parse table" is then written, recording the number of 109 | words, the length and position of each word and the dictionary 110 | address of each word which is recognised. For the format, see the 111 | read opcode. 112 |
113 |Usually (under Inform, mandatorily) there are three bytes of data 117 | in the word entries, so that dictionary entry lengths are 7 and 9 118 | in the early and late Z-machine, respectively. 119 |
120 | 121 |It is essential that dictionary entries are in numerical order of the 122 | bytes of encrypted text so that interpreters can search the dictionary 123 | efficiently (e.g. by a binary-chop algorithm). Because the letters in 124 | A0 are in alphabetical order, because the bits are ordered in the right 125 | way and because the pad character 5 is less than the values for the 126 | letters, the numerical ordering corresponds to normal English alphabetical 127 | order for ordinary words. (For instance "an" comes before 128 | "anaconda".) 129 |
130 | 131 |Both Infocom and Inform-compiled games contain words whose initial 132 | character is not a letter (for instance, "#record"). 133 |
134 | 135 |Linards Ticmanis reports that some of Infocom's interpreters convert 136 | question marks to spaces before lexical analysis. This is not 137 | Standard behaviour. (Thus, typing "What is a grue?" into 'Zork I' 138 | no longer works: the player must type "What is a grue" instead.) 139 |
140 | 141 |144 | Contents / 145 | Preface / 146 | Overview 147 |
148 | 149 |Section 150 | 1 / 2 / 151 | 3 / 4 / 152 | 5 / 6 / 153 | 7 / 8 / 154 | 9 / 10 / 155 | 11 / 12 / 156 | 13 / 14 / 157 | 15 / 16 158 |
159 | 160 |Appendix 161 | A / B / 162 | C / D / 163 | E / F 164 |
165 | 166 |
12 |
13 | The following table of 8x8 bitmaps gives a suitable appearance 17 | for font 3. The font must have a fixed pitch and characters must be printed 18 | immediately next to each other in all four directions. 19 |
20 |
21 | 32( ): 76543210 33(!): 76543210 34("): 76543210 35(#): 76543210
22 | 0 0 0 0 #
23 | 1 1 1 1 #
24 | 2 2 # 2 # 2 #
25 | 3 3 ## 3 ## 3 #
26 | 4 4####### 4####### 4 #
27 | 5 5 ## 5 ## 5 #
28 | 6 6 # 6 # 6 #
29 | 7 7 7 7#
30 | 36($): 76543210 37(%): 76543210 38(&): 76543210 39('): 76543210
31 | 0# 0 0 0
32 | 1 # 1 1 1
33 | 2 # 2 2 2
34 | 3 # 3 3 3########
35 | 4 # 4 4######## 4
36 | 5 # 5 5 5
37 | 6 # 6 6 6
38 | 7 # 7 7 7
39 | 40((): 76543210 41()): 76543210 42(*): 76543210 43(+): 76543210
40 | 0 # 0 # 0 # 0
41 | 1 # 1 # 1 # 1
42 | 2 # 2 # 2 # 2
43 | 3 # 3 # 3######## 3
44 | 4 # 4 # 4 4########
45 | 5 # 5 # 5 5 #
46 | 6 # 6 # 6 6 #
47 | 7 # 7 # 7 7 #
48 | 44(,): 76543210 45(-): 76543210 46(.): 76543210 47(/): 76543210
49 | 0 # 0 # 0 # 0
50 | 1 # 1 # 1 # 1
51 | 2 # 2 # 2 # 2
52 | 3 # 3 # 3 # 3 #####
53 | 4 #### 4#### 4 ##### 4 #
54 | 5 # 5 # 5 5 #
55 | 6 # 6 # 6 6 #
56 | 7 # 7 # 7 7 #
57 |
58 | 59 | 48(0): 76543210 49(1): 76543210 50(2): 76543210 51(3): 76543210 60 | 0 0 # 0 # 0# 61 | 1 1 # 1 # 1 # 62 | 2 2 # 2 # 2 # 63 | 3##### 3 # 3 # 3 ##### 64 | 4 # 4##### 4 ##### 4 # 65 | 5 # 5 5 # 5 # 66 | 6 # 6 6 # 6 # 67 | 7 # 7 7# 7 # 68 | 52(4): 76543210 53(5): 76543210 54(6): 76543210 55(7): 76543210 69 | 0 # 0 # 0######## 0######## 70 | 1 # 1 # 1######## 1######## 71 | 2 # 2 # 2######## 2######## 72 | 3##### 3 # 3######## 3######## 73 | 4 # 4##### 4######## 4######## 74 | 5 # 5 # 5######## 5 75 | 6 # 6 # 6######## 6 76 | 7 # 7 # 7######## 7 77 | 56(8): 76543210 57(9): 76543210 58(:): 76543210 59(;): 76543210 78 | 0 0##### 0 ##### 0 # 79 | 1 1##### 1 ##### 1 # 80 | 2 2##### 2 ##### 2 # 81 | 3######## 3##### 3 ##### 3######## 82 | 4######## 4##### 4 ##### 4######## 83 | 5######## 5##### 5 ##### 5######## 84 | 6######## 6##### 6 ##### 6######## 85 | 7######## 7##### 7 ##### 7######## 86 | 60(<): 76543210 61(=): 76543210 62(>): 76543210 63(?): 76543210 87 | 0######## 0##### 0 ##### 0 ##### 88 | 1######## 1##### 1 ##### 1 ##### 89 | 2######## 2##### 2 ##### 2 ##### 90 | 3######## 3##### 3 ##### 3 ##### 91 | 4######## 4######## 4######## 4 ##### 92 | 5 # 5##### 5 ##### 5 93 | 6 # 6##### 6 ##### 6 94 | 7 # 7##### 7 ##### 7 95 | 64(@): 76543210 65(A): 76543210 66(B): 76543210 67(C): 76543210 96 | 0 0 0##### 0 ##### 97 | 1 1 1##### 1 ##### 98 | 2 2 2##### 2 ##### 99 | 3 ##### 3##### 3##### 3 ##### 100 | 4 ##### 4##### 4##### 4 ##### 101 | 5 ##### 5##### 5 5 # 102 | 6 ##### 6##### 6 6 # 103 | 7 ##### 7##### 7 7# 104 |105 |
106 | 68(D): 76543210 69(E): 76543210 70(F): 76543210 71(G): 76543210 107 | 0# 0 # 0##### 0 # 108 | 1 # 1 # 1##### 1 109 | 2 # 2 # 2##### 2 110 | 3 ##### 3##### 3##### 3 111 | 4 ##### 4##### 4##### 4 112 | 5 ##### 5##### 5 # 5 113 | 6 ##### 6##### 6 # 6 114 | 7 ##### 7##### 7 # 7 115 | 72(H): 76543210 73(I): 76543210 74(J): 76543210 75(K): 76543210 116 | 0 0 0# 0######## 117 | 1 1 1 1 118 | 2 2 2 2 119 | 3 3 3 3 120 | 4 4 4 4 121 | 5 5 5 5 122 | 6 6 6 6 123 | 7 # 7# 7 7 124 | 76(L): 76543210 77(M): 76543210 78(N): 76543210 79(O): 76543210 125 | 0 0# 0 # 0 126 | 1 1# 1 # 1######## 127 | 2 2# 2 # 2 128 | 3 3# 3 # 3 129 | 4 4# 4 # 4 130 | 5 5# 5 # 5 131 | 6 6# 6 # 6######## 132 | 7######## 7# 7 # 7 133 | 80(P): 76543210 81(Q): 76543210 82(R): 76543210 83(S): 76543210 134 | 0 0 0 0 135 | 1######## 1######## 1######## 1######## 136 | 2# 2## 2### 2#### 137 | 3# 3## 3### 3#### 138 | 4# 4## 4### 4#### 139 | 5# 5## 5### 5#### 140 | 6######## 6######## 6######## 6######## 141 | 7 7 7 7 142 | 84(T): 76543210 85(U): 76543210 86(V): 76543210 87(W): 76543210 143 | 0 0 0 0 144 | 1######## 1######## 1######## 1######## 145 | 2##### 2###### 2####### 2######## 146 | 3##### 3###### 3####### 3######## 147 | 4##### 4###### 4####### 4######## 148 | 5##### 5###### 5####### 5######## 149 | 6######## 6######## 6######## 6######## 150 | 7 7 7 7 151 |152 |
153 | 88(X): 76543210 89(Y): 76543210 90(Z): 76543210 91([): 76543210
154 | 0 0 0# # 0 #
155 | 1 # 1# 1 # # 1 #
156 | 2 # 2# 2 # # 2 #
157 | 3 # 3# 3 ## 3 #
158 | 4 # 4# 4 ## 4########
159 | 5 # 5# 5 # # 5 #
160 | 6 # 6# 6 # # 6 #
161 | 7 7 7# # 7 #
162 | 92(\): 76543210 93(]): 76543210 94(^): 76543210 95(_): 76543210
163 | 0 ## 0 ## 0 ## 0########
164 | 1 #### 1 ## 1 #### 1# #
165 | 2## ## ## 2 ## 2## ## ## 2# #
166 | 3 ## 3 ## 3 ## 3# #
167 | 4 ## 4## ## ## 4## ## ## 4# #
168 | 5 ## 5 #### 5 #### 5# #
169 | 6 ## 6 ## 6 ## 6# #
170 | 7 7 7 7########
171 | 96('): 76543210 97(a): 76543210 98(b): 76543210 99(c): 76543210
172 | 0 #### 0## # 0 ## 0 #
173 | 1 ## ## 1# # # 1 # # 1 ##
174 | 2 ## 2# # 2 # # 2 # #
175 | 3 ## 3## 3 ### 3# # #
176 | 4 ## 4# # 4 # # 4 # #
177 | 5 5# # 5 # # 5 ##
178 | 6 ## 6# 6 ## 6 #
179 | 7 7 7 7
180 | 100(d): 76543210 101(e): 76543210 102(f): 76543210 103(g): 76543210
181 | 0# # 0# # 0# # # 0# #
182 | 1## ## 1## ## 1# # # 1 # #
183 | 2# # # # 2# # # # 2## # 2 # #
184 | 3# # # 3# # # 3# # 3 #
185 | 4# # # # 4# # 4## 4 # #
186 | 5## ## 5# # 5# 5 # #
187 | 6# # 6# # 6# 6# #
188 | 7 7 7 7
189 | 104(h): 76543210 105(i): 76543210 106(j): 76543210 107(k): 76543210
190 | 0## # 0 # 0 # 0 #
191 | 1# # # 1 # 1 ### 1 #
192 | 2## # # 2 # 2 # # # 2 #
193 | 3# # # # 3 # 3# # # 3 ###
194 | 4# # ## 4 # 4 # # # 4 # # #
195 | 5# # # 5 # 5 ### 5# # #
196 | 6# ## 6 # 6 # 6# # #
197 | 7 7 7 7
198 |
199 |
200 | 108(l): 76543210 109(m): 76543210 110(n): 76543210 111(o): 76543210
201 | 0 # 0## ## 0# # 0## #
202 | 1 ## 1# # # # 1 # # 1# # ##
203 | 2 # # 2# # # 2 ### 2## # #
204 | 3 # # 3# # # # 3 # # 3# # #
205 | 4 # 4## ## 4 # # 4# #
206 | 5 # 5# # 5 # 5#
207 | 6 # 6# # 6 # 6#
208 | 7 7 7 7
209 | 112(p): 76543210 113(q): 76543210 114(r): 76543210 115(s): 76543210
210 | 0# 0 # 0 ## 0 #
211 | 1# 1 # 1 # # 1 # #
212 | 2# 2 # 2 # # 2 # ##
213 | 3# # 3 #### 3 # # 3 # # #
214 | 4# # # 4 # # 4 ## 4 ## #
215 | 5## # 5 # # 5 # # 5 # #
216 | 6# # 6 # # 6 # # 6 #
217 | 7 7 7 7
218 | 116(t): 76543210 117(u): 76543210 118(v): 76543210 119(w): 76543210
219 | 0 # 0 ## 0 # 0 ##
220 | 1 ### 1 # # 1# ### # 1 # #
221 | 2 # # # 2 # # 2 # # # 2 # #
222 | 3# # # 3 # # 3 # 3 # #
223 | 4 # 4 # # 4 # 4 ##
224 | 5 # 5 # # 5 # 5 #
225 | 6 # 6 # # 6 # 6 #
226 | 7 7 7 7
227 | 120(x): 76543210 121(y): 76543210 122(z): 76543210 123({): 76543210
228 | 0# # # 0### 0 # 0### ###
229 | 1 # # # 1## # 1 # # 1## ##
230 | 2 ### 2# # # 2 # # 2 # #
231 | 3 # 3# # # 3 # # 3### ###
232 | 4 # 4# ## # 4 # 4### ###
233 | 5 # 5# # ## 5 # # 5### ###
234 | 6 # 6# # # 6 # # 6### ###
235 | 7 7 7 7########
236 | 124( ): 76543210 125(}): 76543210 126(~): 76543210
237 | 0### ### 0### ### 0## ##
238 | 1### ### 1## ## 1# ## #
239 | 2### ### 2 # # 2##### #
240 | 3### ### 3### ### 3#### ##
241 | 4 # # 4 # # 4### ###
242 | 5## ## 5## ## 5########
243 | 6### ### 6### ### 6### ###
244 | 7######## 7######## 7########
245 |
246 |
247 |
248 | Two different versions of font 3 were supplied by Infocom, which we shall 251 | call the Amiga and PC forms (the Atari form is the same as for the PC). The 252 | arrow shape differed slightly and so did the rune alphabet. Each was an attempt 253 | to map the late Anglian ("futhorc") runic alphabet, which has 33 254 | characters, onto our Latin alphabet. The drawings above are from the Amiga 255 | set. 256 |
257 | 258 |Most of the mappings are straightforward (e.g., Latin A maps to Anglian a), 259 | except that: Latin C is mapped to Anglian eo; K to "other k" (previously a 260 | z sound); Q to Anglian k (the same rune as c); V to ea; X to z and Z to oe. 261 | The PC runes differ as follows: G has an ornamental circle making it more 262 | look like "other z"; K maps to Anglian k (or c); Q is an Anglian ea (which 263 | resembles the late Anglian q); V is an oe; X is an "other k" and Z is a 264 | symbol Infocom seem to have invented themselves. (Though less well drawn 265 | the PC runes arguably have a better sound-mapping.) 266 |
267 | 268 |The font behaviour of 'Beyond Zork', which does have bit 3 of 'Flags 2' 269 | set, is rather complicated and depends on the interpreter number it 270 | finds in the header (see S 11). Specifically: 271 |
272 | 273 |289 | 179 becomes a vertical stroke (ASCII 124) 290 | 186 a hash (ASCII 35) 291 | 196 a minus sign (ASCII 45) 292 | 205 an equals sign (ASCII 61) 293 | all others in the range 179 to 218 become a plus sign (ASCII 43) 294 |295 |
A similarly tangled process is used in 'Journey'. It is 307 | obviously highly unsatisfactory to have to make the decision in 308 | the above way, which is why set_font is now required to return 309 | 0 indicating non-availability of a font. 310 |
311 | 312 |Stefan Jokisch suggests that Infocom originally intended the 313 | graphics bit as a way to develop Version 5 to allow a graphical 314 | version in parallel with the normal text one. For instance, when 315 | the Infocom MSDOS interpreter starts up, it looks at the graphics 316 | flag and: 317 |
318 | 319 |if clear, it sets the font width/height to 1/1 (so that screen 320 | units are character positions); 321 |
322 | 323 |if set, it enters MGCA, a graphical screen mode and sets the font 324 | width/height to 8/8 (so that screen units are pixels). 325 |
326 | 327 |The "COLOR" command in 'BZ' (typed at the keyboard) also behaves 328 | differently depending on the interpreter number, which is legal behaviour 329 | and has no impact on the specification. 330 |
331 | 332 |335 | Contents / 336 | Preface / 337 | Overview 338 |
339 | 340 |Section 341 | 1 / 2 / 342 | 3 / 4 / 343 | 5 / 6 / 344 | 7 / 8 / 345 | 9 / 10 / 346 | 11 / 12 / 347 | 13 / 14 / 348 | 15 / 16 349 |
350 | 351 |Appendix 352 | A / B / 353 | C / D / 354 | E / F 355 |
356 | 357 |