Source ReadMe file for Return of Dr. Destructo v0.9.
-------------------------------------------------

Content:

1. Foreword
2. Dependencies
3. Building Return of Dr. Destructo
	3.1. Windows
	3.2. Linux
	3.3. MacOS
4. General notes on architecture & code organization

-------------------------------------------------

1. Foreword

I decided to make my remake of Island of Dr. Destructo open-source for several reasons. One of them is to make sure the game could be ported
anywhere by anyone. My main development platform for now is Windows and I barely have time and willpower to make it compile on Linux, much
less on MacOS or something more esoteric.

However, I would not recommend to use this code as a learning example. It's very far from perfece, since I cut corners whenever I could, simple
because I wanted to see the game complete, and writing better code sometimes take too much time when you can hack something together and get
instant results.

You may still find some insights here, though, but be sure to read section 4.

-------------------------------------------------

2. Dependencies

Return of Dr. Destructo depends on the following external libraries:

* Allegro 5.0.6 (http://www.allegro.cc/). NOT Allegro 4.4, which is included in most Ubuntu-related repositories!
* TinyXML 2.6.2 (http://www.grinninglizard.com/tinyxml/). WARNING! The game will use HACKED header files to allow correct reading of strings with spaces! Files included with the game.
                 I may consider porting the code to TinyXML-2 in the following versions.
* Lua 5.1 (http://www.lua.org/)
* Luabind 0.9.1 (http://www.rasterbar.com/products/luabind.html). WARNING! Do not use DLL version! Only STATICALLY linked version works!
* Boost 1.44 (http://www.boost.org/). Necessary files are included with the game code, no need to download anything.

-------------------------------------------------

3. Building Return of Dr. Destructo

3.1. Windows

If you use Visual Studio 2008, you should have no problems. Just open DrDestructo2.sln and build it.
There is only one small catch: Allegro library headers and binaries are NOT included with this distribution,
so you will have to download and install it yourself.

If you use other version of Visual Studio, you will have to build all the dependencies yourself. Though luck.

If you use some other, non-Microsoft compiler, you probably know what to do.

3.2. Linux

There is a (very dirty auto-generated) Makefile provided with the game which should let you build it after
you install all the dependencies. So, just type 'make' in the root directory of source tree. There is no
'install' target and binary name is weird.

3.3. MacOS

TODO

-------------------------------------------------

4. General notes on architecture & code organization

Code organization:

The code lacks any filesystem-level organization, since I do my coding in Visual Studio and prefer to organize it
in IDE. The only non-dependency folder in the source tree is Engine, where my Allegro wrapper resides (it's
not an actual game engine, and it's quite bad wrapper, don't pay attention to it).

If you open the solution, however, you will find that code is organized in the following filters:
Engine - aforementioned wrapper
Game - the rest of the code
	Components	- classes, containers and utility structures related to GameObject Components (see below)
	Menu		- base menu class, helpers and some concrete menus
	Processors	- classes that process Components
	Prototypes	- classes that store base information for creating Components, deserializers that read them from XML files and Managers that store them
	States		- classes that encapsulated concrete game states

This organization is still far from perfect or even consistent, but, well...

Architecture:

The project began as an experiment in using Component-Oriented Programming paradigm. It failed. The only place where COP is used
is GameObject class, and it's not quite necessary there. All in all, I found COP to be too cumbersome for most tasks, unless you
wrap component creation in some opaque way.

Now, I'm getting ahead of myself. What IS Component-Oriented Programming? Basically, it differs from OOP in one thing: where OOP
considers everyting to be an Object, which hides things inside it and operates on them when required, COP treats everything as a
Component - a transparent structure on which operations are performed by external processors. OOP Objects in games tend to become
a large, multi-functional things, containing a lot of data and functionality. This lessens opportunities for code reuse and universal
processing.

In COP, each entity is a component, which may, in turn, consist of other components. All components of same type are stored in the
same pool and iteration over them is very simple. For example, if I have Players and Bullets classes which have to have the same
data for collision detection (bounding boxes or spheres) and I want to process them in a single iteration, I don't have to store
Players and Bullets in the same place (which requires them to share a base class), but only their physic components:

class Player
{
   PhysicComponentRef m_physComp;
   Player()
   {
	  m_physComp = CreatePhysicComponent( "player_phys_comp_prototype" );
   }
   // ... Other data
};

class Bullet
{
   PhysicComponentRef m_physComp;
   Bulelt()
   {
	  m_physComp = CreatePhysicComponent( "bullet_phys_comp_prototype" );
   }   
   // ... Other data
};

void PhysicProcessor::Process( int dt )
{
   for ( PhysicComponentPool::iterator iter = m_physComponents.begin(); iter != m_physComponents.end(); ++iter )
   {
       PhysicComponentRef physComp = *iter;
       // Process movement & collisions...
   }
}

If you take it one step further and make all Components inherit IComponent interface, you can even have classes with dynamic number
of components, just like in dynamic languages! Although it may not be a best idea. I didn't do it.

Another bonus here: you can remove a component from object at any time without destroying object itself or adding flags. If your Ship
no longer needs have a Physic component, but still have to be drawn (a good example: you want to play a death animation after it was
destroyed, but it no longer have to collide with anything), you may just call m_physComp.Destroy() and its Physic component will no
longer be processed in PhysicProcessor without even any need for NULL checks, or flags or anything. AND you may add it right back, if
you need! Or even exchange one Physic component for another.

The downside to this all is that all Components of the same type have to be really the same. Inheritance and virtual functions kind of
spoil the concept. So, if some of your objects need to have incompatible Physic components, you will have to create several different
Components, several storages and several processing functions.

Another thing: components are not meant to have access to other same-level components, which leads to data duplication. For example,
if you Ship component contains PhysicComponent and RenderComponent, they may not read current ship coordinates from each other. You
will have, at some point, where both components are known, to copy coordinates from the primary sources (PhysicComponent) to the rest
of components that need them (RenderComponent, AIComponent, whatever).

Just as with OOP, COP could be used for all your code. This is where I failed: I only use COP for some elements of the game. For example,
all images and texts in GameStates should be RenderComponents, but instead I draw them directly. I take no pride in this :)

In fact, only GameObjects use COP model. GameObject represent anything you can see on the game screen which moves, interacts with other
game objects via collisions etc.


Another pirce of architecture is idea of GameStates. Any game has some kind of State Machine in it: there is Menu state, Level state,
GameOver state etc. However, sometimes it is nice to have more than one state at the same time. So, Return of Dr. Destructo actually
have a Stack of states. Actually, it's not quite a stack: you can only push new states on top, but you can remove any state. In this
case, all states above it would be removed, as they are considered "children" states of removed state.

States could be switched from any piece of code which has access to IGameContext, but the switch does not happen instantly. Actually,
change of state happens during the next frame.