UNGAC(1)							      UNGAC(1)



NAME
       ungac - Disassemble games written with Graphic Adventure Creator.


SYNOPSIS
       ungac { -option { -option  ... }} inputfile


DESCRIPTION
       UnGAC  takes  snapshot  files  of Spectrum games written with Incentive
       Software's Graphic Adventure Creator, and produces textual listings  of
       the  data tables which control them. From this it is possible to deter-
       mine how to solve the game (ie cheat :-)) or how to reconstruct	it  on
       another gamewriting system.

       spconv  (1)  can	 be  used to convert many Spectrum snapshot formats to
       .SNA.  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 and DOS. If you only want to run
       it under one operating  system,	the  command  FBSTRIP  UNGAC.COM  will
       remove the code which does not apply to your OS.


COPYING
       UnGAC is copyright 2006 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

       -V     Verbose. If part of  the	game  refers  to  a  particular	 room,
	      object,  word or message, the dump of that part of the game will
	      be annotated with the text of the respective room, object,  word
	      or message.

       -Sx    Do not output a section of text.	x can be:

	      A	     Adverbs.

	      B	     "Begin Here" room.

	      C	     Local conditions.

	      F	     User-defined font (if present).

	      G	     Location graphics.

	      H	     Low-priority conditions.

	      L	     Low-priority conditions.

	      M	     Messages.

	      N	     Nouns.

	      O	     Objects.

	      R	     Rooms.

	      V	     Verbs.


OUTPUT FORMAT (Normal mode)
       Output will be in the form of several tables:


   Verbs / Nouns / Adverbs table
       text of the verb. Synonyms (eg, GET and TAKE) have the same ID.


   Conditions tables:
       There are three condition tables. High priority conditions are executed
       before player input. After player input, local conditions for the  cur-
       rent room are executed, and then low-priority conditions.

       Therefore, you may see sequences of instructions such as this one (from
       the sample adventure, Ransom ): PUSH 7 VERB PUSH 5 NOUN AND  IF	(mean-
       ing:  continue  only if verb is 7 and noun is 5). In verbose mode UnGAC
       will try to keep track of the values on the stack and annotate instruc-
       tions with what the numbers refer to.

       In  the following table, S0 is the word at the top of the operand stack
       and S1 is the word below it.


   The opcodes are:
       PUSH x Pushes the constant x onto the operand stack.

       AND    Pops S0 and S1. Pushes the binary AND of S0 and S1.

       OR     Pops S0 and S1. Pushes the binary AND of S0 and S1.

       NOT    Pops S0. Pushes the logical NOT of S0; nonzero values go	to  0,
	      zero goes to 1.

       XOR    Pops S0 and S1. Pushes the binary XOR of S0 and S1.

       HOLD   Pops  S0.	 Waits	for  S0	 50ths	of a second, or until a key is
	      pressed.

       GET    Pops S0. Attempts to get object number S0. This can fail if  the
	      object  is not present, or already carried, or too heavy; if so,
	      the appropriate message is shown.

       DROP   Pops S0. Attempts to drop object number S0. Prints the appropri-
	      ate message if the object is not held.

       SWAP   Pops S0 and S1. Swaps the locations of these two objects. Unlike
	      GET, this does not do any checks of weight  or  player  carrying
	      capacity; the total weight carried remains unchanged.

       TO     Pops  S0	and  S1. Moves object S1 to location S0. As with SWAP,
	      does not recalculate the total weight carried.  The  GAC	sample
	      Ransom deals with this by dropping the object before using TO.

       OBJ    Pops S0. Displays the description of object S0.

       SET    Pops  S0. Sets marker number S0 to 1. Markers are boolean flags,
	      of which GAC has 256. Markers 0-3 are used by the system:	 0  is
	      set when a room is described, 1 should be set if the room is not
	      dark, 2 should be set if the player has a light  source,	and  3
	      should be set not to print the score at the end of a game.

       RESE   Pops S0. Sets marker number S0 to 0.

       SET?   Pops S0. Pushes 1 if marker S0 is 1, else 0.

       RES?   Pops S0. Pushes 1 if marker S0 is 0, else 1.

       CSET   Pops S0 and S1. Sets counter number S0 to value S1. Counters are
	      byte variables, of which GAC has 128. Counters 0,	 126  and  127
	      are  used	 by  the  system: 0 holds the score, and 126/127 are a
	      16-bit count of player turns.

       CTR    Pops S0, and pushes the value of counter S0.

       DECR   Pops S0, and decrements counter S0.

       INCR   Pops S0, and increments counter S0.

       EQU?   Pops S0 and S1. Compares the value of counter S0	with  S1,  and
	      pushes 1 if they're equal or 0 if not.

       DESC   Pops S0, and prints the description of room S0.

       LOOK   Prints the description of the current room.

       MESS   Pops S0. Prints message S0.

       PRIN   Pops S0. Prints its integer value.

       RAND   Pops S0. Returns a random number modulo S0.

       <      Pops S0 and S1. If (S1 - S0) < 0, pushes 0; else 1.

       >      Pops S0 and S1. If (S0 - S1) < 0, pushes 0; else 1.

       =      Pops S0 and S1. If (S0 = S1), pushes 1; else 0.

       SAVE   Saves the state of the game to cassette.

       LOAD   Loads the state of the game from cassette.

       HERE   Pops  S0.	 Pushes	 1  if	object	S0  is in the same room as the
	      player, else 0.

       AVAI   Pops S0. Pushes 1 if object S0 is either in the same room as the
	      player or carried, else 0.

       CARR   Pops S0. Pushes 1 if object S0 is carried, else 0.

       +      Pops S0 and S1. Pushes S0 + S1.

       -      Pops S0 and S1. Pushes S0 - S1.

       TURN   Pushes the contents of the turn counter.

       AT     Pops S0. Pushes 1 if the current room is S0, 0 otherwise.

       BRIN   Pops  S0. If object S0 exists and is not carried, move it to the
	      player's current location.

       FIND   Pops S0. Attempts to move the  player  to	 object	 S0's  current
	      location, if it exists and is not carried.

       IN     Pops S0 and S1. If object S0 is in room S1, push 1; otherwise 0.

       OP28   OP28 is a no-op.

       OP29   OP29 is a no-op.

       OKAY   Prints "Okay", stops all condition processing,  and  requests  a
	      new player input.

       WAIT   Stops all condition processing, and requests a new player input.

       QUIT   Asks the player if they want to quit. If they say yes,  end  the
	      game.

       EXIT   End the game without asking the player.

       ROOM   Pushes the current room number.

       NOUN   Pops S0. If the command line contains noun S0, pushes 1; else 0.

       VERB   Pops S0. If the command line contains verb S0, pushes 1; else 0.

       ADVE   Pops  S0. If the command line contains adverb S0, pushes 1; else
	      0.

       GOTO   Pops S0. Moves the player to room S0 and describes it.

       NO1    Pushes the number of the first noun found in the player's input.

       NO2    Pushes  the  number  of  the  second  noun found in the player's
	      input.

       VBNO   Pushes the number of the verb found in the player's input.

       LIST   Pops S0. Lists objects in that location.

       PICT   Enables graphics, if they are present.

       TEXT   Disables graphics, if they are present.

       CONN   Pops S0. Attempts to find a connection from the current location
	      using  verb  S0.	If a connection is found, pushes the ID of the
	      room it leads to; otherwise pushes 0.

       WEIG   Pops S0. Pushes the weight of object number S0.

       WITH   Pushes 32767, the ID of the "room" containing player  inventory.
	      This is used in conjunction with "LIST" to list inventory.

       STRE   Pops S0. Sets the maximum weight of objects carried to S0.

       LF     Prints a carriage return and line feed.

       IF     Pops  S0.	 If  S0 is zero, skip up to and including the next END
	      instruction.

       END    End of bytecode routine. Execution will continue with  the  next
	      routine if one is present.


   Objects.
       Each object has a weight, a starting position and a description.


   Rooms.
       Each  room  has	a  graphics ID (specifying which picture - if any - to
       display), a table of exits, and a textual description.

       Rooms are numbered from	1  to  9999.  Room  0  is  the	'limbo'	 where
       destroyed  and  non-created  objects  are  kept,	 and room 32767 is the
       player's inventory.


   Messages
       Message 239-255 are printed by the game engine in  appropriate  circum-
       stances.	 Messages 1-238 are only printed by condition code.


   First room
       Prints the number of the room in which the game starts.


   User-Defined Font
       Output as an X-Window bitmap, containing 96 8x8 characters (ASCII 32 to
       127).  This will only be present if the game is using a custom font.


   Location graphics
       Location graphics are output as a series of drawing instructions.


       BORDER n
	      Set the border colour to n.

       PLOT x,y
	      Plot a point at coordinates x,y. The coordinate  system  is  the
	      one  used	 by  Spectrum BASIC, so the bottom left-hand corner of
	      the drawable area is (0,48) and the  top	right-hand  corner  is
	      (255,175).

       ELLIPSE x1,y1 x2,y2
	      Draws  an	 ellipse,  whose  centre is at (x1,y1). It will extend
	      horizontally to (x2,y1) and vertically to (x1,y2).

       FILL x,y
	      Does a solid flood fill, starting at (x,y).

       BGFILL x,y
	      Does a  background  flood	 fill,	starting  at  (x,y);  Spectrum
	      attributes are drawn, but not pixels.

       SHADE x,y
	      As FILL, but shades with a 50% grey pattern.

       CALL gfx
	      Calls another graphics routine - for elements common to multiple
	      pictures, such as a border.

       RECT x1,y1 x2,y2
	      Draws a rectangle whose opposite corners are  at	the  specified
	      points.

       LINE x1,y2 x2,y2
	      Draws a line between the specified coordinates.

       INK i  Sets the Spectrum ink colour to use, 0-9.

       PAPER p
	      Sets the Spectrum paper colour to use, 0-9.

       BRIGHT b
	      Sets the Spectrum brightness level - 0, 1 or 8.

       FLASH f
	      Sets the Spectrum flash attribute - 0, 1 or 8.


EXAMPLES
       A>ungac -Oransom.txt ransom.sna

       Send the contents of Ransom to a text file.

       D:GAMESCTRUM>ungac -sh -sl -sc -sm -so -sr -sb -sf ransom.sna

       Display the verbs, nounds and adjectives used in Ransom.

       % ungac -v cursecit.sna | more

       List  the  workings  of	Cursed	Be  The City, annotating references to
       rooms, messages and so on.



BUGS
       Report any bugs to John Elliott (jce@seasip.demon.co.uk). If a particu-
       lar .sna file caused problems, include a copy of it.



VERSION HISTORY
       v0.1   Initial release.


TO DO
       Z-Code output format.

       Add the ability to run the game.


SEE ALSO
       spconv(1), unquill(1)




			       11 November 2006			      UNGAC(1)
