glHack README
=============

by Andrew Apted, updated to NetHack 3.4.3 by James Bentler.

Version: 1.2

Last revised: 24th June 2004.


This is the main README file for glHack.  The other glHack-related
documents are NEWS.GL, CHANGELOG.GL and TODO.GL.  Note that the
original NetHack docs haven't been changed, and can be inconsistent
with glHack in some places (especially the installation instructions,
like sys/unin/Install.unx, which should not be followed).

For newcomers to NetHack, the file "doc/Guidebook.txt" is essential
reading, covering all aspects of the game itself.


GLHACK INTRO
------------

glHack is a port of the game NetHack, using hardware acceleration via
OpenGL(R) to render the 2D tile graphics.  It uses LibSDL as the video
and input library.  There is good support for software rendering too.
 
glHack is just one of the many NetHack front-ends.  Others include
the original text-terminal (TTY) version, one for the X Window
System, and one for GNOME called GnomeHack.

glHack site: http://glhack.sourceforge.net/

Official NetHack site: http://www.nethack.org/


NEWS
----

The news has been moved out, please read the NEWS.GL file.

See also CHANGELOG.GL for all the gory details.


IMPORTANT CHANGES FOR NETHACK 3.4.0
-----------------------------------

Firstly, NOTE WELL: if you are updating from a version prior to 0.9.5,
you cannot use "make update" with this release.  The bone and save
files changed format in the new NetHack version.  If you have a good
game in progress, finish it before re-installing.

Secondly, some glHack options have been replaced or removed, because
NetHack 3.4.0 introduced some standard options which do the same thing
(the "WINCAP" options).  For backwards compatibility, glHack still
accepts the old options in the config file, but not on the command
line.  These options are:

   tilesize      : use tile_height instead.
   mapfont       : use font_size_map instead.
   textfont      : use font_size_message instead.
   msglines      : use vary_msgcount instead.

The replacements need to be put on an "OPTIONS" line in the config
file (instead of "GL_OPTIONS").  For example:

before:

   GL_OPTIONS=tilesize:16
   GL_OPTIONS=msglines:4

after:

   OPTIONS=tile_height:16
   OPTIONS=vary_msgcount:4


INSTALLATION
------------

The glHack source comes pre-configured for a Linux system.  The
install directories and permissions follow the example of the Debian
nethack and gnomehack packages (see below).  (P.S. Debian recently
changed to /var/games/nethack).

The following commands should install everything:

   make

   su -c 'make install'

and then just type "glhack" in an X terminal to play.

The following manpages will be available:

   glhack(6)   glhackrc(5)   nethack-guidebook(6)

If your OS is a recent Debian or Mandrake Linux, you can install
glHack into the desktop menus using one of these commands:

   su -c 'make debian_install'
or
   su -c 'make mandrake_install'


Installation directories:
-------------------------

   /usr/lib/games/glhack/ : all the read-only game data goes here,
                            like dungeon files and PNG images.

   /var/lib/games/glhack/ : the persistent game data goes here, such
                            as the high score table and saved games.
   
   /usr/bin/ : the glhack executable goes here.  It's really just a
               script that sets up some important shell variables
               and runs the real executable in the read-only dir.
 
Installation permissions:
-------------------------

   The executable is run setgid, with group "games".  This is needed
   so that it can write/modify the persistent game files.  More
   precisely, the owner/group is root.games with mode 02755.
  
   The read-only files are root.games with mode 0644.

   The directory in /var holding the persistent data also has the
   setgid bit, with group "games", with mode 02775 (i.e. group
   writable).  This means files creating in that directory will be
   placed into the same group ("games") automatically.
   
   The persistent data files themselves are root.games with mode 0664
   (i.e. group writable).

   The recovery program `recover_glhack' exists in the read-only dir,
   and requires root privileges to run.
 

KEYBOARD CONTROLS
-----------------

Press the `?' key to bring up a help menu (while in the game).  One of
the choices will show what all of the keys do.

The `S' key will save (and leave) the current game.  To quit the
current game altogether (without saving), type `#quit' and press
return.  Note to newcomers: there is no way to save the current game
and keep on playing, like you can in many other games.  Once you die,
that's it, game over.  That's the nature of NetHack, though it can
seem stupid or frustrating at first.  There's always the "Explore"
mode (the `X' key) which I recommend to anyone who is really stuck.

The arrow keys can be used to move the player, or scroll through
menu/text windows.  Using them with SHIFT will scroll menu/text
windows by a larger step, and with CTRL they will scroll as far as
possible.  Using them with ALT scrolls the map window.


Other Keys:
-----------

   PGUP        -  zoom the map out.
   PGDN        -  zoom the map in.
   
   CTRL-PGUP   -  set zoom to maximum (smallest tiles).
   CTRL-PGDN   -  set zoom to default level.
   
   HOME        -  toggle the text-mode view of the map.
   END         -  center the screen on the player.

   CTRL-P      -  scroll back through history buffer.
   CTRL-O      -  scroll forward through history buffer.

   F4          -  toggle permanent cursor on the player.


MOUSE CONTROLS
--------------

Clicking on a place in the map will take you there (if nothing gets in
the way).  This is the new "travel" feature in NetHack 3.4.0.  Also,
clicking on a monster next to you will attack it, plus you can open
doors this way, even push boulders.  Try it !

When a menu is displayed, you can click on an item to select it (for
menus requiring a single choice), or toggle the item on/off (for menus
which allow multiple items to be chosen).

Text windows can be scrolled by clicking in them.  The mouse cursor
will change shape to an arrow to show the direction you can scroll.
Pressing the ALT key allows you to scroll menu windows and the map
window with the mouse as well.


SELECTING THE RENDERER
----------------------

glHack now supports software rendering.  It is selected using the
standard NetHack option "windowtype" with the value "SDL".  The value
"GL" selects the OpenGL renderer.  For example:

   # glHack Config file
   OPTIONS=windowtype:SDL

The in-game option screen (the `O' key) shows the current type.

When glHack hasn't been told what video-mode or depth to set (using
command line or config file options), it tries to autodetect them.
[ This feature is new in version 1.1 ].  It hasn't been well tested,
but seems to work OK so far.  You can override this by putting your
own values in the config file.

For software rendering, it is important to get the correct depth
value.  The wrong depth can result in wrong colors and/or much slower
rendering.  The autodetected value will usually be OK, so here I'll
just mention some tips when setting it by hand.  Roughly speaking, the
depth should match what the X server is using: if the X server is in 8
bit mode, then you should use "depth:8", if it's in 16 bit mode, then
use "depth:16", and for X servers in 24 bit mode, "depth:32" seems to
be fastest.  The xdpyinfo program is useful for showing information
about the X server.  

The depth can be important for OpenGL rendering too, e.g. really slow
rendering suggests that hardware acceleration is NOT being used.  For
Voodoo 3, both the X server and glHack should be in 16 bit mode.  More
modern cards may support 24 or 32 bit depths. 


COMMAND-LINE OPTIONS
--------------------

Some standard NetHack options that are worth mentioning here (see the
NetHack docs for a complete list) :

  -u UserName       Name of your character in the game.  Normally this
                    is determined automatically from your login name.
                    This option allows you to play multiple games at
                    the same time (with different characters).

  -p Profession     Profession (role) of your character.
  -r Race           Race of your character.
  -@                Choose remaining character attributes randomly.

  -s                Shows the current high-score list.


glHack Command-Line Options:
----------------------------

The glHack command line options all begin with `--'.  Values are
normally separated from the option with a space, like "--depth 32".

Alternatively, a value can be placed after an `=' sign without any
spaces, like "--depth=32".  This should be used if the value begins
with a minus (`-') sign, otherwise the number will be mistaken as a
new option.

Options that take a value are shown here with example values.

The available options are:

  --help            Show a help page.
 
  --version         Show the current glHack version.  This can also be
                    done within the game using the #version command.
 
  --mode 640x480    Use the specified video mode.  Normally glHack will
                    autodetect the mode, but using this option will
                    override that.  The default value (when all else
                    fails) is 800x600.

  --depth 32        Video depth (bits per pixel).  Possible values are
                    15, 16, 24 and 32, and 8 when using the software
                    renderer.  The default value is autodetected.

  --windowed        Open in a window.  Default is fullscreen.

  --gamma=-1        Gamma correction value.  Range is -5 to +5, where
                    positive values make the screen brighter, and
                    negative values make it darker.  Zero is the
                    default value (no adjustment).

  --tileheight 64   Choose the tileset, which can be 16, 32 or 64.
                    The default is 32.  To get the Isometric 3D
                    tileset, use 64 (as shown).

  --fontsize 22     Choose the font size, out of 8, 14, 20 or 22.  The
                    default is 20.  The size will be used for all text
                    windows, overriding any wincap settings in the
                    config file.
 

CONFIG FILE
-----------

The config file for glHack is ".glhackrc" in your $(HOME) directory.
If you already have a ".nethackrc" file, you can copy it to .glhackrc
and it should work fine.

The config file can contain both standard NetHack options (lines that
begin with "OPTIONS=") as well as glHack-specific options (with lines
that begin with "GL_OPTIONS=").  The glHack options follow the same
conventions: 

   1. multiple options are separated by commas.

   2. boolean options are enabled by just including their names, or
      disabled by placing an `!' character before their name.

   3. options with values put the value after a `:' character.

Examples:

   GL_OPTIONS=!windowed,jailsize:10

   GL_OPTIONS=mode:1024x768,altprev


GLHACK CONFIG OPTIONS
---------------------

Here is the list of all available glHack config file options.  Options
shown without values are booleans (on or off).

   mode:1024x768   \
                    |
   depth:8          |
                    |  Same as the command line (see above).
   windowed         |
                    |
   gamma:-1        /

   jailsize:60     Sets the "jail" size, which is a percentage of
                   the size of the screen.  Usable range is 1 to 100.

                   The jail controls when the map window scrolls: when
                   set to 1, the player will always be centered and
                   the map always scrolls when moving.  When set to
                   100, the map will only scroll if the player tries
                   to move off the edge of the screen.

                   This option is ignored when "jumpscroll" is enabled
                   (see below).

   defzoom:16      Sets the default zoom factor, in pixels.  Use 0 to
                   make it the same as the tile size (i.e. 1:1 scale)
                   which is the default.  Use 8 to mean the text-mode
                   view.

   keyrepeat:never  
                   Enables/disables keyboard auto-repeat.  Use "never"
                   to disable it everywhere, "always" to enable it
                   everywhere, and "partial" is a compromise which
                   enables auto-repeat for scrolling windows (etc) but
                   disables it for game commands (moving, etc).
 
   altprev         Enables the alternate previous history (CTRL-P)
                   mode, which is more like the TTY version: the lines
                   are limited to the message window, and you don't
                   need to press CTRL-O, space or escape to dismiss
                   the window.
 
   prevstep:3      Number of lines to step through the previous
                   message history.  For altprev mode, using the same
                   value as the message window height (vary_msgcount)
                   gives the best results.  That's the default for
                   altprev mode, for normal mode the default is 1.
 
   reformat        Causes text windows that don't fit across the
                   screen to be reformatted.  The default is off.
 
   shrinkwrap      Shrinks the fonts on text windows if they don't
                   fit across the screen.  It's mainly an alternative
                   to the `reformat' option.  Default is off.

   flipping        Flips monster tiles horizontally so the direction
                   they face on-screen matches the direction they are
                   moving in.  NOTE: this only works in GL mode, and
                   it doesn't work with the Isometric 3D tiles.

   jumpscroll      Scrolls the map window in large jumps, rather than
                   single steps, which improves speed when using the
                   software renderer.  When enabled, the standard
                   NetHack option "scroll_margin" will be used to
                   decide when to scroll.

   invisfx         Draws monsters which are invisible (but can be
                   seen by the player) using alpha blending (i.e.
                   translucently).  Default is off.


WINCAP OPTIONS
--------------

The WINCAP (Window port Capability) options are new in NetHack 3.4.0,
and are described in the Guidebook (section 9.5).  glHack currently
supports these ones:

   align_message, align_status,
   color, hilite_pet,
   font_size_map, font_size_message, font_size_status,
   font_size_menu, font_size_text,
   scroll_margin (but only when jumpscroll is enabled),
   splash_screen,
   tile_height,
   vary_msgcount.


SHELL VARIABLES
---------------

glHack supports the same shell variables (also called "environment
variables") as standard NetHack, in particular the NETHACKOPTIONS
variable.  See the NetHack man page or Guidebook for full details.

glHack also supports a new shell variable "GLHACKOPTIONS", which can
be used to set glHack-specific options.  The format is the same as
NETHACKOPTIONS (and very similiar to the config file).  For example,
using the bash shell you could type this:

   export GLHACKOPTIONS=mode:1024x768,altprev,keyrepeat:partial

If the line contains `!' marks, they will need to be escaped by
putting a backslash (`\') before them, otherwise the shell will
get confused (`!' usually has a special meaning).


EXAMPLE CONFIG FILE
-------------------

If you don't already have a glHack config file, and would like to
permanently set some NetHack options, just copy and paste the
following lines into $(HOME)/.glhackrc, and edit to taste.  Lines
beginning with `#' are comments.

#
# glHack Config file
#
OPTIONS=windowtype:SDL
OPTIONS=tile_height:32,vary_msgcount:3
OPTIONS=font_size_message:20,font_size_map:14
OPTIONS=dogname:Woofer,catname:Morris
OPTIONS=horsename:Tally,fruit:mango
OPTIONS=color,hilite_pet,safe_pet
OPTIONS=verbose,lit_corridor,confirm
OPTIONS=pickup_burden:U,pickup_types:$?!/="
OPTIONS=!showexp,showscore,splash_screen,!time
OPTIONS=toptenwin,tombstone,menustyle:partial
OPTIONS=!prayconfirm,pushweapon,disclose:yi ya yv
#
GL_OPTIONS=!windowed,keyrepeat:always
GL_OPTIONS=altprev,prevstep:3
GL_OPTIONS=flipping,!jumpscroll


NOTE FOR CVS USERS
------------------

The sources in CVS only contain the glHack-specific parts (including a
few NetHack files that were modified to work with glHack).  To compile
and install after checking out glHack from CVS, you need (a) the PNG
images and (b) the original NetHack sources.  See the "CVS Extras"
section on the download page of the glHack site.

Putting the PNG files in place is easy enough, just unpack in the top
glhack directory.  Putting in the NetHack sources is a bit harder, but
fairly straightforward.  Unpack the nethack-340.tgz file someplace
(I'll use /tmp for this example), then cd into the original glhack
directory and type:

   cp -a -v * /tmp/nethack-3.4.0/

and build from there.  The -a option ensures that subdirectories get
copied recursively and symbolic links are preserved.  The -v option
just shows you what files are copied.


NO WARRANTIES
-------------

This program is free software.  It is distributed in the hope that it
will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


AUTHORS
-------

Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote
the original hack, very much like rogue (but full of bugs).

Andries Brouwer continuously deformed their sources into an
entirely different game.

Mike Stephenson has continued the perversion of sources, adding
various warped character classes and sadistic traps with the help
of many strange people who reside in that place between the worlds,
the Usenet Zone. A number of these miscreants are immortalized in
the historical roll of dishonor and various other places.  The
resulting mess was then called NetHack, to denote its development
by the Usenet.
 
Andrew Apted wrote the window port to SDL and OpenGL, later adding
a pure software renderer (based on a patch from Allister MacLeod).
This little beasty was called glHack.  When NetHack 3.4.0 was
released it got updated to match, but then stagnated for a while,
until James Bentler came along and updated it to 3.4.3.