UNQUILL(1) General Commands Manual UNQUILL(1) NAME unquill - Disassemble, play, and convert games written with Quill. SYNOPSIS unquill { -option { -option ... }} inputfile DESCRIPTION UnQuill takes snapshot files of Spectrum, CPC and Commodore 64 games written with Quill, and produces textual listings of the data tables which control them. From this it is possible to determine how to solve the game (ie cheat :-)) or how to reconstruct it on another gamewriting system. It can also run the games or convert them to the Infocom Z-Code format. Supported snapshot formats are Spectrum .SNA (used by JPP), CPC .SNA (used by CPCEMU) and Commodore .VSF (used by VICE). spconv (1) can be used to convert many Spectrum snapshot formats to .SNA; I'm not aware of equivalent CPC or C64 tools. Note that spconv v1.08 or later is needed to convert the most recent format of .Z80 snapshots. The supplied .EXE file runs under DOS. COPYING UnQuill is copyright 1996-2002, 2011, 2012, 2015, 2020 by John Elliott. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER‐ CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. OPTIONS -O Redirect output to a file rather than stdout. -C UnQuill normally refuses to write a Z5 file to standard output. You can force it to using the -C option. -Dx Display options when the -TR option is used under DOS to run the game. x can be: 4 CGA 4-colour graphics mode (default if CGA video hardware detected) C CGA / EGA / VGA 16-colour text mode. E EGA 16-colour graphics mode (default if EGA video hard‐ ware detected) M MDA monochrome text mode (default if MDA video hardware detected) T Plain text output (matching the behaviour of UnQuill on other platforms) -- no graphics or colours. V VGA / MCGA 256-colour graphics mode (default if VGA video hardware detected) Note that if a game does not define a custom typeface, UnQuill will try to load the Spectrum font from a Spectrum ROM image. This should be called spectrum.rom and be located in the current directory. If spectrum.rom is not present, a built-in open- source font will be used instead. -G Enables experimental graphics character support when outputting to a Z5 file. -M Disable text colours when outputting to a Z5 file. -L There are two types of Quilled games - "early" (usually text- only) and "late" (usually with graphics). -L selects the "late" type; use this if UnQuill gives nonensical output or address er‐ rors without the -L option. Games produced with PAW (Profes‐ sional Adventure Writer) will probably cause address errors whether the -L option is present or not. -TX Output a representation of the game in XML. -TZ Normally, game text is displayed in 32-column lines and colour codes are omit‐ ted. -TZ switches to HTML-like output ("ZXML") where colour codes are represented as and the text is not formatted. The <,> is the PRINT comma (16-column tab). -TZB As ZXML, but
(line break) tags are inserted where the lines of output would break while being printed. -TI Produce a source file suitable for the Inform (1) adventure game compiler. Note that the resulting source will not compile into a working game; it is intended to be used for further rewriting. -T5 Produce a Z5 module suitable for Infocom/Inform interpreters such as frotz (1). For this to work, the file iqrun.z5 must be in the current directory (or, in the Unix version, in the li‐ brary directory specified in the Makefile). -TR Emulate the Quill runtime system and play the game. Notes on the emulation are scattered through the detailed information below. -Q Quiet. No beeping (applies to -TR and -T5). This is for use with games like SubSunk wherein the beeper is used to play tunes. -V Verbose. Condition and connection table entries referring to a particular room, object or message are annotated with the text of the respective room, object or message. -Sx Do not output a section of text. x can be: C Condition tables (Response and Process). F User-defined font(s) (if present). G Location graphics. L Location descriptions. M Messages. N Connections. O Object descriptions and initial locations. S System messages. U User-defined graphics. V Vocabulary. OUTPUT FORMAT (Normal mode) Output will be in the form of several tables: Response (Events) table Each entry is of the form: VERB NOUN Conditions: condition1 condition2 condition3... Actions: action1 action2 action3... This table is scanned immediately after player input. The two words at the beginning are compared with the player's command, and if there is a match the conditions will be tested. Assuming the conditions hold, the actions are then performed. Scanning of the table then continues at the next entry. If all entries have been scanned, an attempt is made to parse the command as a "movement" command; if that fails, the message "I can't do that" is printed. The word "_" is a wildcard and matches any word typed. The table is sorted by word number; since "_" is word 255, it comes last. Process (Status) table As Response, but the two words at the beginning of the entry are used only for sorting and as aides memoires for the programmer. All entries are checked; this table is scanned immediately before player input. Conditions are: AT x True if player in room x NOTAT x True if player not in room x ATGT x True if player in room > x ATLT x True if player in room < x PRESENT x True if object x is worn, carried or at the same location as the player. ABSENT x True if object x is not worn, carried or at the same location as the player. WORN x True if object x is worn. NOTWORN x True if object x is not worn. CARRIED x True if object x is carried. NOTCARR x True if object x is not carried. CHANCE x True if a random number between 0 and 100 is less than x ZERO x True if flag x is zero. NOTZERO x True if flag x is nonzero. EQ x y True if the value of flag x is y GT x y True if the value of flag x > y LT x y True if the value of flag x < y Actions are: (actions marked * are only available in later games) INVEN Display player's inventory DESC Describe current room, stop scanning table. QUIT Print "Are you sure?". If player types Y, continue; else behave as DONE END Print "End of game - play again?". If player types Y, restart the game. Otherwise, print "Have a nice day" and reset the Spectrum. DONE Command successful. Stop scanning the table. OK Print "OK." and behave as DONE ANYKEY Print "Press any key to continue" and wait for a keypress. Note: On systems other than DOS, you should press RETURN, because the input works in cooked mode. SAVE Save the current position. LOAD Load the current position. TURNS Print "You have taken n turns" where n is the number of inputs made. SCORE Print "You have scored x " where x is the contents of flag 30. *CLS Clear the screen. *DROPALL "Drop" all objects. *AUTOG "Get" the currently referenced object. *AUTOD "Drop" the currently referenced object. *AUTOW "Wear" the currently referenced object. *AUTOR "Remove" (ie unwear) the current object. PAUSE x Pause x /50 seconds. PAUSE is also used in "late" games to con‐ trol functions such as RAMsaving and graphics; if flag 28 holds a value from 1-23, a subfunction will be called and then flag 28 will be reset to zero. The subfunctions are listed later. *PAPER x Set background colour to x (0 is black, 1 is blue, 2 is red, 3 is magenta, 4 is green, 5 is cyan, 6 is yellow and 7 is white). *INK x Set foreground colour to x (0-7). *INK x y On the CPC6128, this is used to change the palette used: x is the pen number, 0-3, and y is the colour to use for that pen. *BORDER x Set border colour to x (0-7). GOTO x Move player to room x MESSAGE x Display message x REMOVE x "Remove" (unwear) object x ; checks that the player is wearing it and would be able to carry it. GET x "Get" object x ; includes checks for the object's presence etc. DROP x "Drop" object x ; checks that the player is carrying it etc. WEAR x "Drop" object x ; checks that the player is carrying it etc. DESTROY x Move object x to room 252 (destroyed objects). CREATE x Move object x to the same room as the player. SWAP x y Exchange object x and object y (eg "a lamp" and "a lit lamp"). *PLACE x y Move object x to room y SET x Let flag x = 255. CLEAR x Let flag x = 0. PLUS x y Add y to flag x MINUS x y Subtract y from flag x LET x y Let flag x = y BEEP x y Sound beeper; x = duration (centiseconds), y = pitch (60+(tones above middle C)). When the game is emulated, this is done by writing a BEL to stdout, and pausing for a second. On a game which makes frequent use of this command (such as Subsunk), this can get annoying, so the -Q option silences the beeps. "Patch" allows users to add new machine-code drivers for these com‐ mands. For example, in the Very Big Cave Adventure, INK has been rewritten to flash the screen. PAUSE subfunctions The subfunctions in this list are numbers to store in flag 28. Some also use the parameter x passed to PAUSE. They may vary slightly from game to game. Not many of these are emulated because they rely heavily on Spectrum hardware. 1,2,3,5,6 Sound effects; duration may be passed as the parameter to the PAUSE. 4 Flash the screen and the border. 7 Switch to the default font. 8 Switch to the alternative font. 9 A series of coloured boxes expands out of the centre of the screen at speed. 10 Change the "You can also see" message to x 11 Set the maximum number of objects carried at once to x 12 Restart the game without warning. 13 Reboot the Spectrum without warning. Emulated by leaving Un‐ Quill. 14 Increase number of objects that can be carried at once by x 15 Decrease number of objects that can be carried at once by x 16,17,18 Change the keyboard click to one of three alternatives. 19 If graphics extension loaded, switch graphics on or off (off if x is 255). 20 Has no effect. 21 RAMsave or RAMload. If x is 50, the game state will be loaded from RAM; otherwise it will be saved. 22 Save files contain an identity byte which is checked when load‐ ing or saving positions (normally 255). This subfunction sets the byte to x Object texts Object 0 is a source of light. If flag 0 is nonzero, then it is "dark" and the location description will only appear if object 0 is present; otherwise the message "Everything is dark. I can't see" appears. Objects are sometimes used to change the location descriptions of rooms; for example, the Very Big Cave Adventure has an object "The hairy figure has been blown to kingdom come. Unfortunately, so has the bridge". When this object is created, the location description contains this text just after a message of the "You can also see:" type. Such objects do not have words associated with them. Location texts The player starts in Room 0. The following extra locations may be seen in the condition tables: 252 Repository of non-created objects 253 Worn 254 Carried 255 The player's current location Message texts At the end of a message, all colours are reset to the standard colours. System messages Messages such as "I can't do that". In "early" games, these messages are in the runtime module rather than the database proper. Connections For each location, a list of verbs which can be typed and the result of typing them. These are scanned after the Response table. Vocabulary A list of words. Two or more words can have the same number; this makes them synonymous. Words with numbers <14 are "directions"; if an action involving such a word fails, "I can't go that way" is printed instead of "I can't do that." User-Defined Graphics Output as an X-Window bitmap. The UDGs are 21 8x8 characters, which have ASCII values 144-164. Some games (for example, Subsunk) use the UDGs to create location "graphics". User-Defined Font Output as an X-Window bitmap, containing 96 8x8 characters (ASCII 32 to 127). UnQuill displays UDGs in the game text as ? marks, or as "%xx" in ZXML, where xx is the hexadecimal version of their ASCII number (90-a4). Location graphics Location graphics are output as a series of drawing instructions. AMOVE x y Move the drawing position to the absolute coordinates (x,y). PLOT flags x y As AMOVE, but plots a point at the coordinates as well. The flags (i and o) are for Inverse and Over respectively. MOVE x y Move by a number of pixels relative to the current drawing posi‐ tion. LINE flags x y As MOVE, but draws a line. The flags (i and o) are for Inverse and Over. BLOCK h w x y Move to point (x*8, y*8) and set screen attributes in a block (w*8, h*8) in size. SHADE x y f As MOVE, but then does a shaded flood fill in a texture given by "f". "f" is treated as two nibbles; each gives an index into a patterns table. The two resulting patterns are ORed together, and that pattern is used for the fill. BSHADE x y f As SHADE, but overwrites the borders of the shaded area. FILL x y As SHADE, but does a solid fill rather than shaded. GOSUB sc=n room Draw the graphic for another room at the current coordinates, with scale "sc". Scale 0 is full-size; Scale 1 is 1/8, Scale 2 is 2/8, ... RPLOT flags dx dy Move by one pixel and plot a point. INK i Set ink colour for drawing. PAPER p Set paper colour for drawing. BRIGHT x Set bright attribute for drawing. FLASH f Set flash attribute for drawing. END End of drawing opcodes. The flags The flags are 36 variables which can hold values from 0-255. They are not displayed by UNQUILL since their initial values are always 0. Flag 0 is nonzero => it is dark. Player cannot see without object 0. Flag 1 = number of objects carried. Flag 2 if nonzero is decremented each time a location is described. Flag 3 if nonzero is decremented each time a location is described and it is dark. Flag 4 if nonzero is decremented each time a location is described, it is dark, and object 0 is absent. Flags 5-8 if nonzero are decremented at each player input. Flag 9 if nonzero is decremented at each player input when it is dark. Flag 10 if nonzero is decremented at each player input when it is dark and object 0 is absent. Flags 11-27 are free for use by games. Flag 28 is passed as a parameter to the PAUSE command in "late" games. If it is nonzero, PAUSE has extra functionality. Flag 29 is used in "late" games to control display of graphics. Bit 5 is set for graphics never to be drawn. Bit 6 is set for graphics to be drawn every time a location is described. If Bits 5 and 6 are zero, the graphics are only drawn the first time a location is described. Bit 7 is set to force the graphics to be drawn at the next loca‐ tion description, at which point it is automatically cleared. Thus a typical instance would be: LOOK _ Conditions: Actions: PLUS 129 128 DESC Flag 30 holds the player's score. Flags 31-32 hold the number of turns. This is a little-endian word. Flag 33 holds the vocabulary number of the first word found in the com‐ mand line. Flag 34 holds the vocabulary number of the second word found in the com‐ mand line. Flag 35 holds the current location. OUTPUT FORMAT (Inform mode) The Inform output mode performs a simplistic translation to an Inform source file. The rooms and objects will be converted to Inform rooms and objects, while the logic tables will be converted to two long sub‐ routines. Note that these subroutines (called QuillProcess and GamePre‐ Routine) are syntactically correct Inform, but will not work correctly; QuillProcess is called every game turn rather than every player input, while the code to detect nouns in GamePreRoutine doesn't work because the correct objects aren't in scope. The code may also generate verb actions with the same names as those in the Inform verb library (verblibm.h). If this is the case, the Inform compiler will emit error messages relating to verblibm.h; the first one of these shows the verb that caused the trouble, and the copy in the generated source file can be removed. The automated translation of directions is not perfect; for example, the translation of The Secret Of St. Brides translates "up" directions as UPST_to rather than u_to. OUTPUT FORMAT (Z5 mode) UnQuill merges the .SNA file with iqrun.z5, which must be present. The resulting Z-code file should run in any good Z-code interpreter (sup‐ port for timed events is preferable). iqrun.z5 is actually a Quill interpreter written in Z-code; so the Quilled game will be running under double emulation. This makes the game run at something like a third of the speed of a native Inform game; this only becomes apparent if you're using an 8-bit computer with CPU speed in the single figures. EXAMPLES A>unquill subsunk.sna -Osubsunk.txt Send the contents of Subsunk to a text file. D:/GAMES/SPECTRUM>unquill vbca1.sna -L -SC -SO -SL -SM -SS -SN -SU -SF -SG Display the vocabulary of the Very Big Cave Adventure, Part 1. % unquill -L -V -SL -SM retarded.sna | more List the workings of Retarded Creatures & Caverns; omit the locations and the messages because they will appear as annotations. A>unquill hampstd.sna -SC -SO -SL -SS -SC -SU -SV -TZ Display the messages of Hampstead, in ZXML. % unquill subsunk.sna -ti -osubsunk.inf Create an Inform file containing a simplistic conversion of Subsunk. $ unquill -l -t5 -otcom1.z5 tcom1.sna Create a Z5 file containing The Colour Of Magic. This file can then be used like any other .z5 file. BUGS Z5 output does not set the file checksum of the resulting Z5 game. So a "Verify" command (were there one) would say the file was damaged. The SAVE command in Z5 games saves the state of the Z-machine, not the state of the Quilled game. This means, firstly, that saved games are much bigger than they need to be; and secondly, that savefiles are not interchangeable between games. The automatic Inform translation is rather primitive. Report any bugs to John Elliott (jce@seasip.demon.co.uk). If a particu‐ lar .sna file caused problems, include a copy of it. FILES /usr/lib/games/zcode/iqrun.z5 - The Z-code module for the -T5 option. VERSION HISTORY v0.1 Could not display compressed files or UDGs. A bug sometimes oc‐ curred in listing more than 128 objects, locations or messages. v0.2 Ability to list compressed objects and UDGs added. Listing bug fixed. v0.3 Verbose mode added. System messages in "early" games now listed. v0.4 Lists word-object mappings in "late" games. Can run gamefiles. v0.5 Some bugs in the "run" code fixed - in particular, The Secret Of St Brides will now run correctly. Initial support for output in the Inform format. v0.6 Run-time accuracy improved. Output in Z5 format added. v0.7 Support added for the Commodore 64 and CPC Quill runtimes. Fur‐ ther bugs fixed in the "run" code. v0.8 Support added for Spectrum graphics. More runtime bugs fixed. v0.8.1 Some debugging text removed from the .Z5 template game. v0.8.2 Added font output. UDGs are now output correctly (not mirror-im‐ age). UnQuill version number is printed at the start of the output. v0.8.5 Added -TZB option for "ZXML with linebreaks". If a game has mul‐ tiple fonts, all of them will be extracted rather than just the currently selected one. v0.8.6 Fixed a bug that caused premature exit when dumping Merlock the Mede in verbose mode. v0.8.7 Improved the C64 snapshot parser to search for a C64MEM block rather than assume it to be at a fixed offset. v0.9.0 Corrected the behaviour of PLUS and MINUS opcodes (clamping at 255 and 0 respectively). Corrected the handling of colour output in the Z-code version. Added -TX XML output. v0.10.0 Added support for direct screen access in DOS, allowing display of coloured text and user-defined graphics. Dropped CP/M sup‐ port, as the source is now too complex for the Hi-Tech C com‐ piler to compile correctly. v0.10.1 Corrected various parts of the XML output that generated ill- formed XML documents. v0.11.0 Fixed various problems with the compression dictionary (com‐ pressed colour control sequences did not display correctly; com‐ pressed text in Z-code version was garbled). v0.11.1 Address validation refactored. v0.11.2 Corrected C64 vocabulary output. v0.11.3 Added UnQuill version number to output. v0.12 Attempted to improve range-checking so that minor corruption in a condition / action table does not lead to a crash. TO DO Output location graphics for CPC6128 and C64 versions. Support beeper sound in the DOS version. Support location graphics in the DOS version. Create SDL and Curses output handlers allowing the UNIX version to dis‐ play colour, accurate graphics etc. SEE ALSO spconv(1), inform(1) 19 November 2020 UNQUILL(1)