******************************************************
*-------OPENDUNGEONS---------------------------------*
******************************************************

FREQUENTLY ASKED QUESTION

1. What is OpenDungeons ?
1A. Is it free ?
1B. What license is it distributed under ?
1C. How much it is playable ?
1D. When it is completed ?

2. Building OpenDungeons:
2A. Help!, I cannot compile OD !
2B. Help!, I cannot run OD !

3. Gameplay:
3A. Controling Player's Field of View (Camera)
3B. Key-shortcuts
3C. Running Console and Console's commands

4. May I contribute to OpenDungeons ?
4A. I wrote a patch ...
4B. I cannot do programming ...

5. Developer's FAQ
5A. Why Ogre3D ?
5B. Why STL ?
5C. General ideas and design patterns
5D. Code conventions
5E. What code constructs to AVOID

6. Used libraries and abbreviations:
6A. Libraries
6B. Abbreviations


1. What is OpenDungeons ?
-------------------------

OpenDungeons is an open source, real time strategy game sharing game elements with the
Dungeon Keeper series and Evil Genius. Players build an underground dungeon which is
inhabited by creatures. Players fight each other for control of the underground by
indirectly commanding their creatures, directly casting spells in combat, and luring
enemies into sinister traps.


1A. Is it free ?
----------------

It is free of charge, but more over it's free as in freedom of speech, that is, you are
permitted to redistribute, modify, and copy this game further under GPLv2.


1B. What license is it distributed under ?
------------------------------------------

Code is under GNU Public License. Any added new code must be compatible with that license.
Game content comes under Creative Commons license.


1C. How much is it playable ?
-----------------------------

OD (as of September 2014) is still in Alpha, this means you can have a basic but already stable gameplay experience:
- Select tiles of dirt walls to dig them and gold to collect money.
- With money, you build the basic room: Treasure rooms, Sleeping rooms, Training grounds, ...
- The creatures you have will either dig the tiles of dirt, train, sleep, eat, or fight on their own.
- You can grab and drop your own creatures on claimed tiles near enemies to let them fight.

- You can also play with friends on using the join/host game buttons.
The game is supporting fixed alliances on certain map, so you can compete together against the AI.

A few level are provided. Read their description in the loading menu for more info.


1D. When will it be completed ?
-------------------------------

Nobody knows, it is a spare-time project and we always need help!


2. Building OpenDungeons:
-------------------------

On linux, make sure to install the required dependencies (§ 6A).

On Windows, MSVC 11 (2012) is required to build the game and you'll need the following SDKs:
(Make sure to either compile from source or take the MSVC 11 (2012 SDK))
- Ogre 1.9
- CEGUI 0.8
- boost (same version than Ogre)
- DirectX
- SFML 2.x

Then, in either way, you'll need to install cmake.

On linux, "cmake ." and "make" should make you able to compile the game.
On Windows, you'll have to start the Cmake Gui, and configure and create a MSVC 11 project file.


2A. Help!, I cannot compile OD !
--------------------------------

USE C++11 WHEN COMPILING OD ! General notice : some of the files (some AI*.cpp) use
explicit construct of new C++ standard : C++11.

Each compiler has it's C++0x or C++11 flag, for GNU g++ it's :
"g++ --std=c++11"

On CMake, it is normally added automatically to CMAKE_CXX_FLAGS.
Or type bash cmd 'cmake-gui' it opens graphical configurator, unfold the CMake node. And find
the CMAKE_CXX_FLAGS flag.


2B. Help!, I cannot run OD !
----------------------------

-- I get runtime error exception similiar to:

>>Mesh: Loading Dirt_10001000.mesh.  An internal Ogre3D error ocurred: OGRE
EXCEPTION(6:FileNotFoundException): Cannot locate resource Dirt_10001000.mesh in resource
group Autodetect or any other group. in ResourceGroupManager::openResource at
/home/bender/Bureau/ogre/OgreMain <<

Make sure you have the game data files installed. If you're using the official repository,
all the needed data should be provided.

On windows, please note also that the necessary dlls must be copied in the same directory
than the game data along with the main OD binary in order to let the game run.
(You can grab an official Windows game copy to get them in the sourceforge OD downloads)


-- I get runtime error something like : "CEGUI : OGre3d system not initialized '

You have a wrong CEGUI version. Actually, it might be right one, but it was compiled against
diffrent OGRE3D package, and now it is loorking for it's interface while it isn't there in
memory ;). Either build your own version from sourcepackages OR ENSURE THAT your package
is built for currently installed OGRE3D package's version. For most well-maintained linux
distros it means they are from the SAME REPOSITORY.


-- Just after program start I get :
 "   An internal Ogre3D error ocurred: OGRE EXCEPTION(7:InternalErrorException): Could not load dynamic library RenderSystem_GL.
 System Error: RenderSystem_GL.so.1.9.0: cannot open shared object file:
 No such file or directory in DynLib::load at /tmp/buildd/ogre-1.9-1.9.0+dfsg1/OgreMain/src/OgreDynLib.cpp (line 109)  "

Normally, cmake does detect the render plugins location, but in this case,
you'll have to edit the plugins.cfg and/or plugins_d.cfg files copied by CMake when invoked
and change the "PluginFolder=" line to where the GL Render system shared lib is located.
(Usually the Ogre's libraries' native directory e.g.:
"PluginFolder=/usr/lib/x86_64-linux-gnu/OGRE-1.9.0/ " or "/usr/lib/OGRE")


3. Gameplay:
------------

Please note that there are more game controls available than listed here,
but only the working ones were added. More will be added as the game gets improved.


3A. Controlling Player's Field of View (Camera)
------------------------------------------------

Camera movement: (Read as in a US layout keyboard)
- keyboard arrows ( up, down, left, right) or W A S D.
- Rotate left or right: Q and E.
- Rotate up or down: Page up and down
- Move higher/lower: Mouse wheel or Home, End.

-- Game:
You can left click on creatures to grab them and right click on a neutral
or tile of your color to drop them there. Note that you can grab several of them
without needing to drop the last one each time.

You can click on a room type on the bottom the screen in the room menu,
and click on a tile of your color to create a room tile if you have enough money.

You can click on a dirt or gold wall to make your creature dig it.
Creatures digging gold tiles will then deposit the gold on the treasury room tiles,
and make you have money, permitting you add more room tiles.

You can drag dirt or gold tiles to select a square of tile to dig/undig.

-- Editor:
You can left-click on a creature and to pick it up, and right-click to release it.
You can click on tiles to add walls of the currently selected type.
You can change the current seat id of a room using the 'Y' key.


3B. Key-shortcuts
-----------------

- Tilde/F12: Open Console

-- Game:
- T: Return to the Dungeon start location.

-- Editor:
- R: Change the tile type.
- T: Change the tile fullness. (With a fullness of 0, you actually remove walls, and ground tiles of the given type.)
- Y: Change the current seat id of the rooms/traps added.


3C. Running Console and Console's commands
------------------------------------------

Console commands needs testing.


4. May I contribute to OpenDungeons ?
-------------------------------------

For bugs, patches, propose help, say hello or anything related,
drop by our forums:
http://forum.freegamedev.net/viewforum.php?f=15


4A. I wrote a patch ...
-----------------------

Please:
- Make sure your patch compile fine without adding new warnings,
and that the game is still running fine, this means:
- Start the game editor and play with it a bit.
- Start the game and make sure the basic game actions are still working.
- Make sure the feature you've coded has got no weird regressions or unbearable drawbacks.


4B. I cannot do programming ...
-------------------------------

I you are ready to test the game and present thorough bug reports,
we can certainly appreciate your help.
I you can do modeling, or if you're interested in improving the game GUI,
and are rather at ease with image manipulation, there is always something
to do ;)
Please drop by our forums. (Link at §4)


5. Developer's FAQ
------------------

5A. Why Ogre3D ?
----------------

As of 2008 (when project started) Ogre3d was leading and rapidly developing opensource
3d Engine, and only one of the few similar available (the other being Irrlicht) . The
general consensus is it's praised for its object-oriented design (by fans of
object-oriented programming) and minimal effort to manage common situations. On the other
hand it's criticised for its object-oriented design (by people who don't like OOP) and
lack of extensible documentation and paper-books (although both exist to small extent).


5B. Why using STL ?
-------------------

It has been argued in the past that the use of STL (Standard Template Library)
was not something relevant when doing a game,
especially a 3D game, notably because of the STL's use of exceptions.

Well, at first, STL's state, C++ language and practice have fortunately evolved in 10 years.
Secondly, it is a rather curious to ask that to us since we're using Ogre3D,
which is a 3D gaming library using exceptions itself. Ask them first ;)

STL is nowadays a well famous standard, used even in military-grade applications,
and we do think it's properly shaped to be used in our game, rather than implementing
custom-made templates with forcefully poorer quality and reinvent the wheel.
There is always something to improve in our code, though, and you are welcome to propose patches.


5C. General ideas and design patterns
-------------------------------------

The game code is using a standard client/server paradigm, where the server has his own thread and
the client+rendering part has got another one.
Simply put, this means the game internally keeps server data used as reference for the game state
and communicates with the client part to make it stay in sync. This is working that way for local
and lan games. This way, we ensure more robust code for lan games.
This also means that if you want to update the game state, you have to "ask" the server to do so. ;)

Overall, and anyway, try to have a clear view of what you want to achieve first, and start simple,
components by components. Once you have a clear view of your components and how they interact
to each others, you might find clever to add a few design pattern here or there.

Starting by using a design pattern and applying it to something new right from the start
is a bad idea, especially in a spare-time project.


5D. Code conventions
--------------------

http://opendungeons.sourceforge.net/?q=code-style-guidelines
http://forum.freegamedev.net/viewtopic.php?f=35&t=5363


5E. What code constructs to AVOID
---------------------------------

Avoid using any functions from the old libC library, eg: <cstdio>
(that is the standard library of the C language).

We beg anyone to stop using one-character names for variables (poor capture
of most editors' search function).
We also beg people to stop using temp* as a variable name.
A variable always has a role, and can be named accordingly.

Do not use Singletons which depends on other non-singleton classes
(that is your code shouldn't do any >>hidden<< singleton initialization.)
--> If you happen to do that, maybe it's meaning the singleton is simply a component
of the mother class and can be accessed exclusively from the mother class,
and can be un-singleton-ed.


6. Used libraries and abbreviations:
------------------------------------

6A. Libraries
-------------

Ogre - Version 1.9.x
CEGUI - Version 0.8.x
Boost filesystem, locale, system (same version than the one used by Ogre)
SFML - Version 2.x
OpenAL (Required by SFML)

- Included in the repository (in 'dependencies/'):
AngelScript


6B. Abbreviations
-----------------

OD = OpenDungeons
NST = New Scorpio TileSet (from April 2013)
STL = Standard Template Library
FPP Mode = First Person Player Mode, when incarnating a creature in game.
