T1 Netcode

===============================================================
Short overview of how Tribes 1 interacts with netcode and demos
===============================================================

 1. The game waits for a packet of data. This can come from a demo
    or from an underlying net connection, the game doesn't
    differentiate.
 
 2. The packet is passed off to the NetStream object.
 
 3. The NetStream object will update the packet rate/size if needed
    and pass off the rest of the data to each of 3 objects:

    A. EventManager will process any non-game events
    B. PlayerPSC will process player interaction with the server
    C. GhostManager processes ghosting objects from the server
    
 4. This same sequence happens in the same order for writing packets
    to the server. Obviously a demo source will ingore the writing packets
    phase.


 NOTE. A demo actually has more than just the packet data from the server
       embedded. It also has player move information to locally update
       the controlled object which is the exact data sent to the server
       when the demo was recorded. 
       
       It also has IDACTION's for zooming embedded, which is how you are
       able to see when a player using the default zoom methods zooms. This
       is also why a player using a custom zoom script that only alters 
       $pref::playerFoV will appear to never zoom in a demo.



=========================
Source Class Descriptions
=========================

T1NetStream (abstract)
----------------------
An abstract (unusable on it's own) class to process Tribes 1 data packets.
T1NetStream handles packet rate and size updates to the server and 
reads and writes to the 3 Tribes handler objects: 
 - EventManager, which handles non-game events such as player messages, 
   team adds, and such
 - PlayerPSC, which handles local player control over game objects, 
   command map information, etc.
 - GhostManager, which handles ghosting game objects from the server and
   keeping them updated

T1NetStream is abstract as it doesn't care where it's source information 
is coming from. You must provide a derived class to feed it data, the 
two obvious choices being a Demo reader class (to stream data from a 
Tribes demo), and a UDP connection class to read live data from a
physical server.

T1Connection
------------
Implements a UDP packet handler for the Tribes 1 protocol. T1Connection
negotiates connection instantiation, packet ordering and drops, and sends 
alerts up to a T1NetStream object.

T1NetLayer : T1NetStream
------------------------
Derived class to source packets from a udp connection (T1Connection). Also
takes care of writing packet data back out to the server.


T1Demo : T1NetStream
--------------------
Derived class to source packets from demos. Nothing special


T1EventManager
--------------
T1EventManager processes non-game object releated events such as player 
messages, datablock events on first join, remoteEvals from the server, etc. 
It reports any interesting events back to a T1Game class, which can then do 
with them what it likes.

The EventManager also handles sending remoteEvals back to the server, which 
is how you interact with the server. It will resend any remoteEvals that are 
dropped.

T1Game
------
T1Game is the final stop for game events that you can act on. It also handles
a T1NetStream object which it passes off game initiation and update calls to.

You choose which type of T1NetStream you want by using OpenDemo or OpenServer,
set any appropriate options you need (SetTimeScale, SetPlayerName, etc) and
then Start / Poll the T1Game object until you're ready to quit. The underlying
T1EventManager and T1NetStream classes will filter events up to your T1Game
derived object for you to act on.

All event functions are stubbed to do nothing by default, except a few like
OnDataFinished_Chain, which remoteEvals a dataFinished / CGADone, or 
OnTeamAdd_Chain, which fakes a CGADone since we don't have any mechanism in 
place to handle ghosting. You only need to override the events you're 
interested in watching in your derived class.



===============
Generic Methods 
===============

Close
-----------------------
Resets the object to an un-opened state, initializes settings
to defaults.

If members don't require initialization, they are left untouched and only 
handled by constructor/destructor. Close does not need to be called before
deleting an object, it is assumed the destructor will call it.

Open
-----------------------
Open prepares the object to be run. Parameters may be passed for 
initialization.

Start
-----------------------
Start attempts to set the object running. If Start is unable to do this, it 
returns false.

Poll
-----------------------
Poll queries the object and allows it to process some work. If the object is 
done and/or ready to be closed, it will return false.

=================
Table of Contents
=================

 * How to compile the client
 * Understanding the Engine
 * How to extend the T1Game object for your program
 * How to listen to events with your new T1Game client
 * Recording demos 
 * Tables for functions


=========================
How to compile the client
=========================

Visual Studio 2003 and 2005 projects are included, as well as a GNU Makefile
for building on *nix systems.

NOTE: If you are on a big endian system, you must define __USE_BIG_ENDIAN__ 
in T1.h

NOTE: On Solaris, you must run "make solaris" which adds "-lsocket -lnsl".

It succesfully compiles and runs a demo on all of the Source Forge 
compile-farm system (they don't allow outbound network access):

  [x86] Linux 2.6 (Debian 3.1)
  [x86] Linux 2.6 (Fedora FC2)
  [x86] FreeBSD (5.4)
  [x86] NetBSD (2.0.2)
  [AMD64] Linux 2.6 (Fedora Core 3 on AMD64 Opteron)
  [Alpha] Linux 2.2 (Debian 3.0)
  [PPC - G5] MacOS X 10.2 SERVER Edition
  [Power5 - OpenPower 720] SuSE Enterprise Server 9
  [Sparc - R220] Sun Solaris (9)
  [x86] OpenBSD 3.8
  [x86] Solaris 9
  
It succesfully compiles and runs a demo / joins actual Tribes servers under
Linux 2.6 (Gentoo, x86), OpenBSD(?, x86), and Win2k (VS2003/2005, x86).


========================
Understanding the Engine
========================

To understand what's going on in the various systems, here are the functions
to breakpoint or inspect:

  * Packet reading and decoding
    - T1Connection::ReadPacketHeader in T1Connection.cpp
    - T1NetStream::ReadPacket in T1NetStream.cpp
    
  * Demo reading
    - T1Demo::Poll in T1Demo.cpp
    
  * Event decoding
    - T1EventManager::ReadPacket in T1EventManager.cpp
    
  * Connecting to a server
    - T1NetLayer::Start in T1NetLayer.cpp


Hierarchy of functions:

Client->Demo:

+ T1Game::Poll
|----+ T1Demo::Poll
     |----+ T1NetStream::ReadPacket
          |----+ T1EventManager::ReadPacket
               |----+ T1Game::OnEvent
               |----+ T1Game::OnEvent
               |----+ T1Game::OnEvent
               
Client->Server:

+ T1Game::Poll
|----+ T1NetLayer::Poll
     |----+ T1Connection::Poll
          |----+ T1NetStream::ReadPacket
               |----+ T1EventManager::ReadPacket
                    |----+ T1Game::OnEvent
                    |----+ T1Game::OnEvent
                    |----+ T1Game::OnEvent


================================================
How to extend the T1Game object for your program
================================================

The simplest way to make a T1 engine is to extend the T1Game object with
and empty class:

/*
	My First Tribes client!
*/

#include "T1.h"
#include "T1Game.h"
#include "Console.h"

class MyT1 : public T1Game {
};

int main( int argc, char *argv[] ) {
	Console::Init( ); // console init
	T1::Net_Startup( ); // net init
	
	MyT1 *game = new MyT1;
	game->OpenDemo( "my_demo.rec" );
	// or game->OpenServer( "IP:127.0.0.1:28001" ); to join a server
	
	if ( game->Start( ) ) {
		while ( game->Poll( ) ) {
			T1::Sleep( 20 );
		}
	}

	delete game;
	T1::Net_Shutdown( );
	Console::Close( );
	
	return ( 0 );
}


===================================================
How to listen to events with your new T1Game client
===================================================

-------------------------------------------------------------------------------
NOTE: If you ever need to disconnect from the server (using T1Game::Close,
T1Game::OpenLastServer, etc), ONLY do it in your ::Poll function. Doing it
in your OnMissionReset or any other On???? function will destroy all 
buffers and connection state information while you're in the middle of the
game's message loop. 

See "Hierarchy of functions" to see why deleting the connection anywhere but
in ::Poll would be bad. Having a class flag such as "mReconnect" or something 
that you check in ::Poll is the best way to handle connection 
disconnects/reconnects.

If you override any of the non-virtual methods in T1Game (Poll, Start, Close, 
etc), you must call T1Game::Poll, T1Game::Start, etc, at the top of your 
function.

Of the virtual methods, OnDataFinished, OnMissionReset, or OnTeamAdd need to be 
chained. Call "T1Game::OnDataFinished", "T1Game::OnMissionReset", and 
"T1Game::OnTeamAdd" at the top of your overriddent function. This is to ensure 
that remoteDataFinished and remoteCGADone are called properly so demos record
properly.
-------------------------------------------------------------------------------



The previous example is a fully working client, but there isn't much it can
do. To get some feedback on what is happening, we need to extend some of
the T1Game events. The list of extendable events are in T1Game.h, and are the
On??????? declarations with "virtual" in front. 

Let's add OnPlayerSay to our MyT1 class so we can see what players are 
saying. Server messages are also sent to OnPlayerSay, except they have an
id_player of 0 instead of the normal 2049+.

class MyT1 : public T1Game {
	virtual void OnPlayerSay( int id_player, int type, char *msg ) {
		Console::Print( "SAY: %d(%d): %s\n", id_player, type, msg );
	}
};

Re-run your demo and the chat and server messages will be echoed! Of course 
they aren't very useful since we have no idea who each player id is, so 
you could add an OnPlayerJoin method to keep track of which player each id is. 
You can also use Console::PrintColor to color the message according to what 
type it is (team chat, global chat, server messages, etc). Event types are 
stored in T1EventManager.h.

The included main.cpp is an example client with handling for most events. When
it is connected to a live server, it will also respond to "!test" in chat with
with "Bot compiled on [DATE] for [OPERATING SYSTEM]"


===============
Recording demos
===============

T1Game::

• Console.cpp
• bitStream.h
• bitStream.cpp
• Console.h
• Howto.txt
• Info.txt
• main.cpp
• Makefile
• T1.cpp
• T1.h
• T1Demo.cpp
• T1Demo.h
• t1demoformat.txt
• T1EventManager.cpp
• T1EventManager.h
• t1events.txt
• t1eventsother.txt
• T1Game.cpp
• T1Game.h
• t1netcode.2005.sln
• t1netcode.2005.suo
• t1netcode.2005.vcproj
• t1netcode.sln
• t1netcode.suo
• t1netcode.vcproj
• T1NetStream.cpp
• T1NetStream.h
• t1structure.txt