                        NetHack 5.0 for Atari ST/TT/Falcon
                        ===================================

Requirements
------------
    - Atari ST-class machine (ST, STE, Mega ST/STE, TT, or Falcon)
      with at least 6 MB of RAM.
    - GEM AES (TOS, MagiC, or FreeMiNT/XaAES).
    - At least VGA-class video: 640x480 with 16 colours.

    Known to work:
      - Hatari (https://hatari.tuxfamily.org/) with TOS 2.06 (ST)
        and TOS 3.06 (TT).
      - MagiC 6.2 under MagiCMac on macOS.
      - MagiC under magic-on-linux
        (https://gitlab.com/AndreasK/magiclinux).

    Currently known not to work (to be investigated):
      - EmuTOS.

Supported display modes:
    - 640x480 with 16 colours (VGA minimum)
        - Atari TT  "TT-Mid"
        - Atari Falcon  "VGA 4-plane"
        - or any graphics-card setup providing equivalent output
    - 640x480 with 256 colours
        - Atari Falcon  "VGA 8-plane"
        - NetHack uses the 32-colour NH32.IMG tile sheet here;
          the extra display pens are left alone for GEM.
    - ST High (640x400 monochrome) -- experimental, ASCII map
      only.  The monochrome tile sheet ships in the package but
      the small screen and lack of colour make ASCII the
      practical choice on this video mode.
    - ASCII text in any of the above via the F2 toggle.


Installation
------------
Unzip NH500ST.ZIP on the Atari side -- not on the Linux/Windows
host -- because some unzippers translate line endings inside the
archive and corrupt nhdat.

The archive expands into a self-contained game directory:

    nethack.prg         GEM application
    nhdat               packed game data (Lua scripts + tile mapping)
    nethack.cnf         default configuration
    gem_rsc.rsc         GEM dialog resources
    NH2.IMG             monochrome tile sheet (Atkinson dithered)
    NH16.IMG            16-colour tile sheet
    NH32.IMG            32-colour tile sheet
    TITLE.IMG           splash image (colour)
    TITLE2.IMG          splash image (monochrome)
    RIP.IMG             tombstone image
    README.txt          this file
    license, symbols, nethack.txt
    levels/, save/      empty, written to during play

Double-click nethack.prg to start.


Display Modes
-------------
By default the game starts in tile mode.  Press F2 at any point
during play to toggle between tiles and ASCII.

In 4-plane (16-colour) video modes the VDI palette is rewritten
at startup to match the tile palette baked into NH16.IMG.  In
8-plane (256-colour) modes pens 0..15 are left alone and the
32-colour NH32.IMG palette is loaded into pens 16..47, so GEM
keeps its standard system colours.  In ST High (monochrome)
NetHack runs in ASCII mode; the Atkinson-dithered NH2.IMG ships
in the package but the small screen makes ASCII the practical
choice there.

To force ASCII text mode by default, edit nethack.cnf:

    #OPTIONS=!ascii_map
    OPTIONS=ascii_map


Configuration
-------------
See the comments in nethack.cnf.  Key options:

    HACKDIR     game directory (default: nethack.prg's location)
    LEVELDIR    where to write level files (default: levels)
    SAVEDIR     where to write save files  (default: save)

Useful gameplay options:

    OPTIONS=color,hilite_pet,number_pad
    OPTIONS=autopickup,pickup_thrown
    OPTIONS=pickup_types:$?!/="+
    OPTIONS=menucolors          - colored inventory items

Menu colour examples (after OPTIONS=menucolors):

    MENUCOLOR=" cursed "=red&bold
    MENUCOLOR=" blessed "=cyan
    MENUCOLOR=" uncursed "=black


Notes
-----
Save files and bones files from earlier NetHack versions will
not work with 5.0.

If you want to build NetHack for Atari from source, see
sys/atari/README.Crosscompiling.
