fysxasteroids/engine/doc/Usecases.h

/** \page usecases Usecases
 *
 * This page contains some information on how various tasks are supposed to be
 * performed with this engine. It should help understand how the internals
 * work and how to avoid certain pitfalls.
 *
 * \section entity_management Entity Management
 *
 * Entities have to be created with Engine::CreateEntity() Factory Method.
 * This will also cause the correct registration in all modules (especially in
 * the Engine::Physics module). And create the registrations for it.
 *
 * Once an Entity is no more used, one has to call Engine::DestroyEntity().
 * 
 * \section entitiy_drawing Drawing of an Entity
 *
 * Aim: The visual state must always represent the visual state of the game
 * state.
 *
 * To do this we always have to update the visual entity from the game state
 * entity.
 *
 * \code
 * 	View::DrawEntity (Entity* entity) {
 * 		// if this entity has no visual part we don't need to draw
 * 		if (! entity->mPhysicState) return;
 *
 *		// update entity->mVisualState based on entity->mGameState
 *
 * 		// perform positioning based on entity->mPhysicState
 *
 *		// perform drawing based on entity->mVisualState
 *	}
 *	\endcode
 *
 * \section game_input Game Input
 *
 * Each Entity has a ControllerState which keeps track on how the Entity is
 * currently steered. This is then processed by the model each frame for each
 * entity and updates the velocities / orientations etc. before the physical
 * simulation is started. The player input simply forwards its input to the
 * Entity with the Player Id and updates the ControllerState of the Entity
 * with the Id.
 *
 * To add a new key state one has to follow these steps:
 * - add a new EntityControllerKeyState e.g. EntityKeyStateCrouch (must be added
 *   above EntityKeyStateLast)
 * - define the behaviour of the control in Entity::ProcessController() which
 *   updates the EntityPhysicalState of the Entity
 * - add a command to be able to bind a key to the EntityControllerKeyState
 *
 * \section console_input Console Input
 *
 * Since it could be that the key being pressed has to be forwarded to another
 * system such as the Menu or the Engine::Console system, we have to query the
 * Engine::Model whether it is active and forward the input if it is the case.
 * Otherwise we just execute the binding for the key (if it exists).
 *
 * \code
 * 	Controller::OnKeyDown (SDLKey key) {
 * 		if (mConsole->GetActive ())
 * 			mConsole->OnKeyDown (key);
 *
 *		if (mBinding[key].size())
 *			mCommands->QueueCommand (mBinding[key]);
 *	}
 * \endcode
 *
 * \section addcommand Adding a Command to the Command System
 *
 * For the various Modules such as Engine::Controller, Engine::View, etc.
 * separate files exist in which commands are defined. The filename pattern is
 * usually [ModuleName]Commands.cc and contains the function
 *	\code void ModuleName::OnRegisterCommands () \endcode which is run during the
 * initialization phase of the Engine in Engine::OnInit.
 *
 * Commands themselves have the signature:
 * \code bool Cmd_CrazyCommand (std::vector<std::string> args) \endcode
 * and return true on success and error if some error has happened. The
 * prefix \e Cmd_ is not mandatory but keeps things clear.
 *
 * Please make sure to call Engine::CommandSetErrorString in such a case. The
 * message itself will be automatically reported to the Engine::Logging system
 * as a warning since Command errors are hopefully not that important that
 * they can crash the whole Engine.
 *
 * To register a Command to the Engine::Commands system you have to call \code
 * AddCommand ("crazycommand", Cmd_CrazyCommand); \endcode in
 * ModuleName::OnRegisterCommands. With this the Command is accessible through
 * the Command system.
 *
 * \section addvariable Adding a Variable to the Engine::Variable System
 *
 * To register a variable to the Engine::Variables Module one \e must use a
 * static variable of type Engine::Variable and use a special constructor:
 * \code
 *		static Var_Variable PlayerSpeed ("playerspeed", "1.25");
 * \endcode
 * This constructor takes care of registering the Variable PlayerSpeedVariable
 * and its value to the Engine::Variables Module. The first argument is the
 * name of the variable which can be used to retrieve a pointer to the
 * Variable with Engine::GetVariable, Engine::GetVariableString, etc. The
 * second argument is the value which the system will automatically try to
 * convert to a float. This float is then returned if Engine::GetVariableFloat
 * is called.
 *
 * The prefix \e Var_ is for readability in the code.
 *
 * The keyword \e static ensures that the lifespan of the variable is not only
 * in a local function environment and thus mandatory. However it is
 * registered at that time the program executes the first time the line in
 * which the definition was made. To be safe define all your variables in the
 * global scope of te source file of your Engine::Module.
 */