interpreters/nitfol/nitfol.6

   1 .TH NITFOL 6
   2 .SH NAME
   3 nitfol \- Z-code interpreter and debugger.
   4 .SH SYNOPSIS
   5 .B nitfol
   6 .I "[options] file"
   7 .SH DESCRIPTION
   8 This manpage was generated from bits of the info page.  See the info page for complete documentation.
   9
  10 Nitfol is a portable interpreter for Z-machine code, the game format used by Infocom and more recently, Inform <http://www.gnelson.demon.co.uk/inform.html>.  Nitfol handles versions one through eight of the format, and attempts to comply with version 1.0 of the Z-machine specification.
  11
  12 You will need game files to use nitfol.  The ``if-archive'' contains a large collection of these, available at <ftp://ftp.gmd.de/if-archive/games/zcode/> or at the USA mirror <http://ifarchive.org/indexes/if-archiveXgamesXzcode.html>.
  13
  14 This manual describes how to use nitfol and how it differs from other Z-machine interpreters.  This manual was written with unix-like systems in mind; ignore that which does not apply to your platform.  Comments on and corrections for this manual and nitfol are appreciated and should be sent to <nitfol@my-deja.com>.
  15
  16 .SH OPTIONS
  17 .TP
  18 .B \-ignore, \-no\-ignore, \-i
  19 Ignore Z-machine strictness errors.  Normally nitfol checks for illegal and undefined Z-machine behaviour and alerts the user.  If you're playing someone else's buggy game, this can be annoying and you should use this option.
  20 .TP
  21 .B \-fullname, \-no\-fullname, \-f
  22 For running under Emacs or DDD.  Tells nitfol to give machine-recognizeable markers when stack frames are displayed instead of displaying the line. Only useful if you are using nitfol as an inferior debugger.
  23 .TP
  24 .B \-command \fIfile\fB, \-x \fIfile
  25 Read commands from this file.  Load a script from a file for playback in the game.
  26 .TP
  27 .B \-pirate, \-no\-pirate, \-P
  28 Aye, matey.  Make the piracy opcode not branch, letting the game know the game disc is not ``genuine.'' Infocom never used this opcode and neither should you, but if obscurity amuses you...
  29 .TP
  30 .B \-quiet, \-no\-quiet, \-q
  31 Do not print introductory messages.  For GDB compatibility.
  32 .TP
  33 .B \-spell, \-no\-spell
  34 Perform spelling correction.  Normally Z-machine games are unforgiving of typos (though they do have an \fBoops\fP command). If you type in a word which isn't in the game's dictionary and have typo correction enabled, nitfol will search for a word which is off by one letter by a substitution, deletion, insertion or transposition.
  35 .TP
  36 .B \-expand, \-no\-expand
  37 Expand one letter abbreviations.  Early Z-machine games don't include `x' as a synonym for `examine' and such.  If the first word in a sentence is one letter long and not recognized by the game, this will attempt to expand it to a full word.
  38 .TP
  39 .B \-symbols \fIfile\fB, \-s \fIfile
  40 Specify symbol file for game.  If you want to perform source-level debugging, you will need to specify a symbol file, which contains the names of variables and tells nitfol how source code corresponds to object code.
  41 .TP
  42 .B \-tandy, \-no\-tandy, \-t
  43 Censors some Infocom games.  Some version 3 games perform minor wording changes when this bit is set to appease the sensitivity of Tandy Corporation.
  44 .TP
  45 .B \-transcript \fIwfile\fB, \-T \fIwfile
  46 Write transcript to this file.  This transcript begins as soon as the game starts.
  47 .TP
  48 .B \-debug, \-no\-debug, \-d
  49 Enter debugger immediatly.  Imitate GDB by not automatically starting the story.
  50 .TP
  51 .B \-prompt \fIstring\fB
  52 Specify debugging prompt.  This is the prompt nitfol prints when it is waiting for a debugging command (as opposed to the > the game story prints when waiting for a game command).  DDD requires this to be `(gdb) '.
  53 .TP
  54 .B \-path \fIstring\fB
  55 Look for games in this directory.  If nitfol cannot find the requested game in the current directory, it looks through the directories listed in the given colon separated string.  The directories specified here are also used to search for gamefiles from saved games.   If this option is not used, nitfol looks at the \fBINFOCOM_PATH\fP environment variable.
  56 .TP
  57 .B \-autoundo, \-no\-autoundo
  58 Ensure \fB@save_undo\fP is called every turn.  If a turn passes with no \fB@save_undo\fP between, this option performs the \fB@save_undo\fP automagically.  Could cause problems with some games which have a different concept of a turn.
  59 .TP
  60 .B \-stacklimit \fInumber\fB, \-S \fInumber
  61 Exit when the stack is this deep.  If a game is infinitely recursing, nitfol will allocate large amounts of memory and take a long time before the problem is reported.  This option makes it fatal to recurse more than the given number of stack frames.  Setting this to 0 makes nitfol allow as many as fit contiguously in memory.  The Z-machine Standards Document recommends games use no more than 1024 words of total stack (frames and pushed data) in ZIP, which roughly works out to 90 routine calls deep.
  62 .TP
  63 .B \-alias \fIstring\fB, \-a \fIstring
  64 Specify an alias.  Adds an alias which will be expanded in read lines before tokenisation.  The alias is of the form \fIname\fP \fIvalue\fP; you will need to use quotes around it on the commandline.
  65 .TP
  66 .B \-ralias \fIstring\fB
  67 Specify an recursive alias.  Adds an alias whose result is checked for further alias expansion.  Identical syntax to adding a normal alias.
  68 .TP
  69 .B \-unalias \fIstring\fB
  70 Remove an alias.  Removes an alias previously added by -alias.  Useful for removing aliases in preference files.
  71 .TP
  72 .B \-random \fInumber\fB, \-r \fInumber
  73 Set random seed.  Normally the random number generator is initialized with the time of day.  If this option is used with a non-zero argument, the given number will be used to initialize the generator and for \fB@random 0\fP.
  74 .TP
  75 .B \-mapsym \fIstring\fB
  76 Specify mapping glyphs.  Nitfol draws maps using ASCII characters; you can choose which characters it uses to draw rooms.  Defaults to `*udb@UDB+', which is, in order: empty room, room with down exit, room with up exit, room with up and down exits, room with player, room with player and up exit, room with player and down exit, room with player and up and down exits, bend symbol.
  77 .TP
  78 .B \-mapsize \fInumber\fB
  79 Specify map size.  Determines the number of lines to be used for the map.
  80 .TP
  81 .B \-maploc \fIstring\fB
  82 Specify map location.  Nitfol creates a Glk window for the map it generates.  The map can be placed `above', `below', to the `right', or the `left', of the main game window.  Follow this option with one those locations.
  83 .TP
  84 .B \-terpnum \fInumber\fB
  85 Specify interpreter number.  Each port of Infocom's Z-machine interpreter was given a number.  `1' for their own DECSystem-20, `2' for Apple IIe, `3' for Macintosh, `4' for Amiga, `5' for Atari ST, `6' for IBM PC, `7' for Commodore 128, `8' for Commodore 64, `9' for Apple IIc, `10' for Apple IIgs, `11' for Tandy Color.  Giving this option makes nitfol claim to be running on the specified system.  A few games change their behaviour slightly depending on which machine type they run.  By default nitfol claims to be on an Apple IIe, as this makes Beyond Zork not do character graphics.
  86 .TP
  87 .B \-terpver \fIstring\fB
  88 Specify interpreter version.  Infocom's interpreters were given versions, typically a capital letter.  Nitfol defaults to `N', Frotz uses `F', and ZIP uses `B'.  Any single character version is allowed.  Multicharacter options are read as a number instead of an ASCII character.  Only known effect upon games is the letter printed by banners and the `version' command.  Version 6 games interpret this as a number instead of a letter.
  89 .SH BUGS
  90
  91 A nitfol bug is any behaviour which makes nitfol reliably misbehave, with the exceptions of bugs in Glk libraries.  These include: anything which makes nitfol crash (other than when nitfol reports `FATAL' errors), anything which causes nitfol to contradict the Z-machine standards documents (except for optional enhancements like spelling correction and debug mode), any buffer overflows, and anything which makes nitfol infinite loop other than infinite loops in the game itself.
  92
  93 Before reporting a bug, make sure the bug is not listed below and your copy of nitfol is not compiled with `-DFAST'.  Please report the version of nitfol, your system type and a series of commands which reliably cause the bug.
  94
  95 Nitfol is lacking:
  96 .IP \(bu
  97 Graphical font (\fIBeyond Zork\fP)  (should use images for this)
  98 .IP \(bu
  99 Terminating character support (mostly \fIBeyond Zork\fP)
 100 .IP \(bu
 101 Reverse video, full color (should querry Glk more aggressively)
 102 .IP \(bu
 103 Unicode support
 104 .IP \(bu
 105 keypad character codes
 106 .IP \(bu
 107 its own random number generator (relies on system one)
 108 .PP
 109
 110 Nitfol does incorrectly:
 111 .IP \(bu
 112 Play is not paused to wait for sounds to complete in \fIThe Lurking Horror\fP.
 113 .IP \(bu
 114 Pictures and text are not placed correctly for v6 games.
 115 .IP \(bu
 116 block quotes are placed in the upper window, so \fBcheapnitfol\fP can't see them.
 117 .IP \(bu
 118 Corrupted save files may make nitfol do bad things.
 119 .IP \(bu
 120 Should figure out a way to handle buggy games like \fIAMFV\fP and \fIVaricella\fP which assume the upper window is 80 columns wide.
 121 .IP \(bu
 122 Doesn't catch header writing other than \fB@storeb\fP and \fB@storew\fP.
 123 .PP
 124
 125 Debugger problems:
 126 .IP \(bu
 127 Sometimes says there's no code at a location where it could be clever and
 128   find some.
 129 .IP \(bu
 130 \fBofclass\fP, superclass not implemented.
 131 .IP \(bu
 132 Should perform more sanity checks everywhere.
 133 .IP \(bu
 134 Lots of useful commands not yet implemented.
 135 .IP \(bu
 136 \fIobject\fP.\fIfunction\fP is handled incorrectly, both for assignments and calls.
 137 .IP \(bu
 138 Assumes you know what you're doing, so \fBquit\fP, \fBrun\fP, etc., don't prompt you for confirmation.
 139 .PP
 140
 141 Automapping problems:
 142 .IP \(bu
 143 Doesn't work well for random destinations (the forest in \fIAdvent\fP)
 144 .IP \(bu
 145 \fB@get_cursor\fP doesn't return the correct value during automapping since output is disabled.
 146 .IP \(bu
 147 Requires too much work for the end-user; should put in stuff to make it figure out the location global in 95% of games.
 148 .IP \(bu
 149 Doesn't really work if multiple locations are coded as being in the same room (long road in \fIEnchanter\fP).
 150 .IP \(bu
 151 Doesn't show exits which go nowhere, but change the game.
 152 .IP \(bu
 153 Perhaps should use graphics windows when available.
 154 .IP \(bu
 155 Movement causing teleportation confuses it.
 156 .IP \(bu
 157 Reincarnation handling isn't optimal.
 158 .IP \(bu
 159 Still very buggy.
 160 .IP \(bu
 161 It's too slow.
 162 .IP \(bu
 163 Should realize it can add extra bends (especially in one-way passages).
 164 .IP \(bu
 165 Should be able to output nice-looking Postscript.
 166 .IP \(bu
 167 Should store map in saved games (wait until automapping code stabilizes).
 168 .PP
 169
 170 .SH "SEE ALSO"
 171 .RB "`\|" nitfol "\|'"
 172 entry in
 173 .B
 174 info;
 175 .BR frotz (6),
 176 .BR txd (1).
 177 .SH AUTHOR
 178 nitfol was written by Evin Robertson, who can be reached at nitfol@my-deja.com.