Legends: Alpha and Omega
------------------------
 test
This is the Legends Linux build.
It includes an OpenGL client, and also a console-only dedicated server
build and a utility to continually respawn a dedicated server.

Client Requirements:
--------------------
A hardware accelerated OpenGL X11 system.

A modern kernel, 2.4.xx seriesfdsf
A newish libc, 6 or above.   
A sound card attached to /dev/dsp
A mouse.
An FPS player.

Dedicated Server Requirements:
------------------------------
Basically, libc...

Quick update notes:
-------------------
- The precompiled script file's extension was changed from .dso to .ofn

Installation:
-------------
Legends can be extracted anywhere on your system using normal
gunzip and tar.

Example:
download http://hosted.tribalwar.com/legends/legends.tar.gz
mkdir legends
cd legends
tar xvfz ../legends.tar.gz


Starting up the client
-----------------------
./runlegends is a shell script that will start up the OpenGL client.
It modifieds LD_LIBRARY_PATH to point to the current directory, so
that the included libSDL.so can be loaded. 

libopenal.so is also provided with the client, as it's a newer build
than what is dished out on most current linux distributions.

libopenal.so is loaded via dlopen() using the path to the LinLegends
binary as is normally available in argv[0].

You can also get more verbose console output from the client by
running ./runlegends -console, or by referring to ~/.legends/console.log

Please include a copy of your console.log or any console output when 
reporting bugs.

Dedicated Server:
-----------------
A legends dedicated server may be started by running:
./lindedicated -dedicated -mission legends/data/mission/Sol.mis


Dedicated server timer latencies:
---------------------------------
The long explanation:
---------------------
In order for legends to give up CPU cycles to the operating system,
it calls the linux nanosleep() function every cycle. This is essentially
what provides a deterministic timer for the game's simulation "Tick".

For the short explanation, read further down. The following paragraphs
become rather technical

Legends asks for a 1ms nanosleep(). Due to the nature of the linux and
intel timers however, the minimum nanosleep() one is likely to get is
10ms, or a little below. Some systems have latencies much higher than
10ms, and this affects the "ping" people will receive from your server.

The higher your system timers latency, the more time it will take to 
produce game ticks, and this will increase players's packet processing
rates, and "ping latency".

For systems with timer latencies < 10ms, it isn't really a problem, but
if you are able to reduce your kernel latency to as close as possible
to 1ms you will be able to offer your players the best experience possible.

This, however in most cases requires a realtime or fairly new kernel. 
I've been told that Redhat9 kernels are compiled by default with a low
latency sleep timer.

The other option, is to have the dedicated server NOT use nanosleep()
at all, and just spin in a tight loop, processing packets, and sim 
events. This gives the best possible player performance, but will also
make it appear that legends is using 100% of cpu time when players
are connected to the server. When no players are connected the server
will sleep regardless, to reduce cpu time, seeing as it doesn't matter
if the server is doing nothing. When players join though, you will see
the dedicated server CPU utilisation skyrocket. 

This might be disconcerting to administrators, but when you consider 
the fact that scheduling of the process is now up to the kernel, 
instead of legends yielding using nanosleep() it isn't really 100%
cpu utilisation. Legends still makes a lot of system calls to send
and receive packets which will inevitably yield processing slices
to the other processes running on the system, and the server process
may still be preempted at any point by the kernel. Of course, not 
using sleep at all, causes the simulation ticks to be determined by
the kernel scheduler. If you have a realtime kernel this might
be a good option, but in general this is not preferred.

To complicate matters further, on some kernels a nanosleep() requesting
a 0ms delay will yield a "cool" latency of around 8-9 ms which is
really what we're after. 1ms being perfect, 8-9 being "as good as it gets"
due to the overhead involved in making system calls.

The problem with a zero ms nanosleep appears to be that some systems
may consider it a non-yield, i.e, an immediate return, so that instead
if giving away time to the scheduler, the sleep causes the same 100%
cpu utilisation situation dicussed previously.

A zero nanosleep on most systems however, yields nicely, and gives the
best resolution timer, making this the most attractive option.

A lot of disconnected waffling I realize, so the try the following short
explanation rather.

The short explanation:
----------------------
On startup of a dedicated server, legends will time your sleep latency,
and suggest a sleep timer mode. IT WILL HOWEVER DEFAULT to using the cpu
friendly "1 ms nanosleep" mode if no sleep mode argument is specified
to stop sysadmins from raising their hackles.

There are three modes which can be specified on the commandline:

-sleep 		- 	Legends will use a 1ms nanosleep() to  yield to the kernel. 
				This will reduce cpu usage but on timing challenged systems
				this may increase ping latency by the amount reported.
				This is now the default mode, so that there is no accidental
				thrashing of servers that get installed with defaults. 
				On my test system though, this yields a minimum client-server
				ping time of 18ms.

-nosleep	-	Legends will not use nanosleep() at all to yield.
				This will provide the best possible ping to players but
				the server will be in a tight loop, and appear to use
				99% of available cpu time. On my test system this produces
				wildly varying results depending on system load. This
				option is best used on realtime scheduling kernels.

-zerosleep	-	This will cause the dedicated server to attempt a 0ms
				nanosleep. On most non-hires kernels this will cause a <10ms
				sleep latency. This is probably the BEST option to use
				and will provide the least latency on MOST kernels whilst
				still yielding time for scheduling in a sane way.

				On my test system this produces an 8ms client-server ping,
				which is the best result.

				Danger, Will Robinson. Some systems may consider a 0ms
				nanosleep something that should just return immediately, 
				which will once again cause a 100% cpu utilisation issue.
				This is entirely kernel version/platform/system dependant.

				For this reason -zerosleep is NOT the default. You
				may try -zerosleep on your dedicated server, and join
				with a client to see what the CPU utilisation does.

				If it does not skyrocket then it should be safe to use
				this option, and is recommended.

				Using -zerosleep implies -sleep mode.


Just as a note: Windows suffers from exactly the same timing issues, 
the linux version just gives server admins a choice.



ispawn:
-------
ispawn is a utility to continually monitor a Legends dedicated server
via it's UDP port, and to restart the process if it stops responding,
or has exited.

ispawn takes 2..n parameters:

ispawn <port> <executable> <arg1...argn>

example:
./ispawn 28000 ./lindedicated -dedicated -mission legends/data/missions/Sol.mis
will start up a dedicated server, monitor it every 30 seconds for a "alive" 
response on port 28000, and start with the mission file "Sol.mis" loaded.

ispawn pings the server every 30 seconds to check on its livelihood.

Home directory and preferences:
-------------------------------
Legends uses ~/.legends as the home directory for Legends to store temporary
files and client preferences.

~/.legends/legends/prefs contains a series of scripts that stores your custom
configuration of keybinds, field of view, etc...

~/.legends/legends/scripts/*.ofn are byte-code compiled versions of the legends
scripts. Sometimes, when a script is modified, the .cs.ofn (compiled) and .cs
(code) versions may become out of sync. In such a case it may be necessary to
remove all .cs.ofn files from your ~/.legends directory in order to force 
the engine to recompile the byte-code compiled .cs.ofn versions of the scripts.

<IMPORTANT NOTE> The extension for precompiled scripts has changed from .dso 
to .ofn as of Legends 0.3.0. Update any scripts you have that may depends on
this specific extension. </IMPORTANT NOTE>

This happens very rarely, but may occur when clock skew has happened, or the
engine has messed up the timestamping.

As general best practice, it's always good to delete the .cs.ofn files after
the development team has released a patch, which may contain script updates.


The data archive (.unf) format:
-------------------------------
In the directory where Legends was extracted, you will find a nubmer 
of *.unf data files. These files are nothing more than .zip files which
contain the game data and script files. You can extract these files with,
for example, "unzip data.unf" to retrieve the files in the archive.

Legends will scan all .unf files found first, add it to it's internal
"VFS" file system, and then override any files that are the .unf files
with files found in the normal raw file system directory structure.

Example:

legends/scripts.unf contains a file, stored with the path 
"scripts/server/init.cs"

To override the "scripts/server/init.cs" with a modified version, simply
create a subdirectory called scripts/server, and create a custom init.cs
file.

When the engine loads, your custom init.cs file will override the default
init.cs file included in the compressed .unf archive.

This can be done for textures, art, or script files, in fact for any file
that is contained in the default .unf archives.

If you want you may package up your own scripts, and art in a new .unf file.
Simply create the archive with the appropriate relative paths.


Getting patches:
----------------
Legends is typically updated about once a week, as we add new art, and 
features to the game. Updates are available via rsync:

rsync://hosted.tribalwar.com/linlegends 
  or 
rsync://themasters.co.za/linlegends

If you don't know how to use or obtain rsync, visit http://rsync.samba.org/

The typical rsync command to update legends would be:

cd <dir where legends was extracted>
rsync -arvz --progress --stats rsync://hosted.tribalwar.com/linlegends .

Occasionally completely new tarballs may be made available on our website.


Deleting precompiled script (.ofn) files
----------------------------------------
Once you have updated your copy of legends either via tarball, or rsync
it is typically a good idea to delete the precompiled script files under 
~/.legends

A useful command to do this is:
find ~/.legends -name *.ofn| xargs rm -f

Bug Reporting
-------------
You can report bugs, and interact with other Legends players at the
Legends forums located at http://hosted.tribalwar.com/legends/


Troubleshooting
---------------
You can play the game without sound, but it will suck. If you have
things such as arts or esound running, make sure they non-exclusively
access /dev/dsp, or disable them before running legends.

ALSA isn't currently supported, but probably will be pending a newer
libopenal.so build.

Fonts: Legends makes extensive use of Helvetica, and the Lucida Console fonts
It will try to fallback to adobe-courier, and adobe-helvetica if unable to
load these fonts. Finally, in panic, it will attempt to use the courier-10
pitch font if it's unable to get an appropriate font.

Make sure your X isn't font-starved.

More verbose debug output may be obtained by running ./runlegends -console
You can also refer to  ~/.legends/console.log for the same output.

Bugs may be reported at http://hosted.tribalwar.com/legends/bugtracker/


Editor 
------
The engine includes a built-in map and GUI/interface editor. To access
the map editor, host a game by clicking "Start" and choose any mission.
Once inside the simulation, press Alt E to access the game editor.

Help is available by pressing F1, or by reading some of the good ole FM
available at www.garagegames.com. You can also try the Legends forums
for help, or refer to www.tribes2maps.com where a lot of mappers using
the original Torque engine is concentrated.

To access the GUI editor (used for creating controls, and interfaces)
press Alt F1.


Build Monkey:
--------------
contact: rodent@themasters.co.za or rodent@mighty.co.za to chat to me 
about the build, give advice, criticism, or whatever. Loose beers, women,
etc. are also gratefully accepted. Ok, I lied. Just beer. I'm married.


Copyright:
----------
Legends is copyrighted by the Legends Development team. The game,
and binaries can be distributed freely. Refer to our website at
for more information about licensing restrictions.

Website:
--------
http://hosted.tribalwar.com/legends/

IRC:
----
irc.dynamix.com #legends

