
diff -r 7e6d373d8c98 -r bbc30317fa6a doc/kishna.tex
--- a/doc/kishna.tex	Tue Dec 09 02:46:51 2008 +0000
+++ b/doc/kishna.tex	Tue Dec 09 02:52:11 2008 +0000
@@ -115,12 +115,12 @@
 
 \section{Program architecture}
 The program consists of four main parts: Graphics\&Input, GameState,
-Network and Physics. Each part contains various classes the relations
+Network and Physics. Each part contains various classes; the relations
 show up in the doxygen generated documentation of the program.
 
-The program starts from Application class and it then starts Engine
-which creates GameState, Graphics and different network related
-things. Physics simulation is started when GameState is created.
+The program starts from the Application class, which then starts the Engine,
+which creates GameState, Graphics and the Network Client/Server. Physics
+simulation is started when GameState is created.
 
 GameState contains PhysicsWorld which inherits from Terrain and
 contains a list of PhysicsObjects. GameState also contains Player and
@@ -132,7 +132,7 @@
 separate PhysicsObject, and is either folded away, being thrown or
 attached to the terrain.
 
-Graphics and input are handled in their own classes. Graphics has an
+Graphics and Input are handled in their own classes. Graphics has an
 Input object which contains InputHandler objects for various classes
 of input. One such object is PlayerInput which affects the GameState's
 LocalPlayer. Other object is GuiInput which just modifies what the GUI
@@ -144,7 +144,6 @@
 
 \section{Data structures and algorithms}
 
-
 \subsection{Basic data structures}
 
 \begin{itemize}
@@ -247,42 +246,112 @@
 the product of the interval $(h)$ and an estimated slope that is
 defined as $\frac{1}{6}h\left(k_1+2k_2+2k_3+k_4\right)$.
 
-% TODO: something network related?
+\subsection{Input}
+
+All input is represented as a bitmask, composed of bits from \textsl{enum PlayerInputBits}. Additionally, the Graphics
+code uses some local-only flags defined in \textsl{enum GuiInputBits}. These bitmasks are built using the
+\textsl{InputHandler} class, which is defined as a generic template. On every update, it goes through its keymap,
+which is defined as an array of InputKeymapEntry structs. These contain the input bit, flags, and up to two keycodes.
+The InputHandler then reads keycodes from the keyboard and sets bits in the current input mask based on the entry
+keycodes (which may be negative to indicate the the specified key must NOT be pressed down) and any key-repetition
+rules defined by flags.
+
+Key repetition is implemented using InputKeyRepeatQueue, which contains a list of InputKeyRepeatEntry's. To rate-limit
+keypresses, the input code is push()'d to the queue, and it eventually removed from the queue once it expires, or
+the key is released.
+
+The Graphics code then reads the input mask from time to time, resetting the InputHandler's mask to zero, and passes 
+it on to LocalPlayer, which then either handles it locally, or sends it to the remote server.
+
+Since some inputs like walking, aiming and moving up and down the rope are time-dependant, the InputHandler also tracks
+how many milliseconds the input mask has been held, and this time delta is applied by LocalPlayer.
+
+\subsection{Network}
+
+The network code is implemented as separate NetworkServer and NetworkClient modules, which use a common high-level
+network interface, NetworkSession and NetworkObject.
+
+The low-level details are implemented using ClanLib's CL\_IPAddress (referred to as NetworkAddress) and CL\_Socket.
+NetworkUDP provides an interface to send and receive NetworkPackets to/from specific NetworkAddress's across a 
+NetworkSocket. NetworkTCP provides a NetworkTCPTransport interface, which can send/receive NetworkPackets on a
+NetworkSocket (using NetworkBuffer to buffer socket I/O). NetworkTCPServer is a listen() socket which accepts client
+connections as NetworkTCPTransports, and NetworkTCPClient is a NetworkTCPTransport that's connect()'d to some address.
+
+NetworkSession encapsulates some simple application server/client behaviour, it can function as both a server, and
+represents remote NetworkSessions (either clients or servers) as NetworkNode objects. These then provide an interface
+to send and receive NetworkPackets on specific NetworkChannelDs, using either TCP or UDP as a reliable/unreliable
+transport.
+
+NetworkObject then implements a kind of object-oriented network protocol. A NetworkObjectController (with specific
+subclasses for server/client behaviour) uses a NetworkSession to send messages on a specific NetworkChannelID. This
+controller then creates and looks up NetworkObjects (again, with specific subclasses for server/client behaviour).
+Clients and servers can then communicate by having the server construct new NetworkObjects (which are allocated an
+unique id), and then sending NetworkPackets with a specific NetworkMessageID type on a specific object. The message is
+then delivered directly to the NetworkObject instance on the remote end of the connection, or a new NetworkObject is
+constructed using the data in the NetworkPacket. This enables an easy way to send events for specific objects, and
+referr to other objects in these messages.
+
+NetworkServer then implements a core NetworkServer class which has a NetworkSession and a
+NetworkObject\_ServerController. Players that connect are represented as NetworkServerPlayers, which inherit from
+LocalPlayer and NetworkObject\_Server. This class then overrides methods in Player to deliver messages on the Player
+object to the clients, or to create new NetworkServerProjectiles. NetworkServerProjectile inherits from Projectile and
+NetworkObject\_Server, and sends messages when constructed, upon hitting a player, and upon being destroyed.
+
+NetworkClient is a bit more complicated as it must handle both the LocalPlayer, and a number of RemotePlayers. Again,
+NetworkClient has a NetworkSession and a specialized NetworkClientController, which then creates objects of various
+other NetworkClientClasses upon receiving messages from the server.
+
+Two of these classes are NetworkClientLocalPlayer and NetworkClientRemotePlayer. Both inherit from
+NetworkClientPlayerBase, which inherits Player (virtually) and NetworkObject\_Client. NetworkClientLocalPlayer and
+NetworkClientRemotePlayer then also inherit LocalPlayer and Remote player virtually, respectively.
+NetworkClientPlayerBase, contains the common methods that update the Player's state in response to messages received
+from the server. NetworkClientLocalPlayer overrides handleInput to send the input mask to the server, and
+NetworkClientRemotePlayer can handle remote clients disconnecting from the server.
+
+In addition, there is a NetworkClientProjectile class, which inherits from Projectile and NetworkObject\_Client.
+this is created when a Player fires a Weapon on the server, and handles events received from the server like the
+projectile hitting a player (inflicting damage), or being destroyed (by hitting the terrain or something similar).
+
+When the player first connects to the server, the server sends a large packet containing the terrain array to the
+client, which updates its own GameState world's terrain array with the received data.
+
+Currently, the client only sends handleInput using unreliable UDP messages, and the server only sends position updates
+(as sent in response to handleInput events) unreliably. All other events are sent using reliable TCP.
 
 \section{Known bugs}
 \begin{enumerate}
 \item If player dies while rope is attached the rope will still be
-  attached when the player spawns.
+    attached when the player spawns.
 \item If rope is thrown without releasing it first, rope will pull worm
   when midair
 \item Collisions with the terrain are only tested for the edgepoints
-  of the polygon.
+    of the polygon.
+\item Existing Player ropes and Projectiles are not sent to the client when it connects, which can cause apparent
+    glitches in what the terrain looks like and how players move.
 \end{enumerate}
 
 \section{Tasks sharing and schedule}
-We could have followed the schedule a lot better. Now we basically
-forgot the whole schedule and did things always when we had some spare
-time. And still we were late of the schedule. The good thing was that
-almost always all team members were doing things at the same time and
-communicating, either we were at the same place or everyone was on
-IRC.
+We could have followed the schedule a lot better. We basically forgot the whole
+schedule and had a lapse in activity during the middle weeks, which caused us
+to be delayed in terms of the schedule. The positive side was that we almost
+always had all the team members working on their own things in parralel and
+communicating together; either at Maari or using our IRC channel.
 
 Tasks sharing worked pretty much as planned. Tero did all the network
-code and everyone else did everything that had something to do with
-physics and graphics. Most of our eye candy is done by Marko who was
-the responsible person for graphics. Marko, Eric and Atle made
-basically everything physics related. Most of the time every team
-member was working together so most of the code has been written as is
-as a result of a common agreement.
+code and worked on keeping the rest of the code network-safe. Most of our
+eye-candy (like terrain textures) was done by Marko, who was responsible for
+the graphics. Marko, Eric and Atle worked on everything Physics related plus
+the GameState/Player/Rope/etc code. Most of the time all team members were
+working together, so the code was written using common agreement.
 
-We feel that the workload was shared quite even. % Or does someone disagree with this?
+We feel that the workload was shared reasonably evenly. % Or does someone disagree with this?
 
 \section{Differences to the original plan}
 The original plan was quite loose and it let us make decisions during
-development, which was a good thing. The basic structure of the
-program is pretty much as the one we thought about while
-planning. Though, many parts of the game have many levels of
-abstraction (of course).
+development, which was a good thing. The basic structure of the program is
+pretty much as the one we thought about while planning, although the Network
+code ended up being a fair bit more simple-minded due to lack of time to
+implement more UDP-based behaviour.
 
 % References
 \begin{thebibliography}{99}




