


UNQUILL(1)					       UNQUILL(1)


NAME
       unquill	-  Disassemble,	 play,	and convert games written
       with Quill.


SYNOPSIS
       unquill inputfile { -option { -option  ... }}


DESCRIPTION
       UnQuill takes snapshot files of	Spectrum,  CPC	and  Com­
       modore  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.

       CPC .SNA (used by CPCEMU)  and  Commodore  .S64	(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 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 MERCHANTABILITY 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



			22nd October 2002			1





UNQUILL(1)					       UNQUILL(1)


	      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 graph­
	      ics).   -L  selects  the	"late"	type; use this if
	      UnQuill gives nonensical output or  address  errors
	      without  the  -L	option.	 Games	produced with PAW
	      (Professional Adventure Writer) will probably cause
	      address  errors whether the -L option is present or
	      not.

       -TZ    Normally, game text is displayed in 32-column lines
	      and colour codes are omitted. -TZ switches to HTML-
	      like output ("ZXML") where colour codes are  repre­
	      sented 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 com­
	      pile 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 jzip (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



			22nd October 2002			2





UNQUILL(1)					       UNQUILL(1)


	      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.



			22nd October 2002			3





UNQUILL(1)					       UNQUILL(1)


   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




			22nd October 2002			4





UNQUILL(1)					       UNQUILL(1)


       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 num­
	      ber 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 control 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



			22nd October 2002			5





UNQUILL(1)					       UNQUILL(1)


	      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 carry­
	      ing it etc.

       WEAR    x
	      "Drop" object x ; checks that the player is  carry­
	      ing 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




			22nd October 2002			6





UNQUILL(1)					       UNQUILL(1)


       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  commands.	 For example, in the Very Big Cave Adven­
       ture, 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 param­
	      eter 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  cen­
	      tre 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.



			22nd October 2002			7





UNQUILL(1)					       UNQUILL(1)


       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 alterna­
	      tives.

       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 loading 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 descrip­
       tions 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





			22nd October 2002			8





UNQUILL(1)					       UNQUILL(1)


   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 num­
       ber; 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 charac­
       ters, which have ASCII values  144-164.	Some  games  (for
       example,	 Subsunk) use the UDGs to create location "graph­
       ics".

   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  coordi­
	      nates (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.




			22nd October 2002			9





UNQUILL(1)					       UNQUILL(1)


       MOVE x y
	      Move  by a number of pixels relative to the current
	      drawing position.

       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 nib­
	      bles; 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



			22nd October 2002		       10





UNQUILL(1)					       UNQUILL(1)


       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 loca­
	      tion is described.
	      Bit 7 is set to force the graphics to be	drawn  at
	      the next location description, at which point it is
	      automatically  cleared.  Thus  a	typical	 instance
	      would be:
		       LOOK  _	   Conditions:



			22nd October 2002		       11





UNQUILL(1)					       UNQUILL(1)


				   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 command line.

       Flag 34
	      holds  the  vocabulary  number  of  the second word
	      found in the command 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 subroutines. 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 mes­
       sages relating to verblibm.h; the first one of these shows
       the verb that caused the trouble, and the copy in the gen­
       erated 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 (support for timed  events  is  prefer­
       able).

       iqrun.z5	 is  actually  a  Quill interpreter written in Z-



			22nd October 2002		       12





UNQUILL(1)					       UNQUILL(1)


       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:GAMESCTRUM>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 retarded.sna -L -V -SL -SM | 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 tcom1.sna -l -t5 -otcom1.z5

       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 interchange­
       able between games.


       The automatic Inform translation is rather primitive.

       Report any bugs to John Elliott	(jce@seasip.demon.co.uk).



			22nd October 2002		       13





UNQUILL(1)					       UNQUILL(1)


       If  a particular .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 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. Further 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



			22nd October 2002		       14





UNQUILL(1)					       UNQUILL(1)


	      game has	multiple  fonts,  all  of  them	 will  be
	      extracted	 rather	 than just the currently selected
	      one.


TO DO
       Output location graphics for CPC6128 and C64 versions.


SEE ALSO
       spconv(1), inform(1)














































			22nd October 2002		       15


