{"id":13782419,"url":"https://github.com/kevinboone/grotz","last_synced_at":"2026-02-23T05:33:10.262Z","repository":{"id":89188951,"uuid":"47747232","full_name":"kevinboone/grotz","owner":"kevinboone","description":"A z-code/Infocom interpreter for Linux and WIndows","archived":false,"fork":false,"pushed_at":"2024-06-20T12:50:33.000Z","size":16470,"stargazers_count":10,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-17T17:43:17.628Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kevinboone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-10T08:08:59.000Z","updated_at":"2024-06-20T12:49:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"f59e99fb-b738-4e61-88b9-29b628e338d0","html_url":"https://github.com/kevinboone/grotz","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinboone%2Fgrotz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinboone%2Fgrotz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinboone%2Fgrotz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinboone%2Fgrotz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kevinboone","download_url":"https://codeload.github.com/kevinboone/grotz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253588744,"owners_count":21932315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T18:01:36.791Z","updated_at":"2026-02-23T05:33:10.213Z","avatar_url":"https://github.com/kevinboone.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# grotz -- a Z-code interactive fiction interpreter for GTK\n\n_Version 0.2c, April 2012_\n\n*Please note that grotz was substantially written back in 2012.*\n*Although there have been bug fixes since then, very little work has*\n*been done, and I'm not convinced that the build machinery for Windows*\n*still works. Despite the optimism I express in the main documentation,*\n*grotz is actually a little fiddly to build, for any platform.*\n*There are binaries in various*\n*repositories, for Linux and Windows, but I have no idea how up to date*\n*they are. Although grotz is notionally still maintained (as of 2024),*\n*I have to confess that there has been little recent activity.*\n\n*Please note also that Frotz uses GTK2 (aka GTK+ 2.0). Both building*\n*and running it probably require dependencies that won't be installed*\n*by default on a modern Linux system.*\n\ngrotz is a GTK2 port of Frotz -- the classic Z-code game engine.\ngrotz, like Frotz, is intended for playing 'interactive fiction'\ngames compiled for the Inform Z-machine platform. Although the\nZ-machine is, in a sense, an archaic and defunct platform, many\ngames and stories were developed for it, and more continue to\nbe written. grotz makes a reasonable job of playing most of the\noriginal Infocom games -- Zork, Arthur, Lurking Horror, etc --\nincluding (to some extent) graphics and sound.  The world of\ninteractive fiction has moved on since the Infocom days, but\nthese old games still exercise a Z-code interpreter thoroughly\n-- more so than modern developments which rely less on the Z-machine\nto provide the complete user interface.\n\ngrotz is intended to support Linux and Windows using exactly the same code and\nbuild files. It is written entirely in C, and uses a single-Makefile build\nsystem which is very simple, and could probably be adapted to compile for other\nplatforms on which GTK runs. The primary platform is Linux -- there are \nalready good Z-code interpreters for Windows. It's always struck me\nas anomalous that there are few stable, feature-rich Z-code platforms\ndesigned for modern Linux desktops. Of course, there is Gargoyle --\nbut Gargoyle's focus seems to be on typography rather than comprehensive,\nspecific Z-machine support.\n\ngrotz is far from being a finished product, but at present it seems to\nbe basically functional. Bug reports, etc., are welcome; bug fixes\neven more so ;) \n\n\n## Features\n\n* Supports all the Z-code versions that Frotz supports, and adds support for zblorb archives\n* Some support for Z-code version 6 graphics (see below)\n* Uses variable-pitch fonts where possible, which most people find easier to read than console fonts\n* Unicode support, both for keyboard and screen\n* Mouse support, with games that implement it. You can move around by clicking the compass rose in _Zork Zero_, for example\n* Transparent and true-colour text support, as defined in version 1.1 of the ZMachine specification\n* Supports Amiga-style box graphics, for those games that require this feature (e.g., _Beyond Zork_)\n* Transcript/scrollback viewer\n* Rudimentary sound support\n\n\n\n## Building and installing\n\nOne of the goals of grotz is to build on Linux and Windows (using MinGW\n and Msys)\nusing unsophisticated build tools. In principle, all that is required\nare GTK2 development libraries and headers, and a C compiler. \n\nBuilding the program ought to be as simple as unpacking the source\ncode and typing `make bundle`. This should compile\neverything, and copy the compiled binary and supporting libraries\nto the platfom-specific subdirectory of the 'deploy'\ndirectory. In the Linux case, there will be no additional libraries,\nbecause we expect to find them at the system level. On Windows, \nbinaries of the GTK2 libraries are copied alonside the program\nexecutable, making a big bundle ready for the Windows installer.\n\nOn Windows, the source code comes with the development version of\nGTK2 bundled, as most Windows developers do not have this. All this\nstuff is in the 'winstuff' directory.\n\nThe assumed use of Msys allows us to treat Windows and Linux builds\nas essentially the same. Msys provides Windows versions of the\nusual Unix 'cp', etc., commands, and the Makefile asumes\nthat these are locatable on the %PATH%.\n\n\n## Running grotz\n\nYou can specify a Z-code story file on the command line, or by \nselecting File|Open... Infocom version 6 files with graphics\nhave an additional complexity -- more on this below. \nWhen a story is running, most menu options will be disabled -- the\nZ-machine specification provides no facility by which the state of\nplay or the environment can be changed other than by the text typed\nby the user. To use the menu again, you'll have to exit the current\nstory (usually by typing 'quit'). You can quit the program at any\ntime, but the game state will not be saved unless you save it\nthrough the game itself.\n\nIt's important to bear in mind that Z-code _is_ an archaic\nformat, from the early days of personal computing. There's a limit\nto how much can be done to modernize the look and feel of Z-code\ngames. Some Z-code games, for example, do their own character input\nand editing -- and they often don't do it very well. If a \nZ-code program asks for input a line at a time, then at least\nthe Z-code interpreter can provide line-editing facilities.\nBut even then the program will probably be drawing a prompt, and\nexpecting input to be echoed to the screen just like on a terminal.\ngrotz does what it can to wrap a modern user interface around an\nancient virtual machine architecture -- but that often turns out\nto be not very much.\n\n\n## Configuration file\n\ngrotz creates a directory '$HOME/.grotz' on Linux or\n'c:\\Users\\[user]\\AppData\\Roaming\\grotz' on Windows.\nThe configuration file 'grotz.ini' is saved in this\ndirectory, as are certain temporary files. There are certain settings\nin the configuration file that are not accessible through the\nGUI -- these are described below.\n\n\n## Font issues\n\ngrotz will allow any font present on the system to be used for the\ndisplay. However, although Inform's specification does hint at the\npossibility of using variable-pitch fonts, the screen model is\nimplicitly based on a fixed size rectangular grid of cells. That\nremains true even for version 6. Z-code games and stories can,\nand nearly always do, position text at absolute row and column\npositions. The screen model does allow for wrapping and scrolling\nof text, so in principle a Z-code program could output text in\nlarge blocks and allow the interpreter to flow it nicely onto\nthe screen. In practice, the code generated by Z-code\ncompilers, even modern ones, outputs text word-by word at\nspecified screen positions. All this makes it very difficult to\norganize text in an elegant, book-like way.\n\nIn short, selecting a variable-pitch font may work reasonably \nwell with some games and stories. It will often be\nnecessary to adust the screen size and font to find a workable\ncombination. Bear in mind that the screen size is worked out \nto accomodate the longest possible row of characters of a particular\nfont. With variable pitch, many of the rows will be unfilled, because\nmost characters are less wide than the largest in the font. There\nwill therefore be a substantial ragged right margin regardless of\nthe font and size settings, because grotz has no way of knowing\nthat the story won't output a whole row of X's or something\n(and, in fact, this kind of behaviour is not uncommon). Having said\nall that, in practice the use of variable-pitch fonts works \npretty well, considering all the problems, and is recommended.  \n\n\n## Unicode support\n\ngrotz supports unicode output and, to some extent, input --\nto the extent that Z-machine, the operating system, GTK, and\ninstalled fonts do. Running David Kinder's Unicode.z5 test program should\nproduce either reasonable output, or complaints about missing\nfonts (I forgot to install Coptic support on my Linux desktop\nmachine, for some reason). If it produces nothing but \nquestion marks or hex boxes, something is wrong. \n\nUnicode characters can be entered so long as they are available\nas a single keystroke, and so long as GTK understands what \nunicode symbols the keystrokes map on to. The 'dead key' method\nof entering extended key codes is not, as yet, supported. \n\nPlease note that unicode support depends on a co-operative operating\nsystem configuration. grotz cannot itself make up for missing\nfonts or libraries, or a dubious locale configuration.\n\n\n## zblorb support\n\nMany IF authors now provide Z-code programs bundled into 'blorb' archives.\nSuch files typically have names ending in '.zblorb'. Files with \nsimilar names, like '.gblorb' may well be in the same format, but probably\ndon't contain Z-code but some other IF format.\n\ngrotz will unpack a .zblorb file and will run the Z-code therein, if it\nfinds any. The Z-code is unpacked into the program's home directory\n('$HOME/.grotz' on Linux) and are not deleted on exit -- you\nnever know, they might be useful. If the zblorb file contains\nauthorship information and/or a cover image, these will displayed if you\nselect Help|About this story... from the menu.\n\ngrotz will treat a file as a zblorb if its name end .zblorb or\n.zlb.\n\nAnother use of blorb files is to provide more modern representations of\nthe graphics and sound used in the Infocom games -- see the sections\non graphics and sound support for more information.\n\n\n\n## V6 graphics issues\n\nA very small number of games were produced by Infocom using the graphical\nversion of the Z-machine, version 6. The best-known of these is \nprobably Zork Zero. This game, like all the other Inform games, remains\nunder copyright, so more modern re-implementations are not widely \navailable. Z-machine version 6 required the graphics to be supplied \nin a separate file to the Z-code program, and in a very peculiar,\nproprietary format. I have not attempted to support this format in\ngrotz -- the amount of work involved for a handful of defunct games\nis just prohibitive. However, versions of the Zork (and other) graphics\nare widely available redrawn in the more modern PNG format, \nbundled up inside\n'blorb' archives. grotz _will_ attempt to display\ngraphics in this format. To use this feature, the graphics file should\nhave the same name as the main story file, but with a '.blb'\nextension, and be in the same directory. The same method is used to\nprovide sound effects (see below), and in principle there might be\na complication about what file to use if a game uses both\ngraphics and sound. However, so far as I can tell, none of the original\nInfocom games did, and more modern games would probably package the\ngraphics and/or sound up with the executable code in a single\nblorb file.\n\nThe original Inform graphics were drawn for a 320x200 pixel screen.\nIn practice, such a resolution is unusable on modern display\nhardware, even if the fonts can be set to provide such a size.\nThere is no straightforward way for for grotz to work\nout what resolution screen graphics were originally intended for\n-- the blorb specification does define a possible method but, like\neverything to do with the blorb specification it thoroughly Byzantine\nin its complexity.\ngrotz therefore assumes that all graphics are drawn for a 320x200\npixel screen, and scales to fit the current true screen size.\n\nNote that the original Inform games were designed to\nflow text around the graphics, so getting the graphics sizes right\nis a matter of some importance. If the graphics you have are\n_not_ for a 320x200 screen, then it might be necessary to \ntell grotz the original screen size. At present, there is no way\nto do this through the GUI (sorry), but you can put the relevant\nsettings into the configuration file:\n\n\u003cpre\u003e\n[UI]\ngraphics\\_width=NNN\ngraphics\\_height=NNN\n\u003c/pre\u003e \n\nSo far, I've not come across any redrawn graphics files for any\nof the original Infocom games that use anything by 320x200, so the\nneed to provide an easy way to change the resolution does not seem\nto be a pressing one.\n\n\n## Colour issues\n\ngrotz tries to respect the original Z-machine colour assignments, ugly\nas they are. Because the original Z-machine spec did not recognize the\nneed for transparent text, problems arise when overlaying text onto\nimages. grotz tries to work around these the same way the Windows Frotz\ndoes -- it samples the screen colour under the cursor, then maps the\ncolour value onto an index in a table. This index is then passed\naround the Z-machine VM as if it were a standard colour code. \nThe efficacy of this technique is somewhat variable. The 'true colour'\nmode of the Z-machine 1.1 spec. is also supported, using the same\nmechanism.\n\nIf the game does not set any colours, then default foreground and \nbackground colours are used. These can be configured in the \npreferences dialog. It is also possible to set grotz to ignore the game's\nown colour settings, in which case defaults are always used. Ignore game\ncolours is not advisable with games like Beyond Zork, which use\ncolour assignments to highlight menu selections. Results are likely to\nbe unpredictable if the game uses transparency, or if you change colour\nsettings in mid-game.\n\n\n## Sound support\n\n...is rudimentary. Sounds need to be packaged into blorb files in the\nsame manner as described for V6 graphics. Sounds suitable for the\noriginal Infocom games (_Sherlock_, _Lurking horror_, etc)\nare widely available in this format. grotz does not attempt to play \nany sound itself -- why should it, when there are any number of\nperfectly satisfactory audio players for Linux? Instead, when called\non to play a sound it will unpack the sound into the temporary\ndirectory, and then invoke the script 'grotz\\_playmedia.sh'\n(or 'grotz\\_playmedia.bat' on Windows). As shipped, this\nscript will invoke 'mplayer', passing arguments representing\nthe number of repetitions of the effect, volume, etc. The Windows \n.bat file will also try to invoke mplayer, in the directory\n'c:/program files/SMplayer/mplayer'. The batch or script\nfiles can readily be edited to invoke an alternative media player,\nor mplayer in a different location, if necessary.\n\nThis method of producing sounds works pretty well on Linux, because\nmplayer is fast to start up, and can be run invisibly in the background. \nOne complication of this approach is that grotz only finds out\nthat sound playback has finished if it gets notified by the OS that the\nmedia playing process has terminated. This method seems to work\nreasonably reliably on Linux, but less predictably on Windows. \n\nThe use of an external player is less satisfactory on Windows. \nmplayer is a console application, and it is difficult to prevent\na 'DOS box' popping up when sound is played, at least momentarily.\nIt might be possible to change the Windows batch file to launch\na different player -- but Windows Media Player is even less\nsatisfactory because, even though you can launch it to play a specific\nfile, it won't close that file when playback is finished, unless\nyou take manual action.\n\nThe entire set of Infocom games use about 30 sound effects between\nthem, and I'm not aware that anybody else is producing IF stories\nthat use sound. If there is a substantial demand, it would certainly\nbe possible to implement sound playback directly in grotz, in a way\nthat would work on Linux and Windows. But at present it hardly\nseems worth the considerable development effort that would be involved.\n \n\n## Keyboard input\n\ngrotz should recognize all keystrokes that generate a unicode or ASCII\ncharacter (although the Z-machine program might not). The following\nkeystrokes have a particular meaning during line input.\n\nKey | Function\n----|---------\nctrl-v | paste at cursor position\nctrl-d | end of input. Actually enters the text quit+Enter, as if from the keyboard, as this is the usual way of quitting most IF games\nctrl+k | erase text from the cursor to end of line\nctrl+c | erase whole line\nbackspace | deletes the character behind the cursor\ndelete | deletes the character under the cursor\nctrl+right | moves forward to the next word\nctrl+left | moves back to the previous word\nup/down | moves through the history list of previous lines\n\nThese keystrokes are only effective if a game or story asks for input\na line at a time. Most do, but a few do input character by character.\nHow that works out depends on how well the programmer implemented it --\nthe behaviour cannot be changed by grotz.\n\n\n## Emulation issues\n\ngrotz identifies itself to Z-code programs as an Atari Amiga, unless\nyou specify otherwise. The idenfication can be changed from the\nSettings dialog. For the most part, the changes are quite subtle, and\nconcern the colours that will be used and (occasionally) what\nkeystrokes are used for menu navigation. \n\n\n## Limitations and quirks\n\n* Line editing is not as comprehensive as it might be.  There is no tab completion, and you can't edit within the line itself. You can't select cursor position with the mouse, because a mouse click is a valid input in its own right to the Z-machine.  However, since Z-code line input is typically limited to 60 characters, this might not be a deal-breaking issue.\n* There are no 'hot keys' for features like enabling tracing (as Frotz provides).\n* Games or stories that set the absolute text position in screen units will potentially look quirky with a variable-font display. This is a fundamental limitation of the Z-machine design.\n* Most modern games and stories will output text in such a way that the interpreter can break lines sensibly at work boundaries. But many stull use a fixed-path area for status lines, etc., which cannot be reflowed. grotz will not prevent you making the screen too small to show these areas properly (but it's pretty obvious when this has happened).\n* You can't cut and paste text from the text display to the input line.  The display is essentially a graphics terminal and, once text is rendered onto it, it has no recollection of the actual characters. As a sort of workaround, you can cut and paste text from the transcript window into the input line.\n\n\n## Known issues\n\n* Some PNG graphics files display with rather odd colours. This, I believe, is because they were originally created without a colour palette, and conversion to PNG has forced a palette on them. There is a complicated work-around for this involving 'adaptive palette' chunks in blorb files, but implementing the workaround seems like an awful lot of work for very little benefit. \n* If running the debug build on Linux, stdout and stderr should be redirected.  For some reason, the logging seems to be capable of breaking the console.\n* The user interface allows font and screen size to be changed during execution of a game, but the results can be unpredictable -- Z-machine makes little provision for run-time environment changes.\n* grotz attempts to work around a number of bugs (or at least oddities) in Infocom's games. For example, in _Beyond Zork_ the game puts data into the input buffer which differs in case from what it actually displays on screen. These workarounds have a variable success rate \n* Most Z-code games and stories that use menus draw their own,\nusing the Z-machine's graphics and mouse capbilities. There is a\n'proper' menu facility in the Z-code specification, but grotz does\nnot support it. The reason is that I have been unable to find a single\ngame or story that requires it. I would be happy to implement support\nif anybody can provide an example of its use.\n* No support for languages that use right-to-left text\n* Some errors in the Z-machine are so intractable that the only solution is to shut down the program completely. This is not very elegant\n* On Windows, some fonts do not seem to be rendered with fonts that match their names. I suspect that this is a GTK issue, not a problem in grotz. Moreover, some fonts appear to have baselines in odd places, again only on Windows. With these fonts some characters may be clipped\n* In order to reduce the amount of computation, I have in places made assumptions about how the sizes of different members of a font family relate to one another, rather than having the exact sizes calculated by the layout engine. It's possible that these assumptions will fail with some fonts, and text might be clipped with certain typefaces\n\n## Authors and credits\n\nThe original implementation of Frotz was by Stefan Jokish, around 1997.\nIt was subsequently developed and extended by a number of people,\nnotably Galen Hazelwood, Jim Dunleavy, David Griffith, Alembic Petrofsky,\nand Daniel Schepler. \n\nFrotz was extended with full Unicode support by David Kinder, who wrote\nWindowsFrotz -- the source for which I referred to extensively in \ndeveloping grotz.\n\ngrotz is released under the GNU Public Licence, version 3.0.\n\n\n## Revisions\n\n### 0.2c\n\n* Minor bug fixes\n* Added option to ignore game colours\n\n### 0.2b\n\n* Fixed the 'more...' prompt so that it does not push text to the right\n* Made the caret visible in single-key keyboard read operations\n* Added error reporting level selection the Settings dialog\n* If a game clears the whole screen to a particlar colour, that colour is now also used for the unpainted areas of the main window (e.g., margins).  This makes games like Beyond Zork that draw their own dark backgrounds look nicer, at the expense of a bit more screen flicker at times.  \n\n### 0.2a\n\nFirst public release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevinboone%2Fgrotz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevinboone%2Fgrotz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevinboone%2Fgrotz/lists"}