TomeNET

(2.1) Installing/updating TomeNET                                               
---------------------------------

Basic installation:
-------------------
Go to https://www.tomenet.eu/ (or one of our personal pages) to download the
latest client. It is recommended to use the installer package if available for
your OS (especially Windows).
If you choose an archive file instead, extract it to a new directory and make
sure the pathnames are preserved.
Then just run..
Windows:        'TomeNET.exe' (or double-click the desktop TomeNET icon,
                               provided you used the installer download.)
Linux:          the 'tomenet' binary.
OS X:           'TomeNET.command' (which prepares and runs 'tomenet'.)

Updating via reinstallation:
----------------------------
If you want to update your existing TomeNET and cannot/don't want to use the
TomeNET-Updater, you can also just download the latest TomeNET version again
and install it over your existing TomeNET installation.
This process will not delete any of your macros, screenshots, or configuration
files - EXCEPT for your 'lib/xtra/sound' and 'lib/xtra/music' folders if you
install a TomeNET package that comes with a sound pack or music pack
respectively. Those will then be replaced.

So if you have done custom changes to your sound and/or music pack that you
want to keep, you should rename those folders prior to reinstallation.
This is not a hack but actually the official way TomeNET handles multiple
audio packs and allows you to switch between them in the = X menu! The only
convention you must follow is that music pack folders must start with 'music'
and sound pack folders must start with 'sound'.
For example rename your customized 'music' folder to 'music.myown' and it will
be safe to install a new version of TomeNET over it, the custom music folder
will be left untouched and automatically be recognized by TomeNET afterwards,
allowing you to switch between your music.myown pack and the official pack that
was just installed by pressing '=' key (options menu) followed by Shift+X.

If you install a TomeNET version that comes with sound or music pack over an
existing installation that doesn't have one of these, you will end up with
an audio-wise "upgraded" installation that now features sound and/or music
as it should (depending on what you installed).

Updating via the TomeNET-Updater:
---------------------------------
Starting with version 4.5.7a, TomeNET comes with an updater tool that should
work on most platforms. If it doesn't on yours, please contact us and provide
details about which operating system you are using.

To update your TomeNET client or the sound pack or music pack, just run the
'TomeNET-Updater' and click on the according button.
The only prerequisite is that you must have '7-Zip' installed, a great, free,
open source archiver that beats WinRAR and WinZIP easily. You can get it from
www.7-zip.org.
Important: You should exit the game before attempting to update it!
Note for LINUX:
The Linux version of the TomeNET-Updater no longer requires 7zG (the graphical
user interface of 7-zip), so you do not need to compile it yourself if your
repository packages don't provide it. If you want to compile it anyway then
see (2.1a) and there "a) Automatic audio pack installation - LINUX". That
paragraph has short instructions on how to compile 7-zip from source in Linux.

If you didn't have a sound or music pack installed yet, by "updating" it from
the TomeNET-Updater these will actually be installed.


Optional dependencies on Windows:
---------------------------------
To make use of all features of the game, there are the following optional
programs you can install on Windows:
- explorer and xcopy (these are already installed by default in any Windows
  version): For installing/updating audio packs and opening URLs and folders
  from within the knowledge (~) menu.
- 7-zip (www.7-zip.org): For installing or updating audio packs.
- Firefox or Chrome or Chromium: For making PNG screenshots.

Optional dependencies on Linux:
-------------------------------
To make use of all features of the game, there are the following optional
packages you can install on Linux:
- xdg-utils (for xdg-open) on X11: For opening folders and URLs from whithin
  the knowledge (~) menu.
- xclip: For using copy/paste capabilities.
- coreutils (for readlink) and Firefox or Chrome or Chromium:
  For making PNG screenshots.
- 7-zip: 7zG on X11, 7z on GCU. For installing or updating audio packs.


Installation details / custom installation:
-------------------------------------------
If you want to read up about installation specifics, command-line options,
compiling your own client, using an archive file for extraction instead of a
self-running installer etc., read on here.

If you choose an archive file, extract it to a new directory and make sure the
pathnames are preserved.

Note: If you decide to download the 'test client' instead of the client of the
latest stable version number, be aware that it might stop working correctly
unexpectedly because it's undergoing development, possibly forcing you to
redownload it.

Covered in the following are Windows, Linux, OS X, FreeBSD:


Windows:
--------
It is recommended to get the installer package instead of the zip archives.
You can safely install TomeNET over an already existing installation (just
make sure to quit the game first!), the installer will not reset/delete your
existing macros, settings or custom audio packs (it will only overwrite things
in 'lib/xtra/music' and 'lib/xtra/sound' ie the official audio packs).

The Nullsoft Installer framework (NSIS) the Windows installer uses is an open
source project (https://sourceforge.net/projects/nsis/), yet annoyingly there
are a few badly maintained virus scanners that may give a wrong positive
warnings for NSIS. In the past Avira was notorious for it but it seems they
fixed it, nowadays it seems to be Acronis instead, at least at the time of
writing these lines. Anyway, you can safely ignore those *ahem*.
A fun fact: The TomeNET Winwdows version has never seen an actual Windows
system but was created purely on Linux.

If you used the ZIP archive instead of the installer, 7-zip is recommended for
extracting it. It's a free and open source zip-tool of outstanding performance
that works on all platforms. Grab it from https://www.7-zip.org/ .

There is also a manual in your TomeNET folder, the file is called
"TomeNET-Guide.txt". Double-click to read it. It is recommended to not open it
in Wordpad, but either in Notepad or in any web browser of your choice, because
Wordpad tends to warp the layout badly.
Alternatively you can find the latest version of the manual online for browsing
and easy searching, on the TomeNET homepage (https://www.tomenet.eu/).
The guide can even be accessed inside the game by pressing ? twice or ~g.

If you're tech savvy, you could decide to edit the game configuration manually,
but that is not really required. Continue reading below if you want to do that.

If you are using Valve's Steam and are interested on how to integrate TomeNET
into it, check out (2.1d) :D.

On how to run the game, connect to the game server and start playing, continue
reading at (2.2)!


Windows - Manually editing the configuration file (if you're tech savvy):
-------------------------------------------------------------------------
You may edit the file "TomeNET.ini" and do some changes to your likings, like
setting up window positions (note that the game will remember window positions
changed via dragging the windows around, which is an easier way), or choosing
font size (look into lib/xtra/font directory to see available fonts).
Further you can specify an account name and password to be filled in
automatically, and various other things.

Windows command-line options:
-h                      Displays this list of command-line parameters
-C                      Compatibility mode for ancient servers (deprecated)
-F <fps>                Set client internal engine fps (default is 100)
-k                      Don't disable numlock on client startup
-l<Account> <Password>  For example -lGandalf geheim
-m                      Skip motd (message of the day) on login
-N<character name>      For example -NDruidor
-p<Port>                For example -p19348
-P <path to lib dir>    Sets the path to TomeNET's 'lib' folder
-q                      Turns off loading/initializing of audio ('quiet mode')
-R <character name>     Character name to choose and auto-reincarnate it
-u                      Disables automatic LUA script updating
                        (You should NOT use this option!)
-v                      Automatically save chat log on exit (exclusive with -V)
-V                      Automatically save complete message log on exit
-w                      Disables weather effects
-x                      Don't save chat/message log on exit (don't prompt)
<ip address>            for example 37.187.75.24

(Skip down to (2.2) to continue reading.)


Windows (cross-compiling from Linux):
-------------------------------------
Install the usual compiling environment with gcc or clang.

For the crosscompiling part, install mingw32 and take note of the folder prefix
it installs to, in most cases it will be 'i686-w64-mingw32', so it will install
to /usr/i686-w64-mingw32/...  with notable subfolders include/, lib/ and bin/.
Edit the makefile.mingw to have MINGW_TARGET reflect the prefix.

For regexp search (only used for the guide-search in c-cmd.c) you will probably
need a regexp lib, mingw-libgnurx should work fine.

Next, for sound support you will have to download at least SDL2 and SDL2-mixer
v2.6 or higher. Optionally you can get SMPEG for MP3-support or MikMod for
various mod-file suport, and libogg/libvorbis, but it's not required.
Make sure you do _not_ download the designated 'mingw32' tar.gz from the
libsdl.org page but get the generic src tarball at the top of that page
instead.
Detailed instructions for installing SDL are provided by Mikael here:
https://muuttuja.org/tomenet/howto-install-sdl.txt
These aim at SDL 1 though, we have now migrated to SDL 2, so they don't apply
directly anymore, but they might still be helpful in some way.

Adjust the makefile.mingw accordingly, which means setting SDL_CONFIG to the
sdl2-config script that should now be installed inside your mingw-prefix folder
so probably it looks like SDL_CONFIG = /usr/$(MINGW_TARGET)/bin/sdl2-config.

You should be able to cross-compile the client now. First a paranoid clean-up,
then build the client (or server I guess, if desired):
make clean
make tomenet.exe
(Or for the server: make tomenet.server.exe)


Linux (using pre-compiled client):
----------------------------------
Make sure that ncurses and crypt libraries are installed, package names are
usually libncurses5 and libxcrypt (formerly libgcrypt11). Depending on your
system, there might or might not be numbers appended to the package names
(eg libxcrypt1 instead of libxcrypt), just do a generic search.
Enter the 'tomenet/' folder and type:
        ./tomenet
to start the game.

If you get a font-related error ("Font not found: 9x15") please see PROBLEM 56
in chapter Troubleshooting (9.8).


Linux (compiling from source):
------------------------------
There are additional distribution-specific information on Mikael's website at:
https://muuttuja.org/tomenet/installation-linux.php
(It's linked on www.tomenet.eu -> "Links".)

You can get the source from www.tomenet.eu, also see (1.1).

How to compile the game binary:
Go into '/tomenet/src' where the file 'makefile' is located.

Dependencies, that you must make sure you have installed:
C-devel, X11-devel, ncurses, ncurses-devel and crypt libraries.
The package names are usually (may vary depending on the build system):
build-essential, xorg-dev, libncurses5, libncurses5-dev, libc6-dev, libxcrypt
(formerly libgcrypt11) and libxcrypt-dev. Depending on your system, there might
or might not be numbers appended to the package names (eg libxcrypt1 instead of
libxcrypt), just do a generic search.

Since version 4.4.5 which supports music and sound via SDL2, you also need
libsdl2-mixer-devel, libsdl2, libsmpeg. Usual package names (SDL2, not SDL!):
libsdl2-mixer2.6, libsdl2-mixer2.6-dev, libsdl2debian, libsdl2-dev,
(preferably libsdl2debian-pulseaudio, eg under Ubuntu), libsmpeg0,
libsmpeg-dev and optionally more formats like libogg/libvorbis.
Sometimes instead of the libsdl2* packages your system might
provide the packages simply named 'sdl2' and 'sdl2_mixer' instead.
If you don't want to use audio, edit the makefile and compare the two
paragraphs titled 'Without SDL' and 'With SDL' and edit the makefile
accordingly, to compile it without SDL audio support.
NOTE: If you are compiling the above packages yourself, make sure that you
install the specific audio format libs (smpeg, ogg/vorbis/..) _before_ you
install libsdl2-mixer, so its configure script will recognize those formats
and enable support for the according file types.
Note that sdl2_mixer must be at least version 2.6!

Enter these two lines:
        make clean
        make tomenet
and the binary 'tomenet' will be created in this folder 'tomenet/src'.
IMPORTANT NOW: You need to move the binary 'tomenet' that was just created one
               level upwards, so it's placed in the 'tomenet/' folder!
After that, go up one level into your 'tomenet/' folder. There type:
        ./tomenet
to start the game.

If you get a font-related error ("Font not found: 9x15") please see PROBLEM 56
in chapter Troubleshooting (9.8).


Configure TomeNET on Linux by editing config files or setting environment vars:
(This is not really required. Most things can be configured by in-game menus or
by dragging/positioning the game windows with the mouse.)
-------------------------------------------------------------------------------
To configure which windows are visible and what font they use and all sorts of
other options, edit the file ".tomenetrc" which should be in your home folder
(or specify alternative location via -f command-line option, see below).

Note: If the game client's positioning of windows doesn't work on your system,
you can use other means such as KDE's native window positioning (right-click
the windows and modify the "special window settings" or "special application
settings") or the tool Devilspie (should be in your default repository) if
you're on Gnome or Xfce or anything else. 'gdevilspie' may also be available,
which is a graphical version of devilspie.

Alternatively to using the .tomenetrc file for window configuration, you can
also set environment variables. These settings will override .tomenetrc.
Environment Variables:
TOMENET_X11_FONT_SCREEN (height and width of main window cannot be changed)
TOMENET_X11_WID_MIRROR, TOMENET_X11_HGT_MIRROR, TOMENET_X11_FONT_MIRROR
TOMENET_X11_WID_CHOICE, TOMENET_X11_HGT_CHOICE, TOMENET_X11_FONT_CHOICE
TOMENET_X11_WID_RECALL, TOMENET_X11_HGT_RECALL, TOMENET_X11_FONT_RECALL
TOMENET_X11_WID_TERM_4, TOMENET_X11_HGT_TERM_4, TOMENET_X11_FONT_TERM_4
TOMENET_X11_WID_TERM_5, TOMENET_X11_HGT_TERM_5, TOMENET_X11_FONT_TERM_5
TOMENET_X11_WID_TERM_6, TOMENET_X11_HGT_TERM_6, TOMENET_X11_FONT_TERM_6
TOMENET_X11_WID_TERM_7, TOMENET_X11_HGT_TERM_7, TOMENET_X11_FONT_TERM_7
Use the 'export' command to set them, eg:
        export TOMENET_X11_FONT_SCREEN=8x13
        export TOMENET_X11_WID_TERM_4=80
        export TOMENET_X11_HGT_TERM_4=24
TOMENET_X11_FONT sets one font globally for all windows. It's overridden by
the window-specific font variables listed above though.
Depending on your system, some possible fonts are usually:
4x6, 5x7, 5x8, 6x9, 6x10, 6x12, 7x13, 7x14, 8x13, 9x15, 10x20, 12x24.

POSIX command-line options:
-h                      displays this list of command-line parameters
-c                      force command-line interface instead of X11 etc.
                        Use it if you want to run the client within a terminal.
-C                      compatibility mode for ancient servers (deprecated)
-e                      Create file 'tomenet.log' instead of displaying
                        error messages in the terminal
-i                      ignore the ~/.tomenetrc config file
                        This option must come before any -f options!
-f<config file>         source (use) a specified config file. This is actually
                        cumulative and does not cause the standard .tomenetrc
                        to not be loaded. To _only_ load this config file and
                        ignore .tomenetrc, specify -i option together with -f
                        option and make sure that -i comes first!
                        The last file that is read is used as default config
                        file and any changes that are saved will be saved to
                        this file.
-F <fps>                set client internal engine fps (default is 100)
-l<Account> <Password>  for example -lGandalf geheim
-m                      skip motd (message of the day) on login
-N<character name>      for example -NMagnet
-p<Port>                for example -p19348
-P <path to lib dir>    sets the path to TomeNET's 'lib' folder
-q                      turns off loading/initializing of audio ('quiet mode')
-R <character name>     character name to choose and auto-reincarnate it
-u                      disables automatic LUA script updating
                        (You should NOT use this option!)
-v                      automatically save chat log on exit
-V                      automatically save complete message log on exit
-w                      disables weather effects
-x                      don't save chat/message log on exit (don't prompt)
<ip address>            for example 37.187.75.24

Full command-line example:
        ./tomenet -p19348 -lGandalf geheim -NGandalf 37.187.75.24

If your name contains spaces, it is neccessary to put a '\' in front of each.
Example:
        ./tomenet -p18348 -lIron\ Man geheimer 37.187.75.24
..if your account name is 'Iron Man'.

(Skip down to (2.2) to continue reading.)


Mac OS X (using pre-compiled binary; tested with Snow Leopard 10.6.6):
----------------------------------------------------------------------
Run the file 'TomeNET.command' to start the game.

If TomeNET starts only in console mode (or even not at all if you're not within
a terminal but just clicking it from within a file manager window) that means
that TomeNET didn't find X11.
In this case, install XQuartz and run TomeNET.command from within it. TomeNET
should now launch correctly with a GUI, ie various game windows.

If you're tech savvy and want to manually edit the TomeNET configuration file,
see "Configure TomeNET on Linux" further above.

Otherwise skip down to (2.2) to continue reading.


Mac OS X (compiling from source; tested with Snow Leopard 10.6.6):
------------------------------------------------------------------
Basically use the same instructions as for Linux above. Additionally:

-You probably want to have XQuartz (which provides X11) installed to run
 TomeNET not just in console-only mode.

-To actually install gcc you will need to install the 'xcode' package, which
 contains gcc. Download the correct xcode version for your Mac OS X version
 from developer.apple.com. For this you will first need to create a developer
 account (choose the free account version of course).

-Download the required packages (tar.gz/tar.bz2 files from ftp.gnupg.org,
 ftp.gnu.org/pub/gnu and www.libsdl.org) listed in the Linux installation
 instructions above and extract, compile and install them each via the usual
   ./configure
   make clean
   make
   sudo make install
 command chain from a terminal window.
 Note: libsdl2_mixer can be found on www.libsdl.org too, by clicking on the
 "Libraries" menu and searching for "mixer".
 Note that sdl2_mixer must be at least version 2.6!

 If you have trouble installing those source packages, you could try to simply
 use MacPorts to fetch them, at https://www.macports.org/.

Dependencies:
-libgcrypt depends on libgpg-error, which you will need to install too.
-libsdl2_mixer may complain about missing dependencies (at least Ogg Vorbis is
 required for TomeNET, since it's the official audio format - the rest is only
 needed if you add custom audio files in the according file formats):
  -Ogg Vorbis library (www.xiph.org -> libogg and libvorbis) for OGG file
   support, which is what the official TomeNET audio files are.
  -SMPEG library (icculus.org/smpeg) for MP3 file support. (libsdl2_mixer's
   configure script May also list additional notes regarding the environment
   variable SMPEG_CONFIG, don't miss them.)
  -MikMod library (mikmod.raphnet.net) for various module music support.
  -FLAC library (flac.sourceforge.net) for FLAC file support.

-If you mess with compiler-related environment variables and paths and for
 whatever reason get a 'compiler cannot create executables' error when trying
 to ./configure packages, just close the terminal and re-open it, to reset all
 vars.

It is recommended to use the makefile called 'makefile.osx' for compiling.
If for whatever reason you try to use an unmodified Linux makefile to compile
then you might run into the following problems:

-ncurses starts hiding some internal properties at v5.7+ which causes a
 dereference error when trying to compile main-gcu.c. This seems to be a
 Mac OS X specific problem since only the ncurses shipping with Snow Leopard
 has NCURSES_OPAQUE set to 1 while the Linux version has not.
 To fix it, add
   -DNCURSES_OPAQUE=0
 to CFLAGS compiler options in the makefile.

-For preprocessing LUA files the 'cpp' variant does not work, the 'gcc' variant
 must be used instead: Edit the makefile, locate 'cpp' and comment out the two
 cpp-related lines and uncomment the two gcc-related lines, if it's not already
 like that by default.

-If the LIBS linker flags in the makefile say '-lcrypt' that will cause an
 error about library not being found if using libgcrypt. In that case change it
 to '-lgcrypt' to fix it.

-If the LDFLAGS are empty the linker will throw a not-found error 22. Fix this
 by moving (or copying) the -L... library search-folder parameters from LIBS to
 LDFLAGS so it contains all lib paths.

When you have successfully compiled TomeNET, see the paragraph above about
"Mac OS X (using pre-compiled binary" for additional information on running it
regarding X11 aka XQuartz.
If you get an error that libraries are not found, try setting your library path
to your TomeNET folder before running TomeNET:
  export DYLD_LIBRARY_PATH=.
  ./tomenet


Configure TomeNET on Mac OS X:
------------------------------
Most things can be configured by in-game menus or by dragging/positioning the
game windows with the mouse, and do not require manual editing.

See 'Configure TomeNET on Linux' above, it's basically the same, including all
the available POSIX command-line options.
Mac OS X also uses the ".tomenetrc" configuration file which should be in your
home folder, same as Linux.


TomeNET on FreeBSD:
-------------------
Should be same as on Linux, except that the "8x13" standard font might not get
found, preventing TomeNET from starting. A fix according to "N der Fuenfte":
  root% cd /usr/ports/x11-fonts/xorg-fonts
  root% make install clean
  root% # restart X server, if in doubt, just reboot PC.