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.