
Dune Legacy: Developer Guide
----------------------------

This text is intended for new developers that want to contribute to Dune Legacy. It tries to describe the basic design concepts of Dune Legacy.


Introduction
-------------------

Dune Legacy consists of different parts. The 3 main parts are as follows:

Data Management:
These classes are responsible for loading the different media formats (pictures, sounds-effects, music, video). Everything that needs to be loaded from files is loaded through these classes. The DataManager manages all the different media. It provides all these media to the other parts of dune legacy.
Files: /FileClasses/*

Menu:
The menu is shown at the start of the game and let the user specify what scenario/map he wants to play. Every menu screen is basically a endless loop of drawing the screen and processing the input. If you click on a button to open a new menu screen the event handler calls the endless loop of this new menu. Thus the event handler code for the main menu is just stopped when a sub menu is opened and you will get back there if the submenu quits.
Files: /Menu/* , GUI/*

In-Game:
When a game is started the main loop in GameClass is started. This loop consists of 3 main tasks: First the screen is draws, then the input is processed and finally the game logic performed. These 3 aspects are separated strictly. The first two are not time critical. But the game logic must be performed with strict timing. Otherwise the game would have different speed on different computers. Another issue is very important with the third aspect: It has to be deterministic to ensure a network game is in sync.
Every Unit/Structure is implemented in it's own class. These classes are derived from ObjectClass. All objects have an unique ObjectID and every linking to a unit/structure should use these ObjectID instead of a pointer. Through the class ObjectTree it is possible to map an ObjectID to a pointer to that object. But it is important to not save this pointer somewhere for reuse later. It might happen that the unit/structure is destroyed and the memory for this object gets deleted. Thus the pointer gets invalid. Before deleting an object the ObjectTree is informed and thus can later inform you that the ObjectID is no longer valid.
Files: /* , /units/* , /structures/* , ( /GUI/* )



Chapter 1: Input Handling and Game Logic
----------------------------------------

As pointed out in the introduction input handling and game logic are strictly isolated aspects. These two parts can only communicate through so-called "Commands". Consider for example a right-click on the map to order a unit to move somewhere. The input handling will finally ending with calling HandleActionClick() of the unit that should be moved. This method will add a Command to the CommandManager. The CommandManager saves this Command and schedules it to be performed later. In the simplest case it is scheduled to be performed in the next game cycle. But consider a network with low latency. Then the command will be scheduled for e.g. 10 game cycles later. These 10 cycles are needed to send the Command to all other computers.
The CommandManager will be called every game cycle and performs all commands that are scheduled for this cycle. Reconsider our example from above. The command that was added by HandleActionClick() gets now fetched from the command queue for this cycle and gets executed. It calls DoMove() from this unit and the unit finally starts moving to the new destination.
To sum it up: The input handling is only allowed to call methods that do not change the game state or that add Commands. These later methods have a name that starts with "handle" and end with "Click". The game logic may call any method but there are some methods that have a special name. They start with "Do". These methods actual issue some things that a player can do with a unit/structure. These methods are called by the AI and when executing a command.

Chapter 2: Coordinate systems
-----------------------------

There are mainly 3 coordinate systems to deal with: Screen, World and Map.

Map-Coordinate System:
The map consists of a number of tiles. The original dune 2 used mostly 64x64 maps. Each tile has a 2-dimensional coordinate. Both coordinate values are between 0 and 63. A coordinate in this form is called map coordinate in dune legacy.

World-Coordinate System:
Each tile is 16*16 pixels wide. This value is defined by BLOCKSIZE. The world coordinate system describes every pixel on the map not only every tile as the map coordinate system does. Thus conversion between Map and World coordinate system is simply a muliplication or division by BLOCKSIZE. (If converting Map to World you will get the world coordinate of the top left corner of the tile)

Screen-Coordinate System:
If the user clicks somewhere on the game board you have to first check if the click is really on the game area itself or on the gamebar. And then you have to convert these values to world or map coordinates. The class ScreenBorder will manage all this for you. 



