Copyright 2012 Simon Ley alias "skarute"
This documentation is published under the GNU Free Documentation
License v1.3 or later. You can find a copy of this license in
"fdl-1.3.txt" or at <http://www.gnu.org/licenses/>.

########################################
Faunis Developers' Documentation
########################################

This documentation is still incomplete. I'm working on it. :o(

1.   Concurrency
Lots of synchronised statements are used to avoid problems with concurrency. To avoid deadlocks, all class fields are reserved from top to bottom as their definitions appear in the class. After them, all variables not part of the class are reserved.

2.   Code structure
In general, the classes are structured in three main packages: "client" contains everything only needed by the client, "server" everything only needed by the server, and communication contains everything which is needed by both or which is exchanged during client-server communication. All exchanged communication messages are called orders and carry a prefix of two letters to better distinguish between them. The first letter indicates where the order is from (there are some few exceptions where this isn't true, though), while the second letter indicates who the recipient is. C stands for Client, B for Butler, M for MapManager.
Playable characters are represented by the Player class on the server side and by the PlayerGraphics class on the client side. Certain player data relevant for both sides is in GraphicalPlayerStatus which primarily stores information about how the character is displayed. Note that the PlayerGraphics instance can completely be produced from the GraphicalPlayerStatus object.

2.1   Client side
There is the Client class which represents the main client functionality and has the main method. The user interface is represented by the class GraphWin (basic gaming interface) and GameWindow (specialised for client functionality).

2.1.1   Animation
The more complicated part on the client side is the animation stuff: A character frame can be drawn as a whole (compact AniCompoType) or consist of separate limb images (limbed AniCompoType). The compact style is easier to create (since even if you decide to isolate the frame into single limbs, you will have to draw it as a whole anyway just to see if the limbs are proportional), but the limbed style has the advantage that later the character can keep its facial expression during emotes, amongst others.
All frames that form one animation cycle are stored in a Bone instance, which therefore is determined by character class, animation / emote state, body part and direction.
An animation can have different termination behaviour: It can simply return to the default standing animation (revert AniEndType), it can be repeated endlessly (repeat AniEndType), or it can stay in the last frame (end AniEndType).
Except for standing and walking, every animation can be triggered as an emote for now. Note that a walk command will remove any emote in progress.

The GraphicsContentManager is responsible for loading and storing these Bones and will provide them if requested. He also keeps information about AniCompoType and AniEndType. The reason why he is also used on the server side is because the server has to verify if an emote is valid, and must know its AniEndType to handle it correctly. The methods for loading the image files are actually not called on the server side.

2.1.2   Animators and Movers
Whenever a player is moving, a Mover is instantiated on both client and server side (stored in Client resp. MapManager). His task is to regularly adjust the player's position, thus he has an own Timer that frequently executes a TimerTask, in our case an instance of RoughMovingTask on the server side or SoftMovingTask on the client side. Reason for this differentiation is that on the server side it's enough to simply change the coordinates by one step during every task execution, but on the client side that would look too rough and we want a smooth transition between fields. That's why the SoftMovingTask also adjusts a special attribute, the so-called deltaLevel (I couldn't come up with a better name, I'm sorry). It indicates the relative position shift with relation to the recorded coordinates. The deltaLevel is only one value though for a two-dimensional shift we'd need two, however we still have the player's direction, so it is sufficient.
Like with movement, there's a similar approach with animation: The Animator class similarly has its own timer and timerTask to increment a player's frame counter and to handle animation termination. All Animators are kept by the Client class. Since there is no need to have frame counters on the server side, there are no Animators there.

2.2   Server side
The server side main class is MainServer, where at last all data references are hold. There is a Reception class which steadily looks out for new connecting clients and redirects them to a newly created Butler.
The Butler class represents a client on the server side. Besides the reception, he is the only one directly communicating with him, checking and implementing his orders as well as returning the orders meant for him. When the client disconnects, the butler is destroyed.
For each map of the game, there exists a MapManager who manages the list of players / butlers that are currently on this map. Every player / butler who holds an active player must be registered at a mapman. Whenever something happens on the map that others should perceive, the mapman sends orders to all butlers to notify them about the change.

3.   Threads
Client:
- main thread: frequently redraws the screen
- one thread to handle user input
- one to respond to server orders

MainServer:
- main thread: Only used for initialisation and to make the window visible

Butler:
- one to handle orders from the client side
- one to handle orders from the server side (mapman etc.)

MapManager:
- one to handle the butlers' orders

Reception:
- one to receive incoming clients

Furthermore every Animator and Mover has its own thread.

4.   What isn't implemented so far
- maps in general
- everything that turns a MMOG into a MMORPG: Fighting and attributes
- inventory and items
- security and encryption (minimum requirements for a stable version!), data backup
- better administration
- and much, much more...

