About this document:
Last modified by Alex Smith, 2015-09-04
Copyright (C) 2013 Alex Smith.
Copyright (C) 2015 Nathan Eady.
This README file is licensed under the NetHack General Public License.
See libnethack/dat/license for details.
For information about building the game on Microsoft Windows, see
README-MSWindows.txt. For information about building on Unix-type
systems (including Mac and Linux), see Build Instructions, below.
Overview
========
NetHack is free software, and has no warranty of any sort. For more
information on the license situation, read `COPYING` (a summary), or
`copyright` (full details).
NetHack Fourk (NHF) is based on NetHack 4 (NH4), with additional
changes. In order to understand the purpose of NetHack Fourk, you
must first understand about NetHack 4.
NetHack 4
=========
NetHack 4 is a version of the computer game NetHack, that aims to
bring a better-quality codebase and a less hostile interface to
NetHack's highly rated "roguelike" gameplay. Unlike many NetHack
variants, it is intentionally conservative in making gameplay changes;
in particular, it aims to avoid the common problem whereby development
is driven via fixing perceived balance issues with the game (often
losing the ability to improvise solutions to complex problems in the
process), or via focusing too much on the difference between wins and
losses (meaning that players are forced into taking the best choice,
rather than the choice they enjoy most or a choice they want to try).
See the file `doc/philosophy.txt` for more information on NetHack 4's
philosophy.
NetHack Fourk
=============
NetHack Fourk exists to test out changes that are believed to be
needed in principle (typically, for balance reasons) but might or
might not prove to be appropriate in practice, in some cases because
we are unsure whether they are the correct solution to a problem or
because we are unsure how much of the proposed solution is actually
required, or in other cases because we are unsure whether the change
might introduce even larger balance issues than the problem it intends
to solve ("the cure is worse than the disease"). As such, NetHack
Fourk will be far more conservative about gameplay changes than the
truly experimental variants, but less strict than NetHack4.
Development will closely track NetHack 4 as an upstream source.
The following principles are put forward:
* The master branch should not break save compatibility except
after release, when it moves to the new version number by
merging material that was previously in bleeding-edge. The
bleeding-edge branch may break save compatibility any time.
Version-number branches with a version number less than that of
the master branch are to receive important bugfixes only. The
version-number branch that has the same version number as the
master branch will generally keep pace with it; and any
higher-numbered branches are considered to be in a preliminary,
bleeding-edge state and may break save compatibility at any time.
* When possible, uncontroversial improvements should be committed
upstream to NetHack 4 first and then be merged down to NetHack
Fourk. Priority should be given to bug fixes and to popular
enhancements that have been field tested elsewhere (especially
on very active public servers).
* Changes from the stable branch of NetHack 4 (at the time of this
writing, called master) may be merged at any time, unless we are
in a freeze to prepare for release. Such freezes should be short
in duration.
* Changes from other NetHack 4 branches should only be merged at
certain points in the development cycle. If there is more than
one developer working on NetHack Fourk, these changes should be
discussed prior to merging, because planning may be required.
However, in general, NetHack Fourk aims to be somewhat more
experimental than mainstream NetHack 4, so it will often be
appropriate to merge pending changes from other branches.
* At appropriate points in the development cycle, popular changes
from other NetHack variants may also be merged. Priority should be
given to popular changes from conservative variants, or ones that
are popular enough to have made it into multiple variants already,
or ones that are well understood because they have seen extensive
play testing already, or that only impact players who choose to use
them (e.g., new roles).
* Original changes should be implemented when necessary to address
serious shortcomings or major balance issues or to improve the
monster AI. Some exceptions may be made for changes that only
impact players who choose to use them, e.g., for new playable races
and roles. These should always be implemented in a feature branch
first and tested at least a little before merging into the master
branch.
* Improving the monster AI, if it genuinely makes monsters smarter or
introduces greater variety of monster behavior, may be done (at
appropriate points in the dev cycle -- typically, in bleeding-edge)
even if it disrupts game balance; subsequently, if play testing
reveals a significant imbalance, steps may be taken to compensate,
e.g., by giving the player better ways to deal with monsters that
have become more dangerous.
* Improvements that enhance the variety of the gameplay experience
may be made during the alpha phase of the dev cycle (typically,
they will be merged into the bleeding-edge branch), provided they
are kept within reasonable limits and are held to a high standard
of balance and quality.
History
=======
NetHack 4 was originally produced by merging two forks, Alex Smith's AceHack,
and Daniel Thaler's NitroHack. Since then it has incorporated changes from
numerous other forks (especially the fertile sources of bugfixes that are
GruntHack and UnNetHack), and has had many improvements of its own.
NetHack 4 has come a long way since 2009, when AceHack began. Out of all the
lines of C, lex, and yacc source code currently in NetHack 4, less than half
originally come from NetHack 3.4.3 or earlier – even if you don't count
whitespace changes. The rest are typically modifications or even rewrites of
the old code with bugs fixed and style improved. Many people have suggested
rewriting NetHack from scratch to get rid of the bugs and improve the coding
style, but doing so would be close to an impossible project. Our continuous
changes of NetHack from the inside will eventually accomplish a similar goal,
but in a more realistic manner.
The information about NetHack 4 in this README file mainly describes
version 4.3, which focuses mostly on improvements to the game's
internals, rather than gameplay changes. The NetHack 4 developers are
planning to make more substantial gameplay changes in 4.4.
Frequently Asked Questions
==========================
See the file `faq.txt` (`doc/faq.txt` in the source code, or in the
documentation directory in an installed version).
Contact
=======
Bugs in NetHack Fourk that can also be reproduced in NetHack 4 should
preferably be reported upstream at http://trac.nethack4.org, our bug
tracker. The homepage for NetHack 4 itself is http://nethack4.org,
and contains many other resources about the game and its community.
Bugs that are specific to NetHack Fourk, or have not been reproduced
upstream in NH4, MAY also be reported in trac, since at the time of
this writing, NetHack Fourk does not have its own bug tracker or
website. If reporting bugs in trac that have only been sighted in
Fourk, please be sure to set the Version field to indicate that the
bug was seen in Fourk. Bug reports or other correspondance specific
to NetHack Fourk may also be reported to jonadab either on the
Freenode IRC network or by email (at columbus.rr.com).
You can discuss NetHack 4 and NetHack Fourk on IRC.
irc:irc.freenode.net/nethack4 is the channel for NetHack 4, and
typically discusses development. There is also a channel for NetHack
Fourk at irc:irc.freenode.net/nhfourk that can be used to make feature
requests or discuss balance or other issues pertaining either to
changes that NetHack Fourk has already made or perhaps should make.
For gameplay advice, the best place is the general NetHack discussion
channel at irc:irc.freenode.net/nethack (which also covers NetHack 3
and Slash'EM).
If you're more old-fashioned, you can use Usenet instead; the appropriate
newsgroup is rec.games.roguelike.nethack (although they would appreciate it if
you put `[NetHack Fourk]` in the subject line to make it clear that you aren't
talking about NetHack 3).
If you want to contact the developers directly, you can use IRC, or email;
`jonadab` (Nathan Eady) can receive email using that username, at columbus.rr.com.
`ais523` (Alex Smith) can receive email using that username, at nethack4.org.
Selected Changes
================
Here are a few of the highlights in NetHack Fourk:
* Player race now has an impact on attribute caps, adjusting some of
them up or down a point from the value for your role. Additionally,
some races get higher skill caps in certain weapon skills.
* A new playable race, Sylph, has been added.
* Barbarians are now categorically the best role for melee and
probably the easiest role for new players. Samurai, Knights, and
especially Valkyries have been compensated with other advantages.
Some of the other roles also have changes, geared toward
encouraging the use of role-appropriate weapons and tactics.
* Some weapons that previously saw little use (e.g., sling, axe) are
enhanced, particularly if you are playing the right roles for them.
Ranged weapons have been rebalanced, especially multi-fire.
* Players will need to pay somewhat more attention to alignment-record
penalties (like dishonorably attacking the innocent, being a caitiff,
feeling guilty, etc.). The limits are now always -100 to 100. New
alignment-dependent methods for improving your record have been added,
and one important one (killing ordinary monsters) no longer works.
* Sokoban now has more versions of its levels, and there are a couple of
new ways for players who dislike the puzzle aspect of the branch to dodge
the luck penalties.
* Amnesia has been removed from the game; the scroll of amnesia is
replaced with the scroll of water.
* Certain monsters have been enhanced, notably monkeys, the Oracle,
hezrou, pit fiends, ice devils, and the Wizard of Yendor.
* Nymphs have a difficulty progression (wood / water / mountain / island).
* Some level features have been enhanced, e.g., rooms can be
non-rectangular and mazes can have wide walls or corridors.
* Floating eyes had their behavior changed in 4.3.0.1.
* Certain early-game instadeaths are more avoidable now.
* A few monsters have a slightly different appearance than before.
* Some probability formulae have been adjusted. Notable ones
include your chance to hit a monster, your chance to successfully
engrave, the chance for engravings to erode, a monster's chance to
drop a corpse and/or a random item, and the chance for projectiles
to break on impact.
* Wands of wishing are no longer rechargeable, but now there are
also scrolls of wishing.
* Permanently converting your alignment before the quest no longer makes
the game unwinnable (though it is still not recommended.)
For a more complete list of changes in NetHack Fourk compared to the
NetHack 4, see `doc/changelog-fourk.txt`. (If greater detail is
wanted, you can also look at the git log.) Additionally,
changelog.txt, listing the changes in NetHack 4 as compared to 3.x, is
still available.
For a full list of changes in NetHack 4 compared to the NetHack 3 series, see
`doc/changelog.txt`. Some of the most interesting or noticeable of these
changes are listed below.
* Numerous bugfixes. Over 200 of the numbered bugs in NetHack 3.4.3 have
been fixed *intentionally*; many more have been fixed as a side effect of
the improvements to NetHack's internals included in NetHack 4, and many
bugs have been fixed in NetHack 4 that aren't included in the NetHack
3.4.3 bug list (because the NetHack 3 devteam failed to add them, despite
being notified about them).
* A fully rewritten interface, that nonetheless is almost compatible at the
keystroke level with 3.4.3 (with a few exceptions to reduce the effect of
making typos, or to remove redundant prompts). Just like previous
versions, both tiles and console ports are available; unlike previous
versions, these ports are keystroke-compatible with each other, so
more detailed graphics no longer have to be accompanied by a loss in
functionality on the keyboard.
Features of the interface include:
* Status lines which visually represent health and magical power, and
which use color in order to draw attention to dangerous situations and
to allow a quick appraisal of the character out of the corner of your
eye – but stay gray if they have nothing urgent to say, so that they
are most visible when most necessary.
* Improved support for large terminals:
* Extra vertical space will be used to display more messages at once
(cutting down on the need to space through messages at the
infamous `--More--` prompt, and to present more information in the
status area. If you have even more vertical space than that, the
spare space will be used for mouselook (showing information about
the map square the mouse is pointing over), and for reminders
about the controls. (New players are recommended to use very
vertically large terminals.)
* If you have spare horizontal space, it is used to maintain a
permanent display of the inventory and to show information about
the floor beneath your character's feet.
* More information shown on the game map. You can see where your
character's been walking, see stairs and traps underneath items, and
tell at a glance which monsters are peaceful.
* A better rendering backend. NetHack 3.4.3 could only use IBMgraphics
or DECgraphics for this, often with neither working without spending
time configuring your terminal. NetHack 4 will automatically switch
between IBMgraphics and Unicode according to the needs of your
terminal, meaning that there is rarely a need to change settings.
Likewise, it will try its best to give you a working dark gray color
(although in emergencies, you can turn off dark gray in the options,
and the engine will redo its color schemes to avoid that color).
* Commands are now fully rebindable. In most cases, though, you won't
need to; unlike NetHack 3, NetHack 4 understands most of the keys on
the keyboard, meaning that (especially with NumLock off) it can
distinguish the main keyboard and numeric keypad numbers, meaning that
there's no longer a need to mess around with the `numpad` option. In
fact, you can even use the cursor keys for navigation (without losing
the ability to use diagonals), giving three styles of movement:
vi-keys cursor keys number keys
y k u Home Up PgUp 7 8 9
h . l Left . Right 4 . 6
b j n End Down PgDn 1 2 3
(This sadly cuts slightly into the convenience commands that numpad
players were used to. Instead of `N` for `#name`, you can use `C`;
instead of `k` for kicking, you can use `^D`. For command repeat,
just use the numbers on the main keyboard. Alternatively, you can use
the options menu to change back to the old numpad bindings.)
Another gain from this is that the `Meta-` shortcuts for many extended
commands, that do not work properly in 3.4.3 on many terminals, will
normally work in NetHack 4 (using the `Alt` key on the keyboard).
* Addition of some new, convenient, commands, without compromising the
original commands:
* You can limit any command to a specific number of actions via
specifying a number of actions to stop after. (Single-turn
commands will be repeated for that many actions instead, as in
3.4.3.) You can also stop commands midway through by pressing any
key or clicking on the map, if your options are set to animate
long-running commands.
* `^A` is a lot more powerful; when repeating commands, it will
remember what choices you made, and if you use it after an
interrupted multi-turn command, it will resume that command for
you.
* You no longer have to remember the difference between `W` and `P`,
or between `R` and `T`; they're interchangeable now. In fact, you
no longer have to remember any of those commands, nor `w`, `x`, or
`Q`, because you can now change your equipment around using `A`.
Also, your character will temporarily unequip armor in order to
manipulate armor beneath it, meaning that you don't have to
explicitly remove a suit in order to take off a shirt.
* There's no need to explicitly open doors any more; just use the
direction keys to walk towards them. If they turn out to be
locked, you can now unlock them with `o`.
* Examining map squares using `;` still works, but if you have a
mouse available, you can also quickly examine them simply via
hovering the mouse pointer over them.
* If you find exploring empty areas tedious, you can let the game
take over for you; press `v`, and an AI will take over the
exploring for you until it finds something interesting or a
monster turns up.
* The game will remember information about other levels for you,
accessible via the `^O` command; not only will it give a quick
guide to interesting features on each level, but you can select a
level from the menu to view what you remember about its map.
* Fed up of typing out Elbereth by hand? The `^E` command is a
quick shortcut to write an Elbereth in the dust.
* It's now harder to do things that are normally bad ideas by mistake –
but it's still possible to do them intentionally. For instance,
moving towards a shopkeeper is interpreted as "pay" (`p`) rather than
"fight" (`F`); you'd need to give the `F` intentionally if you wanted
to attack. Likewise, moving into lava (when not levitating, confused,
or the like) needs an `m` prefix, or the game will give a warning and
your character will wisely just stand there.
* Along similar lines, you now normally use `,` as an inventory letter
to interact with items on the floor (e.g. `e,` to eat them), because
the ambiguity of `ey` lead to many typo-related deaths back in 3.4.3.
* The game now tracks more information about your character, with a
"history" view that shows major events in your character's life, and
with dumplogs produced when the game ends to summarize the heroic
efforts and final defeat (or glorious victory) of your character.
* Customizing options no longer requires messing around with configuration
files; you can change options for one game using the in-game `O` command,
and options for all future games from the main menu. There are numerous
improvements to the options themselves, too:
* You can set various "birth options" for your game in order to control
what sort of game you want to play, ranging from something small like
turning off bones, to challenge modes where your character is
permanently blind or hallucinating. There's no longer a need to
recompile the game if you want to do something like turn off Elbereth.
* Autopickup is a lot more customizable than in 3.4.3, with the ability
to add rules that match various properties of items against patterns
to choose whether to pick them up.
* There are many more options for what the main movement keys do. In
3.4.3, your choices are limited to choosing whether they displace pets
and whether they ask for confirmation when you attack peacefuls. In
NetHack 4, you could for instance have them refuse to attack monsters
altogether, without losing the ability to pick up items (which is what
adding an `m` before every command would do).
* Finally, if you're a traditionalist, don't worry: the vast majority of
the new interface features from NetHack 4 can be turned off, leaving
you with an uninteresting 3.4.3-like ASCII view if you want.
* The save system has been rewritten (and we removed all the much-maligned
NitroHack save code, too). Save files now contain a complete history of
the gamestate, allowing them to be reconstructed at any point, making it
possible to view a replay of a game with full character knowledge. The
save files are also saved continuously; if something goes wrong, whether
it's a bug in the game or your terminal crashing, you'll be able to just
pick back up where you left. You can even save in the middle of a turn!
(To do this, either close the window, or open the main menu using
Control-C and save that way.) The game is also ever-vigilant for mistakes
in the save system; if at any point your game can no longer be restored
from its save, it will stop gameplay immediately, maximizing the chances
that the save file can be recovered, rather than letting you play on and
then losing all your progress since the moment it went wrong.
* There have been some gameplay changes, mostly to remove "difficulty" that
was created via relying on a bad interface and entirely avoidable via
playing slowly and taking lots of notes. Most notably, amnesia does not
cause the character to forget anything the player could easily find out
by watching the replay of the game up to that point; instead, it drains
skill points and spells.
There are also many gameplay changes intended to streamline the interface.
Try dropping a container full of unidentified items on an altar some time.
Finally, there are some improvements in the monster AI. For instance,
pets can use their special attacks now and are much better at following
you, and hostile monsters may attack each other even without conflict if
they dislike each other enough.
Monsters also have less spoiler knowledge than they did before; in
particular, they won't know where you are on the map without some way to
see or sense your location.
* Building the game from source is much easier than it was in NetHack
3.4.3. See the build instructions below.
For a list of changes in NetHack Fourk compared to the NetHack 4, see
`doc/changelog-fourk.txt`. (If greater detail is wanted, you can also look
at the git log.) Additionally, changelog.txt, listing the changes in NetHack
4 as compared to 3.x, is still available.
Build Instructions
==================
General note
------------
The build instructions in this system are basic "do this, and things should
work" advice, and do not go heavily into details of customizing a build.
If you want to do something complex or unusual, you can read the build
system manual (which lists everything in more detail than most people will
need) via running the command
perl aimake --documentation
UNIX/Linux/Mac OS X
-------------------
You will need to install NetHack Fourk's dependencies: zlib (which is
probably installed already, but you may need to get its development headers
from your package manager), and (if you want a working server binary) inetd,
postgresql and pgcrypto. You also need development headers for the libraries
listed.
NetHack Fourk also requires a working libjansson library (available from
http://www.digip.org/jansson), and its development headers. However, both of
those ship with NetHack Fourk, and will be used by default or if you
explicitly specify `--with=jansson` as an option to `aimake`. (If you have
installed libjansson yourself, you can give `--without=jansson` to use your
own copy. This will build a little faster and avoid installing redundant
copies of the jansson library.)
You will also need the `bison` and `flex` programs (in addition to the usual
compilers), because some of NetHack's tools (e.g. the level-handling
utilities) are written in them.
If you want to build the tiles or faketerm ports (the default), you will also
need to install libpng, and version 2 of the Simple DirectMedia Layer; it may
be available in your package manager, or else you could download the source
code from http://www.libsdl.org and compile it yourself. Otherwise, you can
specify `--without=gui` as an option to `aimake` to build just the console
port (which is built either way), and disable the tiles ports. Note that the
tiles ports do not currently work on Mac OS X.
Assuming you just want to run NetHack Fourk from your home directory, from
the top source directory, run:
mkdir build
cd build
../aimake -i ~/nhfourk .. # or wherever you want
If you want to install for all users, you will need to tell `aimake` which
location to install it into, and how to elevate its permissions:
# as a regular user, not root
mkdir build
cd build
../aimake -i /usr/local -S su .. # or perhaps -S sudo
Note that this requires a group `games` to exist on your system, and contain
no normal users, in order to ensure security of the bones files and high score
tables. This is the case on most Linux distributions, but not on all, and may
not be the case on UNIX.
To run the console port, use `nhfourk`. For the tiles/faketerm ports, use
`nhfourk-sdl`.
Windows
-------
You will need to install various prerequisite programs in order to compile
NetHack Fourk. The build system is written in Perl, and as such, the
simplest way to get a working toolchain is to install Strawberry Perl,
available at http://strawberryperl.com, which comes with a working C
toolchain. You will also need to install Flex and Bison, scanner and parser
generators; the versions at GnuWin32 (http://gnuwin32.sourceforge.net/) work
(although they don't have a very Windows-like idea of directory structure,
and thus can't be installed to paths with spaces in, and produce compiler
warnings; if you know a better option, let us know). Strawberry Perl's and
GnuWin32's executables will all need to be on your PATH (search for "PATH" in
Control Panel, on recent versions of Windows).
You will also need to create two more folders, `build` and `install`; I
recommend that both are parallel to the `nhfourk` folder that contains the
entire NetHack Fourk distribution.
If you want to build a tiles or fake terminal port (recommended even if you
aren't a tiles player, because Windows' terminal is rather slow), you will
need version 2 of the Simple DirectMedia Layer. Download the MinGW version of
the development headers and import libraries from http://www.libsdl.org; also
download the library itself. Then copy the entire `include/SDL2` subdirectory
from the appropriate processor-dependent directory of the SDL distribution, to
the `c/include` folder that was created when you installed Strawberry Perl (so
that it beomes `c/include/SDL2`); and all the files `lib/*.a` from the
appropriate processor-dependent directory of the SDL distribution to the
`c/lib` folder that was created when you installed Strawberry Perl (so that
they become `c/lib/libSDL2.a`, etc.). Finally, copy the file `SDL2.dll` that
you obtained when you downloaded the library itself to the `prebuilt` folder
inside the `nethack4` folder that contained the distribution.
Once you've done this, open Strawberry Perl's command prompt, change to the
build directory, and type:
perl ..\nhfourk\aimake -i ..\install --directory-layout=single_directory
aimake should compile and install the entirety of NetHack Fourk for you into
the install directory. In order to run the console port, change directory to
the install directory, and type `nhfourk`. For the tiles/faketerm port, use
`nhfourk-sdl.exe`.
It is possible that `ld.exe` will crash in the process of the build. This
only seems to happen after it has already produced the output that aimake
needed, so you can just dismiss the error box and let the build work as
normal.
Note that despite the best efforts of the rendering library, the game is quite
slow to render on the console when using recent versions of Windows; this is
because the Windows console itself is prety slow. (For a comparison, you can
try running a command that produces a lot of text, such as `perl
../nhfourk/aimake --documentation`, and observing how long it takes to scroll
the screen when you press the spacebar.) The faketerm port somehow manages to
be faster, even though it too is fairly slow.
Server setup
------------
If you want to run your own server (which is only necessary/useful if you want
people to be able to connect to your NetHack Fourk server from other computers,
rather than running locally), you'll need to give `--with=server` as a
command-line option to `aimake`, and also need to set up the postgresql
database:
su postgres # or any other way to elevate your permissions
createuser -DPRS nh4server
# You'll be prompted for a password at this point.
createdb -O nhfserver nhfourk
echo 'CREATE EXTENSION pgcrypto' | psql -d nhfourk
exit # go back to your normal permissions
Next you need to edit the configuration file (a blank configuration file will
have been installed in the appropriate place for you to edit). If you
installed into `~/nhfourk`, it should be named
`~/nhfourk/config/nhfourk.conf`; other forms of install may have other
locations. (You can run nhfourk-server with no arguments to discover where
the configuration file should be; if it can't find its configuration file,
it'll complain and tell you where it's looking for it.)
The configuration file looks something like this:
dbhost=127.0.0.1
dbport=5432
dbuser=nhfserver
dbpass=passphrase-that-may-as-well-be-nice-and-long
dbname=nhfourk
Note that the port number has been known to vary based on the way that your
copy of postgresql is packaged; you may want to verify it by looking at
postgresql's configuration, `/etc/postgresql/.../postgresql.conf`. Also be
aware that the configuration file necessarily has to store the password in
plaintext (a hashed password is no good for actually logging into the
database); you may want to change the permissions on the configuration file to
help protect it. (I recommend using a long random password, because it's only
used by computers; there's no need for humans to memorize it.)
Finally, you need to tell inetd about the new server setup. As root, you need
to add two extra lines to `/etc/inetd.conf`, looking something like this:
53440 stream tcp nowait username /path/to/nhfourk-server nhfourk-server
53440 stream tcp6 nowait username /path/to/nhfourk-server nhfourk-server
(Here, "username" is the username of the user that the server binaries should
run as.) Then, again as root, just send a `SIGHUP` to inetd (`killall -HUP
inetd`), to tell it to load the new configuration file. inetd will be
responsible for starting the server processes when a new connection is made;
no server processes will be running while no games are being played. To test
your server setup, you can use the `nhfourk` client; there's a menu option to
connect to a server with it.
This only really works properly on Linux, at present; on Mac OS X, it may be
possible to get a partially working server, but functionality is missing due
to that operating system's lack of support for realtime signals.