
                   Using and Installing Amiga NetHack 3.2
      (or Everything You Never Wanted to Know Before NetHacking)

	     Last Revision: 5 November 1996 for NetHack 3.2.2


0. Pre-intro for NetHack 3.2.2:
   Amiga-specific changes for 3.2.2:
     Some (but not all) known bugs fixed (volunteers welcome).
     Some HackWB bugs fixed - if it works for you, great.  If not,
      please use HackCli.
     The bug giving wierd usernames is fixed.

   We would like to thank each and every one of the people who took
   the time and effort to report bugs to us.  THANK YOU!

I. Introduction

I.A. Overview
    Welcome to Amiga NetHack!  If this is your first visit to our fair
    city, you are in for an amazing but dangerous journey; if you have
    visited us before, beware! the city has changed in many strange and
    subtle ways; it has also grown quite a bit.  This missive brings to
    light those mundane tasks which must be dealt with before beginning
    your journey; for those of you who are faced with the task of
    installing the pre-fabricated version of our town, section III
    (Installing Amiga NetHack 3.2) will guide you through the task at
    hand.  If you are ready to visit, the local visitors guide is in
    section II (Using Amiga NetHack 3.2); please also see the general
    guide packaged separately (the file "GuideBook").
    
    To all our visitors, a hearty Welcome! - and please be careful.

    [Those responsible for the previous paragraphs have been sacked.  The
    documentation has been completed at great expense in a more traditional
    style. -- The Management]

I.B. Getting Help
    If you have questions about strategy, weapons, or monsters, the best
    place to go for help is the Usenet newsgroup rec.games.roguelike.nethack.

    If you have problems with installation or think you have found a bug
    in the game, please report it by electronic mail to the development
    team at nethack-bugs@linc.cis.upenn.edu, where it will be routed to
    the appropriate person.  Include your configuration, the version of
    NetHack you are playing (use the 'v' command), whether or not you are
    using an official binary release (and if so which one) and as much
    specific information as possible.  As NetHack runs on many different
    machines, be sure to mention that you are playing the Amiga version.

I.C. Credits
    Olaf Seibert first ported NetHack 2.3 and 3.0 to the Amiga.  Richard
    Addison, Andrew Church, Jochen Erwied, Mark Gooderum, Ken Lorber,
    Greg Olson, Mike Passaretti, and Gregg Wonderly polished and extended
    the 3.0 and 3.1 ports.  Andrew Church, Ken Lorber, and Gregg Wonderly
    are responsible for the 3.2 port.

II. Using Amiga NetHack 3.2
    The short version: from the WorkBench click on HackWB and from the
    CLI invoke HackCli.

II.A. Sources of Information
    Where to go depends on what you want to find out.  If you want to find
    out about distributing NetHack, read the license (in NetHack:license
    or type ?i during the game).  For an introduction to NetHack, read
    the GuideBook file.  To find out what options are compiled into your
    copy of NetHack, type #v during the game.  Finally, for information
    during the game on all kinds of things, type ? and select from the
    menu.  Further information on HackWB is below and available from HackWB -
    press the Help key; more information on HackCli is in the NetHack
    ManPage and in section II.C.

II.B. The Amiga NetHack WorkBench Front End
    3.2.2 once again includes HackWB; it is better than it was, but is still
    buggy in some cases.

    The Amiga NetHack WorkBench Front End, HackWB, looks more or less like a
    WorkBench Drawer - and acts the same way.  Games start with double clicks
    and menus provide more detailed control of games and defaults.  On-line
    help is available - just press the help key.

    Just as with WorkBench itself, options for games are set using the Info
    menu item to modify ToolTypes.  Most common options can be set more 
    easily using buttons available via Info also.

    If necessary, you can adjust the following using the ToolTypes from the
    Info command:

	* OPTIONS=<options> - Options as available in the NetHack.cnf file.

	* HACKDIR=<directory> - Set NetHack working directory to be this
	  directory.

	* LEVELS=<levels> - Intermediate level saving device/directory.

	* PATH=<path> - To search for files such as rumors, help, etc.

	* CMDLINE=<args> - Arguments as passed on the CLI command line.
	  Note:  only the following flags are valid: n, X, D, and r.

	* SCORE <options> - Display the record of scores.  Options as
	  available on the CLI command line after a -s flag.

	* FONT=name.font:size - Set font used for text on screens which are
	  tall enough (>250 lines).

	* PENS=col0/col1/.../col7 - Set palette colors.

    Note that the NetHack.cnf file is read first, then the ToolTypes.  This
    means that the options specified in the NetHack.cnf act as defaults
    which can be overridden by an individual's personal icon's ToolTypes.
    Thus the system oriented entries (HACKDIR, LEVELS, and PATH) should
    generally be set only in NetHack.cnf.  NetHack.cnf should have default
    values for OPTIONS, which will generally be overridden by ToolTypes
    entries.

    Usually, most of the confusing options will be set in the NetHack.cnf
    file once when the game is installed and can be ignored after that.

II.C. The Amiga NetHack CLI Front End

    The CLI Front End, HackCli, provides the standard Unix-like command line
    interface to NetHack.  Unlike the Unix front end however, the CLI front
    end will ask if you want to play again (and optionally change the
    arguments) before exiting.  See the ManPage file for the standard Unix
    flags for NetHack.  In addition to those flags, Amiga NetHack accepts
    the flags -l to force non-interlaced mode and -L to force interlaced mode.
    HackCli is also used if you are running NetHack on a BBS - see the BBS
    section below.

II.D. Amiga-Specific Information for NetHack

    There are several options that are unique to the Amiga version of
    NetHack that may be specified in the NetHack.cnf file or on an
    OPTIONS line:

    altmeta     allows the ALT keys to function as META keys.  The default
                is altmeta.
    fast_map	use a faster display function - but only works with a limited
                set of display setups.  The default is fast_map.
    flush       flush discards all characters in the queue except the first,
                which limits typeahead accidents.  The default is !flush.
    silent      turn off the audio output.  The default is silent.

III. Installing Amiga NetHack 3.2

III.A. General Installation
    Installation should be easy - basically it consists of putting files
    where they belong and adding assigns to your startup.  If you are
    installing from the official binary distribution, simply unpacking
    each archive in the appropriate directory will put the files in the
    places they belong (note that the archives may have been split
    for distribution).

    IF YOU ALREADY HAVE A PREVIOUS VERSION INSTALLED YOU MUST DELETE THE
    OLD SAVE AND BONES FILES - THEY WILL NOT WORK!  This includes save
    and bones files from all versions of NetHack 3.1.

Will NetHack fit on your machine?
    NetHack 3.2 is large.  NetHack 3.2 is very large.  You will need:
    > Any standard series Amiga: 500, 600, 1000, 1200, 2000, 2500, 3000, 4000.
    > WorkBench 1.3 or 2.04 or later.  WorkBench 1.2 or 2.02 will NOT work;
      we will NOT be fixing that. 
    > At least 2 meg of RAM.  NetHack will NOT run in 1 meg.
    > Mass storage:  A hard drive with over 3 meg of free space is highly
      recommended.  NetHack will probably still run on one floppy - but it
      won't be nice and hasn't been tested recently.  Two floppies are almost
      enough.

Hard Disk Installation:
    Find the space
    	cd to wherever you want to install NetHack
	make a new directory to be the main NetHack directory:
	  makedir NH322
	  makedir NH322/NetHack
	  makedir NH322/HackExe
	  makedir NH322/HackExe2
	In S:User-Startup (under 2.0 or later) or S:Startup-Sequence
	(under 1.3):
	  assign NetHack: to the NetHack directory you created above.
	  assign HackExe: to the HackExe directory.
	  assign HackExe2: to the HackExe2 directory.
    Install the files
	Cd to the appropriate places then unpack the files:
	Archive 1 (the one this ReadMe came in), should be unpacked into
	NetHack:
	  cd NH322:
	  lz x NH32P0-1.lzh
	Archive 2 unpacks in two sections to two different places.
	  cd NH322:
	  lz x NH32P0-2.lzh HackExe/#?
	  lz x NH32P0-2.lzh HackExe2/#?

    Use the table in the next section to see where things should end up.
    Be sure that the file 8 ends up in NetHack:hack/8.  Note that NetHack 3.2
    has several dozen FEWER files than previous versions.
      
Floppy Installation:
	Caution: the floppy installation instructions have not been
	tested recently.  Please report any problems.
    Find the space
	Format five disks named:
	    NetHack
	    HackExe
	    HackExe2
	    NHsave
	    NHlevels
    Install the files
	Unpack the archives onto the disks.
	Archive 1 (the one this ReadMe came in), should be unpacked onto
	NetHack:.
	  cd NetHack:
	  lz x NH32P0-1.lzh
	Archive 2 unpacks in two sections to two different places.
	  cd HackExe:
	  lz x NH32P0-2.lzh HackExe/#?
	  cd HackExe2:
	  lz x NH32P0-2.lzh HackExe2/#?
      
    Use the table in the next section to see where things should end up.
    Be sure that the file 8 ends up in NetHack:hack/8.  Note that NetHack 3.2
    has several dozen FEWER files than previous versions.

    The files on each disk are now probably one level too far down
    (for example NetHack:NetHack.cnf is probably NetHack:NetHack/NetHack.cnf).
    This is how to fix that:
    Put the following lines into the file ram:fixit (be sure to delete the
    blanks from the start of the lines or this will NOT work!)
      .key x
      rename <x> /<x>

    For each of the disks NetHack, HackExe, and HackExe2, cd into the "inner"
    directory (for example "cd NetHack:NetHack") and execute these commands:
      list >ram:x lformat="execute ram:fixit %s" #?
      execute ram:x

    Finally, if you build a custom boot disk for NetHack, note that the
    following disk-based libraries are needed in LIBS:
	diskfont.library
	iffparse.library (if using graphics font)

Configuration
    Using your favorite text editor, edit NetHack:NetHack.cnf to match
    your system.  Check HackExe:NetHack.dir and be sure that the paths
    are correct (note that the C or D beginning the line is required and
    is not part of the file path).  The HackWB program uses two standard
    Amiga programs that must be installed in their standard places: C:Copy
    and C:Rename.  The icons for the documentation invoke SYS:Utilities/More
    and will probably need to be updated for your installation.

    Create the save file directory (makedir NetHack:save) and the levels file
    directory (makedir NetHack:levels) - if you use floppies than these
    directories will each be a different floppy.

    Create the score file (echo to NetHack:record) and, if desired, the log
    file (echo to NetHack:logfile).

III.B. File Location Table
NetHack:
	amii.hlp	default.icon	dlb		DlbMan
	DlbMan.info	Guidebook	Guidebook.info	hack.font
	hack/8		HackCli		license		ManPage
	ManPage.info	NetHack.cnf	NewGame.info	nhdat
	nhsdat		ReadMe		ReadMe.info	Recover
	Recover.info	RecoverMan	RecoverMan.info	

HackExe:
	NetHack.c01	NetHack.d00	NetHack.dir	

HackExe2:
	NetHack.c00

IV. BBS Interface
    The BBS mode is based on the standard NetHack tty port and is designed
    for use in a BBS setting - it is specifically not recommended for use
    on the console.  The current TTY mode has changed significantly since
    the preliminary version released with 3.1.2.  In particular, BBS mode
    now works with split binaries (only), and now supports multiple games
    in progress at the same time for multi-line boards (note however that
    any individual user should not be allowed to run two instances of
    NetHack at the same time).

    To set up NetHack for use with a BBS, set OPTIONS=windowtype:tty
    and unset DUNGEONS, TRAPS, and EFFECTS in NetHack.cnf.  Configure
    the BBS to expect I/O through stdin and stdout, and have NetHack
    invoked as:
       HackCLI :uid -u uname options...
    where uid is any string (without embedded spaces, colons, or slashes)
    that is unique for each BBS user and uname is some corresponding human-
    readable name for that user.  Uid is used in constructing file names
    to prevent collisions between simultaneous games and to prevent
    people from using other people's save files.  Uname is the name the
    character will have in the game and the name that will appear in the
    record file.

    The terminal is assumed to be a 24x80 ANSI-compatible terminal.
    The present version does not deal with situations such as low
    memory gracefully - as NetHack uses a considerable amount of
    memory this is particularly painful with multiple games in
    progress.  Sysops are reminded to be familiar with the recover
    utility, which may be needed from time to time and which should
    probably not be available directly to users.  Bug reports and
    suggestions for improvements are requested from the user community -
    this is still considered alpha software.

