Tilehack (Nethack with Graphical Tiles - Online!)

Nethack is the definitive "roguelike" adventure game. It's a huge, complicated and challenging game, both frustrating and rewarding. Most computers can run the game software locally, but it's also fun to play online, for a high score on alt.org or prizes from the /dev/null Nethack Tournament.

Online Nethack servers usually only offer Nethack via the text-only Telnet protocol. Only the classical text interface is available (right). But some players prefer the graphical interface that has been a standard part of offline Nethack since version 3.2 (released 1996).

One way to enable online tiled play is to guess a suitable tile to replace each on-screen character, based on its attributes, and substitute accordingly. This is the strategy used by David McCallum's program Ebonhack. It works for any Nethack server, but it isn't completely ideal. The text display does not contain as much information as a tiled display - some characters could represent more than one tile, and sometimes a page of text is mistaken for a map and vice versa. A better strategy (introduced by Justin Hiltscher for TelnetTiles) extends Nethack to generate hints about the correct tiles alongside the text characters.

Tilehack is a new approach to TelnetTiles, moving the client into Javascript running in a web browser. It is compatible with text mode and the popular dgamelaunch software. This makes it cross-platform and easy to use, and ensures that the tile set used by the players always matches the one used by the server. Naturally, a player can switch between tiled mode and text mode without starting a new game.

The Tilehack interface is similar to the graphical Nethack interface for MS-DOS: there is no mouse and menus are still text. However, the tiles appear exactly as they do within Nethack for Windows, Mac, MS-DOS and Linux (right).

Tilehack Servers

  • This year, the /dev/null Nethack Tournament is providing tiled play as an option using Tilehack. It is currently available on four of the tournament servers, and I have so far ascended one Tourist in tiled mode.
  • amuletofyendor.com also hosts a Tilehack server.
I ran my own experimental server for three months at the beginning of 2010, but I found that I could not spare the time needed to build a really good online Nethack service, which is about much more than the game software! The final scores are still archived below.

How it Works

Tilehack is based on shellinabox. In short, I modified Shellinabox to be able to display tiles as well as text. There are three major components to Tilehack.

1. Patch for Nethack

Translating text characters into tiles is not ideal, so Nethack must state precisely which tile is needed for each location on the screen. My patch for vanilla Nethack 3.4.3 (unified diff) adds the new "vtiles" module to sys/unix and win/tty. The patch should be compiled into Nethack.

It takes effect only when $TERM = "tilehack". Tiles are drawn using VT100-style escape codes; there are additional escape codes to set the cursor colour according to the player's HP, as in Qt Nethack. These escape codes are chosen for compactness rather than compatibility with non-tiled terminals: unrecognised escape codes are supposed to be ignored, but some terminals try to interpret them anyway, so there is no way to produce output that is compatible both with Tilehack (or TelnetTiles) and with absolutely all non-tiled terminals.

2. Shellinabox-based Server

A modified version of Shellinabox is used as the client. Here's the modified version (based on SVN version 239). The modifications alter the Javascript code to add support for the tile-drawing escape codes. Some features are disabled, e.g. printing, and the cursor keys are enabled for Nethack.

(There is also an earlier version based on shellinabox-2.10, and here is the diff for version 2.10 and the diff for SVN version 239.)

3. Tiles

The Nethack tiles need to be converted into PNG format. Here is the standard tile set, converted appropriately. Each file is named number.png. These files should be hosted on the same web server as Tilehack.

The low 12 bits of number are the tile number, as used within Nethack's glyph2tile data structure. The 12th bit indicates if the tile represents a pet: if so, a small "heart" icon is added to the corner. For version 3.4.3, there are 1080 tiles, resulting in 2160 PNG images.


To run your own Tilehack server, you first need to get text-mode Nethack working with dgamelaunch, so that you can telnet to your server and play. This must be the patched version of Nethack described above.

Then, the steps are (roughly) as follows:

  1. Install the "tilehack" terminfo file on the Nethack server. Copy the "xterm" entry to a new entry named "tilehack". On Debian Linux, you can do this as follows: cp /usr/share/terminfo/x/xterm /usr/share/terminfo/t/tilehack. Unfortunately, this step is different on every OS, but without the "tilehack" terminfo file, you may see messages such as "Unknown terminal type: tilehack" and (if using dgamelaunch) you may not get any visible output!
  2. Set up a web server such as Apache to serve the tile set under an URL such as http://example.com/nhtiles/ (substituting example.com for your web server's address).
  3. Configure the web server to act as a reverse proxy whenever an URL such as /nethack/ is accessed. This reverse proxy should forward to "localhost" port 4200, the default port used by shellinabox. Here is an explanation of the procedure for Apache. No need to use SSL.
  4. Run shellinaboxd with a command line such as:
    shellinaboxd -t -s '/:$user:$group:/:$command'
    In this command line, you must substitute $user and $group with the names of a valid user and group on your system. For testing, use your own username and group (the first two fields that are printed by the "id" command). For a real server, you should think about setting up a "chroot" environment and using dummy user accounts for extra security.

    $command should be "telnet -E $nethackserver", or an equivalent that respects your chroot environment. For regular telnet, -E is important: it disables the telnet escape sequences, which might otherwise allow a user to start a shell on your server.
Note that the Nethack server and the web/shellinabox server can be different machines.


I would like to thank all the Nethack players who spent time playing "Nethack with Graphical Tiles - Online". I appreciate your efforts in testing the service and your email feedback. I'd also like to thank David Stone for the feedback he sent while configuring his server (amuletofyendor.com) and paxed from NAO.

Shellinabox is GPLv2-licensed software, written and copyright by Markus Gutschke. Tilehack would have been much more difficult if I had not been able to build upon this excellent piece of free software.

Future Work

A standard for tile escape codes is being established on nethack.alt.org. Future versions of Tilehack may adopt these codes for interoperability with nethack.alt.org and other tile-based clients.

Test Server - Final Information

By the end of the three month testing period, 1651 games had been played on the server. 136 were not completed. There were no ascensions, although "trif" the human male Tourist made it to the elemental planes with the amulet, where he died an unlucky death from a cockatrice-wielding Archon.

Here is the final high score table. Once again, my thanks to all who took part.