Changeset 8727 for code/trunk/src/orxonox/worldentities/pawns

Timestamp:

Jul 3, 2011, 5:42:19 PM (13 years ago)

Author:

dafrick

Message:

Cleaning up in SpaceShip and Engine. Fixed several bugs.
Kicked localLinearAcceleration, primaryThrust and auxiliaryThrust out of the SpaceShip, since it wasn't used anymore.
Moved the trail lights back a bit.
Added some documentation to SpaceShip and Engine.
SpeedPickup is working again, will need some further tuning.

Location:

code/trunk/src/orxonox/worldentities/pawns

Files:

• SpaceShip.cc (modified) (16 diffs)
• SpaceShip.h (modified) (2 diffs)

code/trunk/src/orxonox/worldentities/pawns/SpaceShip.cc

@@ -36 +36 @@
 #include "core/XMLPort.h"
 #include "tools/Shader.h"
-#include "util/Debug.h" // TODO: Needed?
 #include "util/Math.h"
 
@@ -47 +46 @@
 namespace orxonox
 {
-    const float orientationGain = 100;
     CreateFactory(SpaceShip);
 
@@ -54 +52 @@
         RegisterObject(SpaceShip);
 
-        this->primaryThrust_  = 100;
-        this->auxilaryThrust_ =  30;
+        this->bInvertYAxis_ = false;
+
+        this->steering_ = Vector3::ZERO;
+
         this->rotationThrust_ =  10;
-
-        this->localLinearAcceleration_.setValue(0, 0, 0);
         this->localAngularAcceleration_.setValue(0, 0, 0);
+
         this->bBoost_ = false;
-        this->steering_ = Vector3::ZERO;
-
+        this->bBoostCooldown_ = false;
+        this->initialBoostPower_ = 10.0f;
         this->boostPower_ = 10.0f;
-        this->initialBoostPower_ = 10.0f;
-        this->boostRate_ = 5.0;
-        this->boostPowerRate_ = 1.0;
-        this->boostCooldownDuration_ = 5.0;
-        this->bBoostCooldown_ = false;
-
-        this->lift_ = 1.0f;                         // factor of the lift, standard is 1
-        this->stallSpeed_ = 220.0f;                 // max speed where lift is added
-
-        this->bInvertYAxis_ = false;
+        this->boostPowerRate_ = 1.0f;
+        this->boostRate_ = 5.0f;
+        this->boostCooldownDuration_ = 5.0f;
+
+        this->shakeFrequency_ = 15.0f;
+        this->shakeAmplitude_ = 5.0f;
+        this->shakeDt_ = 0.0f;
+        this->cameraOriginalPosition_ = Vector3::UNIT_SCALE;
+        this->cameraOriginalOrientation_ = Quaternion::IDENTITY;
+
+        this->lift_ = 1.0f;
+        this->stallSpeed_ = 220.0f;
 
         this->setDestroyWhenPlayerLeft(true);
@@ -83 +84 @@
         this->enableCollisionCallback();
 
-        this->engineTicksNotDone = 0;
         this->setConfigValues();
         this->registerVariables();
-        
-        this->cameraOriginalPosition_ = Vector3::UNIT_SCALE;
-        this->cameraOriginalOrientation_ = Quaternion::IDENTITY;
-
-        this->shakeFrequency_ = 15;
-        this->shakeAmplitude_ = 5;
-        this->shakeDt_ = 0;
+
     }
 
@@ -100 +94 @@
         {
             this->removeAllEngines();
-        
+
             if (this->boostBlur_)
                 this->boostBlur_->destroy();
@@ -110 +104 @@
         SUPER(SpaceShip, XMLPort, xmlelement, mode);
 
-        //XMLPortParam(SpaceShip, "engine",            setEngineTemplate,    getEngineTemplate,    xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "primaryThrust",  primaryThrust_,  xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "auxilaryThrust", auxilaryThrust_, xmlelement, mode);
         XMLPortParamVariable(SpaceShip, "rotationThrust", rotationThrust_, xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "boostPower", initialBoostPower_, xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "boostPowerRate", boostPowerRate_, xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "boostRate", boostRate_, xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "boostCooldownDuration", boostCooldownDuration_, xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "shakeFrequency", shakeFrequency_, xmlelement, mode);
-        XMLPortParamVariable(SpaceShip, "shakeAmplitude", shakeAmplitude_, xmlelement, mode);
+        XMLPortParam(SpaceShip, "boostPower", setInitialBoostPower, getInitialBoostPower, xmlelement, mode);
+        XMLPortParam(SpaceShip, "boostPowerRate", setBoostPowerRate, getBoostPowerRate, xmlelement, mode);
+        XMLPortParam(SpaceShip, "boostRate", setBoostRate, getBoostRate, xmlelement, mode);
+        XMLPortParam(SpaceShip, "boostCooldownDuration", setBoostCooldownDuration, getBoostCooldownDuration, xmlelement, mode);
+        XMLPortParam(SpaceShip, "shakeFrequency", setShakeFrequency, getShakeFrequency, xmlelement, mode);
+        XMLPortParam(SpaceShip, "shakeAmplitude", setShakeAmplitude, getShakeAmplitude, xmlelement, mode);
         XMLPortParamVariable(SpaceShip, "lift", lift_, xmlelement, mode);
         XMLPortParamVariable(SpaceShip, "stallSpeed", stallSpeed_, xmlelement, mode);
@@ -128 +119 @@
     void SpaceShip::registerVariables()
     {
-        registerVariable(this->primaryThrust_,  VariableDirection::ToClient);
-        registerVariable(this->auxilaryThrust_, VariableDirection::ToClient);
         registerVariable(this->rotationThrust_, VariableDirection::ToClient);
-        // TODO: Synchronization of boost needed?
         registerVariable(this->boostPower_, VariableDirection::ToClient);
         registerVariable(this->boostPowerRate_, VariableDirection::ToClient);
@@ -169 +157 @@
         SUPER(SpaceShip, tick, dt);
 
+        // Run the engines
+        for(std::vector<Engine*>::iterator it = this->engineList_.begin(); it != this->engineList_.end(); it++)
+            (*it)->run(dt);
+
         if (this->hasLocalController())
         {
-            // Handle mouse look
+            // If not in mouse look apply the angular movement to the ship.
             if (!this->isInMouseLook())
             {
@@ -179 +171 @@
             this->localAngularAcceleration_.setValue(0, 0, 0);
 
-            // Charge boostPower
-            if(!this->bBoostCooldown_ && this->boostPower_ < this->initialBoostPower_)
+            // If not in boost cooldown, the boost power is recharged up to the initial boost power.
+            if(!this->isBoostCoolingDown() && this->boostPower_ < this->initialBoostPower_)
             {
                 this->boostPower_ += this->boostPowerRate_*dt;
             }
-            // Use boostPower
-            if(this->bBoost_)
+            // If boosting
+            if(this->isBoosting())
             {
-                this->boostPower_ -=this->boostRate_*dt;
+                // Discount the used power
+                this->boostPower_ -= this->boostRate_*dt;
+                // If the power has been used up boosting is stopped and boost cooldown is initiated.
                 if(this->boostPower_ <= 0.0f)
                 {
@@ -195 +189 @@
                 }
 
+                // Shake the camera because of the boosting.
                 this->shakeCamera(dt);
             }
 
             // Enable Blur depending on settings
-            if (this->bEnableMotionBlur_ && !this->boostBlur_ && this->hasLocalController() && this->hasHumanController())
+            if(this->bEnableMotionBlur_)
             {
-                this->boostBlur_ = new Shader(this->getScene()->getSceneManager());
-                this->boostBlur_->setCompositorName("Radial Blur");
+                if (this->boostBlur_ == NULL && this->hasLocalController() && this->hasHumanController())
+                {
+                    this->boostBlur_ = new Shader(this->getScene()->getSceneManager());
+                    this->boostBlur_->setCompositorName("Radial Blur");
+                }
+                if (this->boostBlur_)
+                {
+                    float blur = this->blurStrength_ * clamp(-this->getLocalVelocity().z/(this->getMaxSpeedFront()*this->getBoostFactor()), 0.0f, 1.0f);
+
+                    // Show and hide blur effect depending on state of booster
+                    if(this->isBoosting())
+                        this->boostBlur_->setVisible(blur > 0.0f);
+                    else
+                        this->boostBlur_->setVisible(false);
+
+                    this->boostBlur_->setParameter(0, 0, "sampleStrength", blur);
+                }
             }
-
-            if (this->boostBlur_) // && this->maxSpeedFront_ != 0 && this->boostFactor_ != 1)
-            {
-                // TODO: this->maxSpeedFront_ gets fastest engine
-                float blur = this->blurStrength_ * clamp((-this->getLocalVelocity().z - 0.0f /*this->maxSpeedFront_*/) / ((150.0f /*boostFactor_*/ - 1) * 1.5f /*this->maxSpeedFront_*/), 0.0f, 1.0f);
-
-                // Show and hide blur effect depending on state of booster
-                if(this->bBoost_)
-                    this->boostBlur_->setVisible(blur > 0);
-                else
-                    this->boostBlur_->setVisible(false);
-
-                this->boostBlur_->setParameter(0, 0, "sampleStrength", blur);
-            }
-        }
-    }
-
-    void SpaceShip::moveFrontBack(const Vector2& value)
-    {
-        this->localLinearAcceleration_.setZ(this->localLinearAcceleration_.z() - value.x);
-        this->steering_.z -= value.x;
-    }
-
-    void SpaceShip::moveRightLeft(const Vector2& value)
-    {
-        this->localLinearAcceleration_.setX(this->localLinearAcceleration_.x() + value.x);
-        this->steering_.x += value.x;
-    }
-
-    void SpaceShip::moveUpDown(const Vector2& value)
-    {
-        this->localLinearAcceleration_.setY(this->localLinearAcceleration_.y() + value.x);
-        this->steering_.y += value.x;
-    }
-
+        }
+
+        this->steering_ = Vector3::ZERO;
+    }
+
+    /**
+    @brief
+        Rotate in yaw direction.
+        Due to added lift, can also lead to an additional right-left motion.
+    @param value
+        A vector whose first component specifies the magnitude of the rotation. Positive means yaw left, negative means yaw right.
+    */
     void SpaceShip::rotateYaw(const Vector2& value)
     {
@@ -245 +232 @@
         Pawn::rotateYaw(value);
 
-        //This function call adds a lift to the ship when it is rotating to make it's movement more "realistic" and enhance the feeling.
-        if (abs(this-> getLocalVelocity().z) < stallSpeed_)  {this->moveRightLeft(-lift_ / 5 * value * sqrt(abs(this-> getLocalVelocity().z)));}
-    }
-
+        // This function call adds a lift to the ship when it is rotating to make it's movement more "realistic" and enhance the feeling.
+        if (this->getLocalVelocity().z < 0 && abs(this->getLocalVelocity().z) < stallSpeed_)
+            this->moveRightLeft(-lift_ / 5.0f * value * sqrt(abs(this->getLocalVelocity().z)));
+    }
+
+    /**
+    @brief
+        Rotate in pitch direction.
+        Due to added left, can also lead to an additional up-down motion.
+    @param value
+        A vector whose first component specifies the magnitude of the rotation. Positive means pitch up, negative means pitch down.
+    */
     void SpaceShip::rotatePitch(const Vector2& value)
     {
-        this->localAngularAcceleration_.setX(this->localAngularAcceleration_.x() + value.x*0.8f);
-
-        Pawn::rotatePitch(value);
-
-        //This function call adds a lift to the ship when it is pitching to make it's movement more "realistic" and enhance the feeling.
-        if (abs(this-> getLocalVelocity().z) < stallSpeed_)  {this->moveUpDown(lift_ / 5 * value * sqrt(abs(this-> getLocalVelocity().z)));}
-    }
-
+        Vector2 pitch = value;
+        if(this->bInvertYAxis_)
+            pitch.x = -pitch.x;
+
+        this->localAngularAcceleration_.setX(this->localAngularAcceleration_.x() + pitch.x*0.8f);
+
+        Pawn::rotatePitch(pitch);
+
+        // This function call adds a lift to the ship when it is pitching to make it's movement more "realistic" and enhance the feeling.
+        if (this->getLocalVelocity().z < 0 && abs(this->getLocalVelocity().z) < stallSpeed_)
+            this->moveUpDown(lift_ / 5.0f * pitch * sqrt(abs(this->getLocalVelocity().z)));
+    }
+
+    /**
+    @brief
+        Rotate in roll direction.
+    @param value
+        A vector whose first component specifies the magnitude of the rotation. Positive means roll left, negative means roll right.
+    */
     void SpaceShip::rotateRoll(const Vector2& value)
     {
@@ -278 +284 @@
     void SpaceShip::boost(bool bBoost)
     {
-        if(bBoost && !this->bBoostCooldown_)
+        // Can only boost if not cooling down.
+        if(bBoost && !this->isBoostCoolingDown())
         {
             this->bBoost_ = true;
-            Camera* camera = CameraManager::getInstance().getActiveCamera();
-            this->cameraOriginalPosition_ = camera->getPosition();
-            this->cameraOriginalOrientation_ = camera->getOrientation();
-        }
+            this->backupCamera();
+        }
+        // Stop boosting.
         if(!bBoost)
         {
@@ -292 +298 @@
     }
 
-    void SpaceShip::boostCooledDown(void)
-    {
-        this->bBoostCooldown_ = false;
-    }
-    
-    void SpaceShip::shakeCamera(float dt)
-    {
-        //make sure the ship is only shaking if it's moving
-        if (this->getVelocity().squaredLength() > 80.0f)
-        {
-            this->shakeDt_ += dt;
-    
-            float frequency = this->shakeFrequency_ * (this->getVelocity().squaredLength());
-    
-            if (this->shakeDt_ >= 1.0f/frequency)
-            {
-                this->shakeDt_ -= 1.0f/frequency;
-            }
-    
-            Degree angle = Degree(sin(this->shakeDt_ *2.0f* math::pi * frequency) * this->shakeAmplitude_);
-    
-            //COUT(0) << "Angle: " << angle << std::endl;
-            Camera* camera = this->getCamera();
-
-            //Shaking Camera effect
-            if (camera != 0)
-            {
-                camera->setOrientation(Vector3::UNIT_X, angle);
-            }
-        }
-    }
-
-    void SpaceShip::resetCamera()
-    {
-        Camera *camera = this->getCamera();
-
-        if (camera == 0)
-        {
-            COUT(2) << "Failed to reset camera!";
-            return;
-        }
-    
-        this->shakeDt_ = 0;
-        camera->setPosition(this->cameraOriginalPosition_);
-        camera->setOrientation(this->cameraOriginalOrientation_);
-    }
-
-    void SpaceShip::backupCamera()
-    {
-        Camera* camera = CameraManager::getInstance().getActiveCamera();
-        if(camera != NULL)
-        {
-            this->cameraOriginalPosition_ = camera->getPosition();
-            this->cameraOriginalOrientation_ = camera->getOrientation();
-        }
-    }
-
+        /**
+    @brief
+        Add an Engine to the SpaceShip.
+    @param engine
+        A pointer to the Engine to be added.
+    */
     void SpaceShip::addEngine(orxonox::Engine* engine)
     {
-        //COUT(0)<<"Adding an Engine: " << engine << endl;
+        OrxAssert(engine != NULL, "The engine cannot be NULL.");
         this->engineList_.push_back(engine);
         engine->addToSpaceShip(this);
-        this->resetEngineTicks();
-    }
-
-    bool SpaceShip::hasEngine(Engine* engine)
-    {
-        for(unsigned int i=0; i<this->engineList_.size(); i++)
-        {
-            if(this->engineList_[i]==engine)
+    }
+
+    /**
+    @brief
+        Check whether the SpaceShip has a particular Engine.
+    @param engine
+        A pointer to the Engine to be checked.
+    */
+    bool SpaceShip::hasEngine(Engine* engine) const
+    {
+        for(unsigned int i = 0; i < this->engineList_.size(); i++)
+        {
+            if(this->engineList_[i] == engine)
                 return true;
         }
@@ -367 +327 @@
     }
 
+    /**
+    @brief
+        Get the i-th Engine of the SpaceShip.
+    @return
+        Returns a pointer to the i-the Engine. NULL if there is no Engine with that index.
+    */
     Engine* SpaceShip::getEngine(unsigned int i)
     {
-        if(this->engineList_.size()>=i)
-            return 0;
+        if(this->engineList_.size() >= i)
+            return NULL;
         else
             return this->engineList_[i];
     }
 
+    /**
+    @brief
+        Remove and destroy all Engines of the SpaceShip.
+    */
     void SpaceShip::removeAllEngines()
     {
@@ -380 +350 @@
             this->engineList_.back()->destroy();
     }
-    
+
+    /**
+    @brief
+        Remove a particular Engine from the SpaceShip.
+    @param engine
+        A pointer to the Engine to be removed.
+    */
     void SpaceShip::removeEngine(Engine* engine)
     {
-        for(std::vector<Engine*>::iterator it=this->engineList_.begin(); it!=this->engineList_.end(); ++it)
-        {
-            if(*it==engine)
+        for(std::vector<Engine*>::iterator it = this->engineList_.begin(); it != this->engineList_.end(); ++it)
+        {
+            if(*it == engine)
             {
                 this->engineList_.erase(it);
@@ -393 +369 @@
     }
 
-    void SpaceShip::setSpeedFactor(float factor)
+    /**
+    @brief
+        Add to the speed factor for all engines of the SpaceShip.
+    @param factor
+        The factor to be added.
+    */
+    void SpaceShip::addSpeedFactor(float factor)
     {
         for(unsigned int i=0; i<this->engineList_.size(); i++)
-            this->engineList_[i]->setSpeedFactor(factor);
-    }
-    float SpaceShip::getSpeedFactor() // Calculate mean SpeedFactor.
-    {
-        float ret = 0; unsigned int i = 0;
+            this->engineList_[i]->addSpeedMultiply(factor);
+    }
+
+    /**
+    @brief
+        Add to the speed factor for all engines of the SpaceShip.
+    @param speed
+        The speed to be added.
+    */
+    void SpaceShip::addSpeed(float speed)
+    {
+        for(unsigned int i=0; i<this->engineList_.size(); i++)
+            this->engineList_[i]->addSpeedAdd(speed);
+    }
+
+    /**
+    @brief
+        Get the mean speed factor over all engines of the SpaceShip.
+    @return
+        Returns the mean speed factor over all engines of the SpaceShip.
+    */
+    float SpaceShip::getSpeedFactor() const
+    {
+        float sum = 0;
+        unsigned int i = 0;
         for(; i<this->engineList_.size(); i++)
-            ret += this->engineList_[i]->getSpeedFactor();
-        ret /= (float)i;
-        return ret;
-    }
-    float SpaceShip::getMaxSpeedFront()
-    {
-        float ret=0;
+            sum += this->engineList_[i]->getSpeedMultiply();
+        return sum/float(i);
+    }
+
+    /**
+    @brief
+        Get the largest maximal forward speed over all engines of the SpaceShip.
+    @return
+        Returns the largest forward speed over all engines of the SpaceShip.
+    */
+    float SpaceShip::getMaxSpeedFront() const
+    {
+        float speed=0;
         for(unsigned int i=0; i<this->engineList_.size(); i++)
         {
-            if(this->engineList_[i]->getMaxSpeedFront() > ret)
-                ret = this->engineList_[i]->getMaxSpeedFront();
-        }
-        return ret;
-    }
-
-    float SpaceShip::getBoostFactor()
-    {
-        float ret = 0; unsigned int i=0;
+            if(this->engineList_[i]->getMaxSpeedFront() > speed)
+                speed = this->engineList_[i]->getMaxSpeedFront();
+        }
+        return speed;
+    }
+
+    /**
+    @brief
+        Get the mean boost factor over all engines of the SpaceShip.
+    @return
+        Returns the mean boost factor over all engines of the SpaceShip.
+    */
+    float SpaceShip::getBoostFactor() const
+    {
+        float sum = 0;
+        unsigned int i=0;
         for(; i<this->engineList_.size(); i++)
-            ret += this->engineList_[i]->getBoostFactor();
-        ret /= (float)i;
-        return ret;
-    }
-
-    std::vector<PickupCarrier*>* SpaceShip::getCarrierChildren(void) const
-    {
-        std::vector<PickupCarrier*>* list = new std::vector<PickupCarrier*>();
-        for(unsigned int i=0; i<this->engineList_.size(); i++)
-            list->push_back(this->engineList_[i]);
-        return list;
-    }
-    
+            sum += this->engineList_[i]->getBoostFactor();
+        return sum/float(i);
+    }
+
+    /**
+    @brief
+        Is called when the enableMotionBlur config value has changed.
+    */
     void SpaceShip::changedEnableMotionBlur()
     {
-        if (!this->bEnableMotionBlur_)
+        if (!this->bEnableMotionBlur_ && this->boostBlur_ != NULL)
         {
             this->boostBlur_->destroy();
-            this->boostBlur_ = 0;
-        }
+            this->boostBlur_ = NULL;
+        }
+    }
+
+    /**
+    @brief
+        Shake the camera for a given time interval.
+    @param dt
+        The time interval in seconds.
+    */
+    void SpaceShip::shakeCamera(float dt)
+    {
+        // Make sure the ship is only shaking if it's moving forward and above the maximal forward speed.
+        if (-this->getLocalVelocity().z > this->getMaxSpeedFront())
+        {
+            this->shakeDt_ += dt;
+
+            float frequency = this->shakeFrequency_ * (square(abs(this->getLocalVelocity().z)));
+
+            if (this->shakeDt_ >= 1.0f/frequency)
+                this->shakeDt_ -= 1.0f/frequency;
+
+            Degree angle = Degree(sin(this->shakeDt_ * math::twoPi * frequency) * this->shakeAmplitude_);
+
+            Camera* camera = this->getCamera();
+            //Shaking Camera effect
+            if (camera != 0)
+                camera->setOrientation(Vector3::UNIT_X, angle);
+
+        }
+        // If the camera is no shaking, reset it.
+        else
+            this->resetCamera();
+    }
+
+    /**
+    @brief
+        Save the original position and orientation of the camera.
+    */
+    void SpaceShip::backupCamera()
+    {
+        Camera* camera = CameraManager::getInstance().getActiveCamera();
+        if(camera != NULL)
+        {
+            this->cameraOriginalPosition_ = camera->getPosition();
+            this->cameraOriginalOrientation_ = camera->getOrientation();
+        }
+    }
+
+    /**
+    @brief
+        Reset the camera to its original position.
+    */
+    void SpaceShip::resetCamera()
+    {
+        Camera *camera = this->getCamera();
+        if (camera == 0)
+        {
+            COUT(2) << "Failed to reset camera!";
+            return;
+        }
+
+        this->shakeDt_ = 0.0f;
+        camera->setPosition(this->cameraOriginalPosition_);
+        camera->setOrientation(this->cameraOriginalOrientation_);
     }
 

code/trunk/src/orxonox/worldentities/pawns/SpaceShip.h

@@ -34 +34 @@
 #include <string>
 #include <LinearMath/btVector3.h>
+
 #include "tools/Timer.h"
 #include "util/Math.h"
+#include "util/OrxAssert.h"
+
 #include "Pawn.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        The SpaceShip is the principal entity through which the player interacts with the game. Its main function is to fly, however many things, such as @ref orxonox::Engine Engines or @ref orxonox::Weapon Weapons, can be attached to it.
+
+        There are several parameters that define the behavior of the SpaceShip>
+        - The <b>rotationThrust</b>, specifies the force with which the SpaceShip rotates.
+        - The <b>boost</b>, there are quite some parameters pertaining to boosting. The boost is a special move of the SpaceShip, where, for a limited amount of time, it can fly considerably faster than usual. The <b>boostPower</b> is the amount of power available for boosting. The <b>boostPowerRate</b> is the rate at which the boost power is replenished. The <b>boostRate</b> is the rate at which boosting uses power. And the <b>boostCooldownDuration</b> is the time the SpaceShip cannot boost, once all the boost power has been used up. Naturally all of these parameters must be non-negative.
+        - The <b>boost shaking</b>, when the SpaceShip boosts, the camera shakes to create a more immersive effect. Two parameters can be used to adjust the effect. The <b>shakeFrequency</b> is the frequency with which the camera shakes. And the <b>shakeAmplitude</b> is the amount with which the camera shakes. Again these parameters must bee non-negative.
+        - The <b>lift</b> creates a more natural flight feeling through the addition of a lift force. There are again tow parameters that can be specified. The <b>lift</b> which is the lift force that is applied. And the <b>stallSpeed</b> which is the forward speed after which no more lift is generated.
+
+        As mentioned @ref orxonox::Engine Engines can be mounted on the SpaceShip. Here is a (primitive) example of a SpaceShip defined in XML:
+        @code
+        <SpaceShip
+            rotationThrust    = 50
+
+            lift = 1;
+            stallSpeed = 220;
+
+            boostPower            = 15
+            boostPowerRate        = 1
+            boostRate             = 5
+            boostCooldownDuration = 10
+
+            shakeFrequency = 15
+            shakeAmplitude = 9
+
+            collisionType     = "dynamic"
+            mass              = 100
+            linearDamping     = 0.7
+            angularDamping    = 0.9999999
+            >
+                <engines>
+                    <Engine />
+                    <Engine />
+                </engines>
+            </SpaceShip>
+        @endcode
+
+    @author
+        Fabian 'x3n' Landau
+    */
     class _OrxonoxExport SpaceShip : public Pawn
     {
@@ -50 +95 @@
             void setConfigValues();
 
-            virtual void moveFrontBack(const Vector2& value);
-            virtual void moveRightLeft(const Vector2& value);
-            virtual void moveUpDown(const Vector2& value);
-
-            virtual void rotateYaw(const Vector2& value);
-            virtual void rotatePitch(const Vector2& value);
-            virtual void rotateRoll(const Vector2& value);
+            /**
+            @brief Move forward or backward,
+            @param value A vector whose first component specifies the amount of movement. Positive means forward, negative means backward.
+            */
+            virtual void moveFrontBack(const Vector2& value)
+                { this->steering_.z -= value.x; }
+            /**
+            @brief Move right or left.
+            @param value A vector whose first component specifies the amount of movement. Positive means right, negative means left.
+            */
+            virtual void moveRightLeft(const Vector2& value)
+                { this->steering_.x += value.x; }
+            /**
+            @brief Move up or down.
+            @param value A vector whose first component specifies the amount of movement. Positive means up, negative means down.
+            */
+            virtual void moveUpDown(const Vector2& value)
+                { this->steering_.y += value.x; }
+
+            virtual void rotateYaw(const Vector2& value); // Rotate in yaw direction.
+            virtual void rotatePitch(const Vector2& value); // Rotate in pitch direction.
+            virtual void rotateRoll(const Vector2& value); // Rotate in roll direction.
 
             virtual void fire();
             virtual void boost(bool bBoost); // Starts or stops boosting.
 
-            void addEngine(Engine* engine);
-            bool hasEngine(Engine* engine);
-            Engine* getEngine(unsigned int i); // This one's for XMLPort
-            inline const std::vector<Engine*>& getEngineList()
+            void addEngine(Engine* engine); // Add an Engine to the SpaceShip.
+            bool hasEngine(Engine* engine) const; // Check whether the SpaceShip has a particular Engine.
+            Engine* getEngine(unsigned int i); // Get the i-th Engine of the SpaceShip.
+            /**
+            @brief Get the list of all Engines that are mounted on the SpaceShip.
+            @return Returns a vector of all Engines of the SpaceShip.
+            */
+            inline const std::vector<Engine*>& getEngineList() const
                 { return this->engineList_; }
-            void removeEngine(Engine* engine);
-            void removeAllEngines();
-
-            void setSpeedFactor(float factor);
-            float getSpeedFactor(); // Gets mean speed factor
-            float getMaxSpeedFront(); // gets largest speed forward
-            float getBoostFactor(); // gets mean boost factor
-
+            void removeEngine(Engine* engine); // Remove and destroy all Engines of the SpaceShip.
+            void removeAllEngines(); // Remove a particular Engine from the SpaceShip.
+
+            void addSpeedFactor(float factor); // Add to the speed factor for all engines of the SpaceShip.
+            void addSpeed(float speed); // Add to the speed of all engines of the SpaceShip.
+            float getSpeedFactor() const; // Get the mean speed factor over all engines of the SpaceShip.
+    
+            float getMaxSpeedFront() const; // Get the largest maximal forward speed over all engines of the SpaceShip.
+            float getBoostFactor() const; // Get the mean boost factor over all engines of the SpaceShip.
+
+            /**
+            @brief Set the steering direction of the SpaceShip.
+                   This is set through the user input.
+            @param direction The direction the SpaceShip should steer in.
+            */
             inline void setSteeringDirection(const Vector3& direction)
                 { this->steering_ = direction; }
+            /**
+            @brief Get the steering direction of the SpaceShip.
+            @return Returns the steering direction of the SpaceShip. The length of the vector is the amount of steering needed.
+            */
             inline const Vector3& getSteeringDirection() const
                 { return this->steering_; }
-            inline void resetEngineTicks()
-                { this->engineTicksNotDone = this->engineList_.size(); }
-            inline void oneEngineTickDone()
-                { this->engineTicksNotDone--; }
-            inline bool hasEngineTicksRemaining()
-                { return (this->engineTicksNotDone>0); }
-
-            inline bool getBoost() const
+
+            /**
+            @brief Check whether the SpaceShip is currently boosting.
+            @return Returns true if the SpaceShip is boosting, false if not.
+            */
+            inline bool isBoosting() const
                 { return this->bBoost_; }
-
+            /**
+            @brief Check whether the SpaceShip boost is cooling down.
+            @return Returns true if the SpaceShip is cooling down from boosting.
+            */
+            inline bool isBoostCoolingDown() const
+                { return bBoostCooldown_; }
+
+            /**
+            @brief Set the initial power available for boosting to the input value.
+                   The current boost power is set to the input value as well.
+            @param power The initial boost power. Must be non-negative.
+            */
+            inline void setInitialBoostPower(float power)
+                { OrxAssert(power >= 0.0f, "The boost power must be non-negative."); this->initialBoostPower_ = power; this->boostPower_ = power; }
+            /**
+            @brief Set the rate, at which boost power is recharged, to the input value.
+            @param rate The boost power rate in units per second. Must be non-negative.
+            */
+            inline void setBoostPowerRate(float rate)
+                { OrxAssert(rate >= 0.0f, "The boost power rate must be non-negative."); this->boostPowerRate_ = rate; }
+            /**
+            @brief Set the rate, at which boost power us used up, to the input value.
+            @param rate The boost rate in units per second. Must be non-negative.
+            */
+            inline void setBoostRate(float rate)
+                { OrxAssert(rate >= 0.0f, "The boost rate must be non-negative."); this->boostRate_ = rate; }
+            /**
+            @brief Set the duration for which boosting, if in cooldown, is not possible.
+                   Cooldown is reached if all boost power is depleted.
+            @param duration The cooldown duration in seconds. Must be non-negative.
+            */
+            inline void setBoostCooldownDuration(float duration)
+                { OrxAssert(duration >= 0.0f, "The boost cooldown duration must be non-negative."); this->boostCooldownDuration_ = duration; }
+            /**
+            @brief Set the frequency with which the camera shakes during boosting.
+            @param frequency The frequency in times per second. Must be non-negative.
+            */
+            inline void setShakeFrequency(float frequency)
+                { OrxAssert(frequency >= 0.0f, "The shake frequency must be non-negative."); this->shakeFrequency_ = frequency; }
+            /**
+            @brief Set the amplitude with which the camera shakes during boosting.
+            @param amplitude The amplitude. Must be non-negative.
+            */
+            inline void setShakeAmplitude(float amplitude)
+                { OrxAssert(amplitude >= 0.0f, "The shake amplitude must be non-negative."); this->shakeAmplitude_ = amplitude; }
+
+            /**
+            @brief Get the initial boost power. Is non-negative.
+            @return Returns the initial boost power.
+            */
+            inline float getInitialBoostPower() const
+                { return this->initialBoostPower_; }
+            /**
+            @brief Get the current boost power. Is non-negative.
+            @return Returns the current boost power.
+            */
             inline float getBoostPower() const
                 { return this->boostPower_; }
-            inline float getInitialBoostPower() const
-                { return this->initialBoostPower_; }
-
-            inline bool isBoostCoolingDown() const
-                { return bBoostCooldown_; }
+            /**
+            @brief Get the boost power rate.
+            @return Returns the boost power rate in units per second. Is non-negative.
+            */
+            inline float getBoostPowerRate() const
+                { return this->boostPowerRate_; }
+            /**
+            @brief Get the boost rate.
+            @return Returns the boost rate in units per second. Is non-negative.
+            */
+            inline float getBoostRate() const
+                { return this->boostRate_; }
+            /**
+            @brief Get the cooldown duration.
+            @return Returns the cooldown duration in seconds. Is non-negative.
+            */
+            inline float getBoostCooldownDuration() const
+                { return this->boostCooldownDuration_; }
+            /**
+            @brief Get the shake frequency.
+            @return Returns the shake frequency in times per seconds. Is non-negative.
+            */
+            inline float getShakeFrequency() const
+                { return this->shakeFrequency_; }
+            /**
+            @brief Get the shake amplitude.
+            @return Returns the shake amplitude. Is non-negative.
+            */
+            inline float getShakeAmplitude() const
+                { return this->shakeAmplitude_; }
 
         protected:
-            virtual std::vector<PickupCarrier*>* getCarrierChildren(void) const;
             bool bInvertYAxis_;
 
-            bool bBoost_;
-            bool bBoostCooldown_;
-            float boostPower_;
-            float initialBoostPower_;
-            float boostRate_;
-            float boostPowerRate_;
-            float boostCooldownDuration_;
-            float lift_;
-            float stallSpeed_;
-            Vector3 steering_;
-            float primaryThrust_;
-            float auxilaryThrust_;
-            float rotationThrust_;
-            btVector3 localLinearAcceleration_;
-            btVector3 localAngularAcceleration_;
-
-            float shakeFrequency_;
-            float shakeAmplitude_;
+            Vector3 steering_; //!< The direction and magnitude of the steering action given through user input.
+
+            float rotationThrust_;               //!< Force with which the SpaceShip rotates.
+            btVector3 localAngularAcceleration_; //!< The acceleration that accounts for angular movement and is used internally.
+
+            bool bBoost_;                 //!< Whether the SpaceShip is currently boosting.
+            bool bBoostCooldown_;         //!< Whether the SpaceShip is currently in boost cooldown, during which boosting is impossible.
+            float initialBoostPower_;     //!< The initial (and maximal) boost power.
+            float boostPower_;            //!< The current boost power.
+            float boostPowerRate_;        //!< The rate at which the boost power is recharged.
+            float boostRate_;             //!< The rate at which boost power is used up.
+            float boostCooldownDuration_; //!< The duration for which boost cooldown is in effect.
+            float shakeFrequency_;        //!< The frequency of the shaking of the camera due to boosting.
+            float shakeAmplitude_;        //!< The amplitude of the shaking of the camera due to boosting.
+
+            float lift_;       //!< The amount of lift that is added.
+            float stallSpeed_; //!< The forward speed where no more lift is added.
 
         private:
             void registerVariables();
             virtual bool isCollisionTypeLegal(WorldEntity::CollisionType type) const;
-            
-            //All things booster
-            void changedEnableMotionBlur();
-            void boostCooledDown(void);
+
+            void changedEnableMotionBlur(); // Is called when the enableMotionBlur config value has changed.
+            /**
+            @brief Callback function. Is called when the boost has cooled down.
+            */
+            void boostCooledDown(void)
+                { this->bBoostCooldown_ = false; }
+
+            void shakeCamera(float dt); // Shake the camera for a given time interval.
+            void backupCamera(); // Save the original position and orientation of the camera.
+            void resetCamera(); // Reset the camera to its original position.
+
+            std::vector<Engine*> engineList_; //!< The list of all Engines mounted on this SpaceShip.
+
+            Timer timer_;                          //!< Timer for the cooldown duration.
+            float shakeDt_;                        //!< Temporary variable for the shaking of the camera.
+            Vector3 cameraOriginalPosition_;       //!< The original position of the camera before shaking it.
+            Quaternion cameraOriginalOrientation_; //!< The original orientation of the camera before shaking it.
+
+            Shader* boostBlur_;      //!< A radial blur shader, applied when boosting according to the amount of boosting.
+            float blurStrength_;     //!< The strength of the applied blur.
+            bool bEnableMotionBlur_; //!< Whether motion blur is enabled or not.
         
-            void resetCamera();
-            void backupCamera();
-            void shakeCamera(float dt);
-
-            Shader* boostBlur_;
-            float blurStrength_;
-            bool bEnableMotionBlur_;
-
-            std::vector<Engine*> engineList_;
-            int engineTicksNotDone; // Used for knowing when to reset temporary variables.
-            Timer timer_;
-            Vector3 cameraOriginalPosition_;
-            Quaternion cameraOriginalOrientation_;
-        
-            float shakeDt_;
     };
 }