115 lines
4.8 KiB
C++
115 lines
4.8 KiB
C++
/** \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.
|
|
*/
|