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 .COM file runs under CP/M; the .EXE file under DOS. If you
       have trouble running UnQuill under DOS, delete UNQUILL.COM.


COPYING
       UnQuill is copyright 1996-2002, 2011, 2012, 2015 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. CP/M users can
	      include user numbers in filenames thus:  4:A:FILENAME.SNA

       -C     UnQuill normally refuses to write a Z5 file to standard  output.
	      You can force it to using the -C option.

       -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
	      errors  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 <CODE> and the text is  not  formatted.
	      The <,> is the PRINT comma (16-column tab).

       -TZB   As ZXML, but <BR> (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.  Not  supported in the CP/M version, since there is no
	      Inform compiler for CP/M. 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
	      library 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 and CP/M,  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
	      UnQuill.

       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
	      occurred	in  listing  more  than 128 objects, locations or mes‐
	      sages.


       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-
	      image).	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.


TO DO
       Output location graphics for CPC6128 and C64 versions.


SEE ALSO
       spconv(1), inform(1)




			       10th October 2015		    UNQUILL(1)
