home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d7xx / d716 / zmachine.lha / ZMachine / zmachine.doc < prev    next >
Text File  |  1992-08-19  |  12KB  |  364 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                          ZMachine   1.0.3
  11.  
  12.             A ZIL Interpreter for the Commodore Amiga
  13.  
  14.                             Kent Dalton
  15.  
  16.            Ported from the original UNIX version written by
  17.                           leo@marco.UUCP  
  18.  
  19.                 Amiga Port Copyright 1992 by Kent Dalton
  20.  
  21.   Read "Copying" section of this manual for redistribution information.
  22.  
  23.  
  24.  
  25.  
  26.  
  27. 1.    Introduction
  28.  
  29. ZMachine is a program which can interpret "Zork Implementation
  30. Language" (ZIL) data files.  ZIL is the language used by the
  31. interactive fiction series of games from Infocom, Inc.  (a subsidiary
  32. of Activision/MediaGenic).  Interactive Fiction and Interactive This
  33. program does not incorporate any code from Infocom software and is not
  34. associated with or a product of Infocom, Inc.  All game names mentioned
  35. in this document are trademarks of Infocom.  ZMachine can interpret
  36. normal interactive fiction data files.  It is not compatible with
  37. interactive fiction plus (games with graphics, i.e.  Beyond Zork, Zork
  38. Zero,etc).
  39.  
  40. This version of ZMachine was ported from a UNIX version.  It was ported
  41. using a PD termcap library and GCC 2.1 (Many thanks to Markus Wild for
  42. porting GCC to the Amiga!).  It has some customizations for the Amiga
  43. environment which are detailed for this enviroment.
  44.  
  45. This program comes with no warranty express or implied.  Use at your
  46. own risk.
  47.  
  48.  
  49. 2.    Copying
  50.  
  51. The Amiga version of this program is Copyright \copyright 1992 by
  52. Kent Dalton.  Non-commercial redistribution of the program is allowed
  53. provided all files are included in the distribution in unmodified
  54. form. Public Domain and Freely Distributable libraries may change
  55. handling, shipping, and copying fee charges to distribute the program
  56. provided the above condition is met. I will consider honoring E--Mail
  57. requests (see ``Bug Reports'' section for E--Mail address) for source
  58. code for this Amiga version. Requestors who add new functionality or
  59. do bug fixes to ZMachine are required to return those changes to me.
  60. I think it will be best for the user base, in general, to have a
  61. single most robust and featureful version available via one source.
  62. Contributors to ZMachine development will be fully credited.
  63.  
  64. I will only distribute source to the the Amiga version, however.  The
  65. original UNIX version is available via anonymous FTP (If you don't
  66. know how to find things available for ftp, please learn about the
  67. archie archive search server, I'm getting far too much ZMachine
  68. related mail as is, I do have a day job ya know! :^))
  69.  
  70. 3.    Features
  71.  
  72. This program provides a number of features not available in the Infocom
  73. ZIL interpreter:
  74.  
  75.  
  76.       o  Support for workbench screens larger than the default NTSC
  77.          (or PAL) hires (640x200) via the termcap enviroment variable.
  78.  
  79.       o  Command history via the arrow keys.
  80.  
  81.       o  Function Key support.
  82.  
  83.       o  Emacs-like command line editing.
  84.  
  85.       o  Support of the Amiga clip board for cutting and pasting text.
  86.  
  87.       o  Support for automatic location of game files for hard disk users
  88.  
  89.       o  Ability to use Interactive Fiction files from other computers.
  90.          (i.e. IBM, Atari ST, etc).
  91.  
  92.       o  Special support for running Infocom games on a BBS.
  93.  
  94. 4.    System  Requirements
  95.  
  96. ZMachine was ported using an Amiga 3000 with 6Mb RAM and AmigaOS
  97. 2.04.  I do not know if it works with AmigaOS 1.3.  If it does not,
  98. no effort will be made to port it to 1.3 (see "Copying" section for
  99. info on how to obtain source code.). The ixemul.library definitely
  100. requires the 2.04 mathieeesingbas.library, ZMachine does not use
  101. floats though, so you might be able to get away with copying over
  102. another library in its place (or you could get the library from
  103. someone who has 2.04, although I'm not sure if this is legal or not.)
  104.  
  105. NTSC and PAL displays and all Motorola 680x0 CPU's are supported.
  106.  
  107. The amount of memory used is detrmined by the game being played.  The
  108. average seems to be on the order of 256K.
  109.  
  110.  
  111. 5.    Installation
  112.  
  113.      1.  Copy termcap file to S: directory.
  114.  
  115.  
  116.      2.  Set TERM environment variable for proper screen type i.e.  
  117.          setenv  TERM  amigalace.
  118.          You'll probably want to add this to your user-startup 
  119.          (or startup-sequence) file.
  120.  
  121.      3.  Copy ixemul.library from the libs directory to LIBS:
  122.  
  123.      4.  If  you  are  using  a  68000  or  68010  CPU  you'll  probably
  124.          want  to  copy  zmachine.68k over zmachine since `zmachine' is
  125.          the 68020+ version.
  126.  
  127.      5.  If your termcap entry is smaller than 640x400 (amigalace) you'll
  128.          also want to edit the dimensions of the WINDOW= tool type for the
  129.          zmachine.info file
  130.          (this controls the size of the window popped by zmachine (and the
  131.          `iconified' window size also.))
  132.  
  133.       Hard  Disk  Users  Note:
  134.  
  135. If you are using a hard disk you may want to assign LTOI: to the
  136. directory where
  137.  
  138. your infocom games are located.
  139.  
  140.       ZMachine assumes a directory structure of:
  141.  
  142.                  LTOI:  ->GameName1->Story.Data
  143.                         ->GameName2->Story.Data
  144.                             .
  145.  
  146.                             .
  147.  
  148.                             .
  149.  
  150.                          ->GameNameN->Story.Data
  151.  
  152.       when using this directory structure, ZMachine will be able to
  153. automatically locate the main data file for the game you wish to play
  154. and automatically place and retrieve game save files from the directory
  155. of that specific game as well.
  156.  
  157.       You'll probably want to rename the Zork 1-3 data files to
  158. Story.Data as well. They work properly with ZMachine, Infocom just
  159. named them differently.
  160.  
  161.       I recommend copying zmachine and zmachine.info to LTOI: as well.
  162.  
  163.  
  164. 6.    Running  ZMachine
  165.  
  166.  
  167. 6.1.    From  Workbench
  168.  
  169. An icon will be opened and zmachine will prompt you for a game name.
  170. If you have not assigned LTOI: to adirectory, you must type in the full
  171. name of the file you wish to run.  If you are you using zmachine with
  172. the LTOI: assign and directory structure mentioned in the Hard Disk
  173. Installation notes above, you can just type the name of the games
  174. directory that you wish to play.  For example: if you type `moonmist',
  175. ZMachine will attempt to open: LTOI:moonmist/Story.Data as the game
  176. file.  From then on, the default SAVE/RESTORE path will
  177. be LTOI:moonmist, this way, you don't get a whole bunch of files mixed
  178. up in your LTOI: directory.
  179.  
  180.  
  181. 6.2.    From  CLI
  182.  
  183. CLI startup works similar to the UNIX version. Switches are
  184. preceeded by a '--' character and switches which take arguments are
  185. seperated from the argument by whitespace. Here is the usage
  186. information with all the switches ZMachine understands:
  187.  
  188. Usage:  zmachine  [-p  protocolfile]  [-w  protocol  linewith]
  189.         [-s  storyfile]  [-r  restorefile] [-cli]
  190.         [-bbs savepath] [-nowrap] [ -li lines] [-co columns]
  191.         [<storyfile>] [<restorefile>]
  192.  
  193. -p protocolfile     : send output after script command to protocolfile
  194. -w protocol linewith: set protocol linewith to linewith
  195. -s storyfile        : use storyfile
  196. -r restorefile      : restore savefile restorefile before starting game
  197. <storyfile>         : use storyfile
  198. <restorefile>       : restore restorefile
  199. -cli                : ZMachine will not prompt user to hit return on exit.
  200. -nowrap             : Do not handle long lines the "amiga" way. May be
  201.                       necessary for running on some non-amiga terminals
  202.                       over serial connection.
  203. -bbs                : BBS mode. Allows exit on CTRL-C, restricted save
  204.                       path, and automatically invokes -cli mode.
  205. -co                 : Override the termcap column entry.
  206. -li                 : Override the termcap lines entry.
  207.  
  208. If you call zmachine without arguments, it trys to open the file
  209. Story.Data on the current working directory. 
  210.  
  211.       Notice the default file extensions.  Zmachine checks and enforces
  212. these (case-sensitively) when started from CLI.  If lots of people are
  213. bothered by this, I can change it.
  214.  
  215.  
  216. 7.    Command  Editing
  217.  
  218.  
  219. Editing Keys:
  220.  
  221. Cursor left        :    ^B (also Left-Arrow on Amiga)
  222. Cursor right        :    ^F (also Right-Arrow on Amiga)
  223. Up in history        :    ^P (also Up-Arrow on Amiga)
  224. Down in history        :    ^N (also Down-Arrow on Amiga)
  225. Delete left        :    0x7f, 0x08
  226. Delete right         :    ^D (also BackSpace and Del on Amiga)
  227. Start of line        :    ^A
  228. End of line        :    ^E
  229. Kill to end of line    :    ^K
  230. Kill to start of line    :    ^X
  231. Program function key    :    ^I (TAB)
  232. Undo            :    ^Y
  233. Function key 0-9    :    F1-F10
  234.  
  235.  
  236. Using the Clipboard:
  237.  
  238.  
  239.      1.  Select text with mouse
  240.  
  241.      2.  Hit Amiga-C to Cut text
  242.  
  243.      3.  Hit Amiga-V to paste text at cursor position
  244.  
  245.  
  246.  
  247. 8.    BBS  Mode
  248.  
  249.  
  250. BBS Mode causes three features to be active:
  251.  
  252.  
  253.      1.  CLI mode becomes active so the user is not prompted for a return 
  254.          keystroke on exit.
  255.  
  256.      2.  ZMachine will recognize a Control-C character as an exit signal.
  257.          This provides  a  way  for  the  sysop  to  signal  the  program
  258.          to  exit  on  time-out or disconnect.
  259.  
  260.      3.  It restricts the save path, so users can only write to or read
  261.          from specific files in a sysop specified directory.  This keeps
  262.          a user from unintentionally (or maliciously) writing to important
  263.          system files, etc.  When the user tries to save or restore the
  264.          game, they are prompted for a save position [0-9], which is used
  265.          to formulate the save/restore file name.  The file name is 
  266.          formulated by first appending the save position to the save file
  267.          path specified with the -bbs option, an extension of ".sav" is
  268.          then appended to that.  Examples:
  269.  
  270.                 zmachine  -bbs  LTOI:saves/
  271.  
  272.          Yields save file names of:
  273.  
  274.                 LTOI:saves/0.sav
  275.                 LTOI:saves/1.sav
  276.                 .
  277.                 .
  278.                 LTOI:saves/9.sav
  279.  
  280.          If the user name and game name are put in the savepath, the sysop
  281.          can make multiple games available to the users:
  282.  
  283.                zmachine  -bbs  BBS:userfiles/kentd/moonmist
  284.  
  285.          Yields:
  286.  
  287.                BBS:userfiles/kentd/moonmist0.sav
  288.                BBS:userfiles/kentd/moonmist1.sav
  289.                .
  290.                .
  291.                BBS:userfiles/kentd/moonmist9.sav
  292.  
  293. This scheme should provide enough flexibility for most BBS operators who
  294. wish to make ZMachine interpreted games available to their users, provided
  295. their BBS software is reasonably configurable.
  296.  
  297. 9.    Caveats  and  Known  Bugs
  298.  
  299. Lurking Horror will hang when it tries to do the Amiga sound stuff.  Do
  300. not use this program with the Amiga version of Lurking Horror (you can
  301. use it with versions of Lurking Horror from other computers' versions
  302. which do not do sound, I've used it with the Atari ST version for
  303. example.)
  304.  
  305. ZMachine save game files are incompatible with game save files created
  306. by the Infocom ZIL interpreter and vice versa.
  307.  
  308.  
  309. 10.    Reporting  Bugs,  Comments,  and  Questions
  310.  
  311. I have tested this program with most of the non-plus interactive
  312. fiction games from Lost Treasures and several others from other
  313. computers and they have all worked great so far.  Let me know if you
  314. find any that do not.
  315.  
  316. Feel free to send Bug reports, comments, or questions to me via
  317. E-Mail:
  318.  
  319.  
  320. Kent.Dalton@FtCollinsCO.NCR.com
  321.  
  322.  
  323. I will try to respond as time allows.
  324.  
  325. I hope you enjoy this program!  I use it for all of my interactive
  326. fiction now!
  327.  
  328.  
  329. 11. Revision History
  330.  
  331. Version 1.0.0
  332.  
  333.    o Original release
  334.  
  335. Version 1.0.1
  336.  
  337.    o ZMachine now resets terminal characteristics on exit.
  338.  
  339.    o Fixed "character wrap" bug on Amiga terminals.
  340.  
  341.    o Added cli switch for no prompt on exit.
  342.  
  343.    o Added nowrap switch that handles line wrap old way. (May be
  344.      necessary for some non-Amiga terminals or running over serial
  345.      line, experiment both ways to see which works best.)
  346.  
  347.    o Tested Function Key support (works).
  348.  
  349. Version  1.0.2
  350.  
  351.    o BBS mode added:  CTRL-C handling, Quick exit, and restricted save
  352.      paths.
  353.  
  354.    o Internal argument parsing routines completely rewritten.  The old
  355.      ones were seriously brain-dead, IMHO.
  356.  
  357. Version 1.0.3
  358.  
  359.    o Command line override of termcap column and line entries added 
  360.      (user request).
  361.  
  362.    o No longer forces extensions for filenames. (misfeature) 
  363.  
  364.