README

Interhack is a layer that sits between you and your NetHack server (which we'll
call NAO) and plays with the text going both ways. For example, this could be
used to color the message "You are slowing down" in bright red.

Interhack is written primarily by Shawn M Moore, Jesse Luehrs, and Jordan A
Lewis. It is released under the MIT license (see LICENSE).

+------------+
| DISCLAIMER |
+------------+

The Interhack development team is in no way responsible for what happens as a
result of using Interhack. If pressing tab causes your character to drown, it
sucks but it's your own fault (hopefully). That's precisely why Interhack tells
you exactly what characters it's going to send, and asks you to press tab.

+---------+
| GETTING |
+---------+

The recommended way to get Interhack is through darcs. This way you can easily
update (and, if you're feeling adventurous, modify) your Interhack build.
darcs is a source control manager (the one we use for Interhack, obviously).
It's written in Haskell and depends on ghc (a Haskell compiler). These
dependencies aren't tiny, so it's up to you whether you want to either fight
the darcs installation or repeatedly download the Interhack code.

See http://darcs.net/DarcsWiki/CategoryBinaries for getting darcs.

Once you have darcs installed, the command to get Interhack is

    darcs get http://interhack.us/trunk interhack

You can then later receive new patches by typing (in the interhack directory)

    darcs pull

+----------+
| BUILDING |
+----------+

Now assuming you have the source code, it's time to actually get the
dependencies required for Interhack. If you want the Mastermind solver, you'll
need a C compiler (we recommend gcc). To build the Mastermind solver, just type
'make'. Eventually a pure-Perl alternative will be provided to avoid this
dependency.

The Interhack developers have no qualms with using the CPAN (a repository for
useful Perl modules for things like reading a ttyrec, or grabbing a webpage).
If running Interhack produces an error that resembles "Can't locate $FOO.pm in
@INC <list of directories>", you need to install modules via CPAN. Use "cpan -i
$FOO" (possibly as root). For example, if you get "Can't locate Term/ReadKey.pm
in @INC <list of directories>", you'll need to run "cpan -i Term::ReadKey".

To install these dependencies in one go, you can use:

    perl Makefile.PL
    sudo make installdeps

+--------+
| CONFIG |
+--------+

    mkdir ~/.interhack
    cp eido-config ~/.interhack/config

+---------+
| RUNNING |
+---------+

For now you have to be in the Interhack source directory to be able to run the
program.

Interhack takes two options:
perl interhack.pl nickname
perl interhack.pl ttyrec

Specifying a nickname (or at least enough of a nickname to be unique) will
autologin as that user. See the CONFIG file for information about autologin.

Specifying a ttyrec (this is disambiguated from nickname by ending in .ttyrec)
will play back the ttyrec using Interhack (so you get the fancy colors and
whatnot). This is useful for debugging, and in general just watching a ttyrec.
The playback is pretty rigid, it only has two commands: p to pause/unpause, and
q to quit.

+---------------+
| CONFIGURATION |
+---------------+

See CONFIG for information about the configuration file.

+-----------------+
| TROUBLESHOOTING |
+-----------------+

If Interhack displays things incorrectly, it's probably because you're using
a terminal that doesn't understand the escape sequences we print. There's
a fix, though!

Run Interhack in screen. It will correctly interpret what Interhack prints out,
then gives your terminal something it will understand. Running the "screen"
command will give you a splash screen, then a new terminal. Just go to your
interhack directory and start it up.

Both screen and NetHack look for ctrl-A. Unfortunately for casual users, screen
has priority here. You can tell screen to use a different escape character by:

   Hitting Ctrl-A to tell screen to expect a command.
   Hit :, this should invert the color of your bottom line.
   Type in: escape ^\\
   Hit enter.

This will remap your escape key to ctrl-\ which nothing I know of uses. Now
NetHack will see your Ctrl-A keystrokes correctly.

+---------+
| DEVNULL |
+---------+

Interhack runs on the annual /dev/null tournament using the "ih_server"
feature. If you set "server 'ih_server'" in your config, then when you start
Interhack you'll see some connection messages, then you'll be back in your own
shell. This shell has all the functionality of Interhack enabled (try
"echo Elbereth"). From here you can ssh to devnull and play normally. When you
use ssh, you must specify the -t option (so,
"ssh -t myname@nethack1.devnull.net").