About this document: Last modified by Fredrik Ljungdahl, 2015-11-03
Copyright (C) 2017 Fredrik Ljungdahl.
This README file is licensed under the NetHack General Public License. See libnethack/dat/license for details.
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 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.
FIQHack is a fork of NetHack4, aimed at improving balance at places, test out new things, improving the codebase with internal changes and to promote consistency between how players and monsters work, and to improve the monster AI.
More detailed information can be seen in doc/CHANGELOG.
This repository consists of the following branches
-
A master branch exist containing general experimental in-development changes which is unfinished and yet to be stable and ready for the public. Saves can break at any moment.
-
One-off feature branches, for developing a certain new feature or refactor
-
Branches representing a certain version, used to push changes specific to a certain version. With the exception of critical bug fixes, changes are only pushed to the latest of the versions.
To build FIQHack, you need make, zlib (which is probably already installed),
libjansson (http://www.digip.org/jansson -- shipped with this source), and
its development branch. You will also need bison and flex, as well as
a C compiler (gcc or clang will both work).
The default setup is to install to ~/fiqhackdir. If you want to change
this, you can modify GNUmakefile -- file paths are set at the top.
Once you are happy with the setup, to compile, you just do
make && make install
In case this doesn't work, please file an issue describing your error, perhaps documentation is lacking or something is missing. Enjoy!
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
You will need to install FIQHack'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.
FIQHack also requires a working libjansson library (available from
http://www.digip.org/jansson), and its development headers. However, both of
those ship with NetHack 4, 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 FIQHack from your home directory, from the top source directory, run:
mkdir build
cd build
../aimake -i ~/fiqhack .. # 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 fiqhack. For the tiles/faketerm ports, use
fiqhack-sdl.
You will need to install various prerequisite programs in order to compile NetHack 4. 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 nethack4 folder that contains the
entire NetHack 4 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 ..\nethack4\aimake -i ..\install --directory-layout=single_directory
aimake should compile and install the entirety of NetHack 4 for you into the
install directory. In order to run the console port, change directory to the
install directory, and type nethack4. For the tiles/faketerm port, use
nethack4-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 ../nethack4/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.
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 4 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 nh4server nethack4
echo 'CREATE EXTENSION pgcrypto' | psql -d nethack4
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 ~/nethack4, it should be named
~/nethack4/config/nethack4.conf; other forms of install may have other
locations. (You can run nethack4-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=nh4server
dbpass=**password**
dbname=nethack4
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:
53430 stream tcp nowait username /path/to/nethack4-server nethack4-server
53430 stream tcp6 nowait username /path/to/nethack4-server nethack4-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 nethack4 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.