Changeset 8727 for code/trunk/src/orxonox

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

Files:

• gametypes/Dynamicmatch.cc (modified) (4 diffs)
• gametypes/Dynamicmatch.h (modified) (2 diffs)
• items/Engine.cc (modified) (10 diffs)
• items/Engine.h (modified) (3 diffs)
• items/MultiStateEngine.cc (modified) (3 diffs)
• items/MultiStateEngine.h (modified) (1 diff)
• worldentities/MobileEntity.cc (modified) (2 diffs)
• worldentities/MobileEntity.h (modified) (2 diffs)
• worldentities/pawns/SpaceShip.cc (modified) (16 diffs)
• worldentities/pawns/SpaceShip.h (modified) (2 diffs)

code/trunk/src/orxonox/gametypes/Dynamicmatch.cc

@@ -151 +151 @@
                 //Give new pig boost
                 SpaceShip* spaceship = dynamic_cast<SpaceShip*>(victim);
-                grantPigBoost(spaceship);
+                this->grantPigBoost(spaceship);
             }
 
@@ -245 +245 @@
                 //Give new pig boost
                 SpaceShip* spaceship = dynamic_cast<SpaceShip*>(victim);
-                grantPigBoost(spaceship);
+                this->grantPigBoost(spaceship);
             }
             // killer vs piggy
@@ -306 +306 @@
     }
 
-    void Dynamicmatch::grantPigBoost(orxonox::SpaceShip* spaceship)
+    /**
+    @brief
+        Grant the piggy a boost.
+    @param spaceship
+        The SpaceShip to give the boost.
+    */
+    void Dynamicmatch::grantPigBoost(SpaceShip* spaceship)
     {
         // Give pig boost
         if (spaceship)
         {
-            spaceship->setSpeedFactor(5);
+            spaceship->addSpeedFactor(5);
             WeakPtr<SpaceShip>* ptr = new WeakPtr<SpaceShip>(spaceship);
             ExecutorPtr executor = createExecutor(createFunctor(&Dynamicmatch::resetSpeedFactor, this));
@@ -599 +605 @@
         if (*ptr)
         {
-            (*ptr)->setSpeedFactor(1.0f);
+            (*ptr)->addSpeedFactor(1.0f/5.0f);
         }
         delete ptr;

code/trunk/src/orxonox/gametypes/Dynamicmatch.h

@@ -30 +30 @@
 #define _Dynamicmatch_H__
 
+#include "OrxonoxPrereqs.h"
+
 #include <map>
 #include <vector>
-#include "OrxonoxPrereqs.h"
+
+#include "tools/Timer.h"
+
 #include "Gametype.h"
-#include "tools/Timer.h"
 
 namespace orxonox
@@ -73 +76 @@
             virtual void furtherInstructions();*/
             virtual void rewardPig();
-            void grantPigBoost(SpaceShip* spaceship); // Added this, since it's used twice on different occasions.
+            void grantPigBoost(SpaceShip* spaceship); // Grant the piggy a boost.
             void resetSpeedFactor(WeakPtr<SpaceShip>* ptr);
             void tick (float dt);// used to end the game

code/trunk/src/orxonox/items/Engine.cc

@@ -29 +29 @@
 #include "Engine.h"
 
-#include "util/Math.h"
 #include "core/CoreIncludes.h"
 #include "core/ConfigValueIncludes.h"
+#include "core/Template.h"
 #include "core/XMLPort.h"
+#include "util/Math.h"
+
 #include "Scene.h"
 #include "worldentities/pawns/SpaceShip.h"
-#include "core/Template.h"
 
 namespace orxonox
@@ -41 +42 @@
     CreateFactory(Engine);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     Engine::Engine(BaseObject* creator) : Item(creator)
     {
@@ -47 +52 @@
         this->ship_ = 0;
         this->shipID_ = OBJECTID_UNKNOWN;
-        this->relativePosition_ = Vector3(0,0,0);
-
-        this->boostFactor_ = 1.5;
-        this->speedFactor_ = 1.0;
-
-        this->maxSpeedFront_ = 0.0;
-        this->maxSpeedBack_ = 0.0;
-        this->maxSpeedLeftRight_ = 0.0;
-        this->maxSpeedUpDown_ = 0.0;
-
-        this->accelerationFront_ = 0.0;
-        this->accelerationBrake_ = 0.0;
-        this->accelerationBack_ = 0.0;
-        this->accelerationLeftRight_ = 0.0;
-        this->accelerationUpDown_ = 0.0;
-
-        this->speedAdd_ = 0.0;
-        this->speedMultiply_ = 1.0;
+        this->relativePosition_ = Vector3::ZERO;
+
+        this->boostFactor_ = 1.5f;
+
+        this->maxSpeedFront_ = 0.0f;
+        this->maxSpeedBack_ = 0.0f;
+        this->maxSpeedLeftRight_ = 0.0f;
+        this->maxSpeedUpDown_ = 0.0f;
+
+        this->accelerationFront_ = 0.0f;
+        this->accelerationBrake_ = 0.0f;
+        this->accelerationBack_ = 0.0f;
+        this->accelerationLeftRight_ = 0.0f;
+        this->accelerationUpDown_ = 0.0f;
+
+        this->speedAdd_ = 0.0f;
+        this->speedMultiply_ = 1.0f;
 
         this->setConfigValues();
@@ -70 +74 @@
     }
 
+    /**
+    @brief
+        Destructor. Destroys the object and removes it from the SpaceShip.
+    */
     Engine::~Engine()
     {
         if (this->isInitialized())
         {
+            // Remove the engine from the ShapeShip.
             if (this->ship_ && this->ship_->hasEngine(this))
                 this->ship_->removeEngine(this);
@@ -108 +117 @@
         registerVariable(this->shipID_, VariableDirection::ToClient, new NetworkCallback<Engine>(this, &Engine::networkcallback_shipID));
 
-        registerVariable(this->speedFactor_, VariableDirection::ToClient);
         registerVariable(this->boostFactor_, VariableDirection::ToClient);
 
@@ -138 +146 @@
     }
 
-    void Engine::tick(float dt)
-    {
-        if (!this->ship_)
-        {
-            if (this->shipID_)
+    /**
+    @brief
+        Run the engine for a given time interval.
+        Is called each tick by SpaceShip.
+    @param dt
+        The time since last tick.
+    */
+    void Engine::run(float dt)
+    {
+        if (this->ship_ == NULL)
+        {
+            if (this->shipID_ != 0)
             {
                 this->networkcallback_shipID();
 
-                if (!this->ship_)
+                if (this->ship_ == NULL)
                     return;
             }
@@ -156 +171 @@
             return;
 
-        SUPER(Engine, tick, dt);
-
-        Vector3 direction = this->getDirection();
-        float directionLength = direction.length();
-        if (directionLength > 1.0f)
-            direction /= directionLength; // normalize
-        
+        // Get the desired steering direction and amount, clipped to length 1 at maximum.
+        Vector3 steering = (this->getSteering().length() > 1.0f ? this->getSteering().normalisedCopy() : this->getSteering());
+
+        // Get the ships velocity.
         Vector3 velocity = this->ship_->getLocalVelocity();
         Vector3 acceleration = Vector3::ZERO;
 
-        float factor = 1.0f / this->speedFactor_;
-        velocity *= factor;
-
-        if (direction.z < 0)
+        // If there is forward steering action.
+        if (steering.z < 0)
         {
             if (this->maxSpeedFront_ != 0)
             {
-                float boostfactor = (this->ship_->getBoost() ? this->boostFactor_ : 1.0f);
-                acceleration.z = direction.z * this->accelerationFront_ * boostfactor * clamp((this->maxSpeedFront_ - -velocity.z/boostfactor) / this->maxSpeedFront_, 0.0f, 1.0f);
+                float boostfactor = (this->ship_->isBoosting() ? this->boostFactor_ : 1.0f); // Boost factor is 1.0 if not boosting.
+                // Boosting can lead to velocities larger the maximal forward velocity.
+                acceleration.z = steering.z * this->accelerationFront_ * boostfactor * clamp((this->maxSpeedFront_ - -velocity.z/boostfactor) / this->maxSpeedFront_, 0.0f, 1.0f);
             }
         }
-        else if (direction.z > 0)
-        {
+        // If there is backward steering action.
+        else if (steering.z > 0)
+        {
+            // Either breaking
             if (velocity.z < 0)
-                acceleration.z = direction.z * this->accelerationBrake_;
+                acceleration.z = steering.z * this->accelerationBrake_;
+            // or backward flight.
             else if (this->maxSpeedBack_ != 0)
-                acceleration.z = direction.z * this->accelerationBack_ * clamp((this->maxSpeedBack_ - velocity.z) / this->maxSpeedBack_, 0.0f, 1.0f);
-        }
-
+                acceleration.z = steering.z * this->accelerationBack_ * clamp((this->maxSpeedBack_ - velocity.z) / this->maxSpeedBack_, 0.0f, 1.0f);
+        }
+        // If there is left-right steering action.
         if (this->maxSpeedLeftRight_ != 0)
         {
-            if (direction.x < 0)
-                acceleration.x = direction.x * this->accelerationLeftRight_ * clamp((this->maxSpeedLeftRight_ - -velocity.x) / this->maxSpeedLeftRight_, 0.0f, 1.0f);
-            else if (direction.x > 0)
-                acceleration.x = direction.x * this->accelerationLeftRight_ * clamp((this->maxSpeedLeftRight_ - velocity.x) / this->maxSpeedLeftRight_, 0.0f, 1.0f);
-        }
-
+            if (steering.x < 0)
+                acceleration.x = steering.x * this->accelerationLeftRight_ * clamp((this->maxSpeedLeftRight_ - -velocity.x) / this->maxSpeedLeftRight_, 0.0f, 1.0f);
+            else if (steering.x > 0)
+                acceleration.x = steering.x * this->accelerationLeftRight_ * clamp((this->maxSpeedLeftRight_ - velocity.x) / this->maxSpeedLeftRight_, 0.0f, 1.0f);
+        }
+        // If there is up-down steering action.
         if (this->maxSpeedUpDown_ != 0)
         {
-            if (direction.y < 0)
-                acceleration.y = direction.y * this->accelerationUpDown_ * clamp((this->maxSpeedUpDown_ - -velocity.y) / this->maxSpeedUpDown_, 0.0f, 1.0f);
-            else if (direction.y > 0)
-                acceleration.y = direction.y * this->accelerationUpDown_ * clamp((this->maxSpeedUpDown_ - velocity.y) / this->maxSpeedUpDown_, 0.0f, 1.0f);
+            if (steering.y < 0)
+                acceleration.y = steering.y * this->accelerationUpDown_ * clamp((this->maxSpeedUpDown_ - -velocity.y) / this->maxSpeedUpDown_, 0.0f, 1.0f);
+            else if (steering.y > 0)
+                acceleration.y = steering.y * this->accelerationUpDown_ * clamp((this->maxSpeedUpDown_ - velocity.y) / this->maxSpeedUpDown_, 0.0f, 1.0f);
         }
 
         // NOTE: Bullet always uses global coordinates.
         this->ship_->addAcceleration(this->ship_->getOrientation() * (acceleration*this->getSpeedMultiply()+Vector3(0,0,-this->getSpeedAdd())), this->ship_->getOrientation() * this->relativePosition_);
-
-        // Hack to reset a temporary variable "direction"
-        this->ship_->oneEngineTickDone();
-        if(!this->ship_->hasEngineTicksRemaining())
-        {
-            this->ship_->setSteeringDirection(Vector3::ZERO);
-            this->ship_->resetEngineTicks();
-        }
-    }
-
-    void Engine::changedActivity()
-    {
-        SUPER(Engine, changedActivity);
-    }
-
+    }
+
+    /**
+    @brief
+        Adds the Engine to the input SpaceShip.
+    @param ship
+        A pointer to the SpaceShip to which the engine is added.
+    */
     void Engine::addToSpaceShip(SpaceShip* ship)
     {
@@ -230 +237 @@
     }
 
-    const Vector3& Engine::getDirection() const
+    /**
+    @brief
+        Get the direction and magnitude of the steering imposed upon the Engine.
+    @return
+        Returns the direction and magnitude of the steering imposed upon the Engine.
+        Is the zero vector if the Engine doesn't belong to a ship.
+    */
+    const Vector3& Engine::getSteering() const
     {
         if (this->ship_)
@@ -238 +252 @@
     }
 
-    PickupCarrier* Engine::getCarrierParent(void) const
-    {
-        return this->ship_;
-    }
-
-    const Vector3& Engine::getCarrierPosition(void) const
-    {
-        return this->ship_->getWorldPosition();
-    }
-
+    /**
+    @brief
+        Load the engine template.
+        Causes all parameters specified by the template to be applied to the Engine.
+    */
     void Engine::loadEngineTemplate()
     {
@@ -260 +269 @@
         }
     }
+
 }

code/trunk/src/orxonox/items/Engine.h

@@ -32 +32 @@
 #include "OrxonoxPrereqs.h"
 
-#include "tools/interfaces/Tickable.h"
+#include "util/OrxAssert.h"
+
 #include "Item.h"
-
-#include "interfaces/PickupCarrier.h"
 
 namespace orxonox
 {
-    class _OrxonoxExport Engine : public Item, public Tickable, public PickupCarrier
+
+    /**
+    @brief
+        The Engine class provides propulsion to the SpaceShip.
+        
+        There are many parameters that can be specified:
+        - The <b>relativePosition</b>, specifies the position relative to the center of the SpaceShip the Engine is mounted on.
+        - The <b>maximal speed</b>, there are four maximal speeds that can be specified: The <b>speedfront</b>, the maximal forward speed. The <b>speedback>, the maximal backward speed. The <b>speedleftright</b>, the maximal speed in y-direction of the SpaceShip coordinate frame. The <b>speedupdown</b>, the maximal speed in z-direction of the SpaceShip coordinate frame. All maximal speeds (naturally) have to be non-negative.
+        - The <b>acceleration</b>, there are five types of acceleration that can be specified: The <b>accelerationfront</b>, the forward acceleration. The <b>accelerationbrake</b>, the braking acceleration. The <b>accelerationback</b>, the backward acceleration. The <b>accelerationleftright</b>, the acceleration in y-direction. The <b>accelerationupdown</b>, the acceleration in z-direction. All accelerations have to be non-negative.
+        - The <b>boostfactor</b>, specifies the factor by which boosting increases the speed. This has to be non-negative, as well. Beware that maximal speeds can be overcome through boosting.
+        - The <b>template</b>, the name of the engine template. Allows for parameters of the Engine be set trough a template.
+        
+    @author
+        Fabian 'x3n' Landau
+    */
+    class _OrxonoxExport Engine : public Item
     {
         public:
@@ -48 +62 @@
             void setConfigValues();
 
-            virtual void tick(float dt);
-            virtual void changedActivity();
-
-            virtual void addToSpaceShip(SpaceShip* ship);
+            virtual void run(float dt); // Run the engine for a given time interval.
+
+            virtual void addToSpaceShip(SpaceShip* ship); // Adds the Engine to the input SpaceShip.
+            /**
+            @brief Get the SpaceShip this Engine is mounted on.
+            @return Returns a pointer to the SpaceShip. NULL if it isn't mounted on any ship.
+            */
             inline SpaceShip* getShip() const
                 { return this->ship_; }
 
+            /**
+            @brief Set the relative position of the Engine.
+            @param position The relative position with respect to the SpaceShip it is mounted on.
+            */
             inline void setRelativePosition(const Vector3 &position)
                 { this->relativePosition_ = position; }
-            inline Vector3& getRelativePosition()
+            /**
+            @brief Get the relative position of the Engine.
+            @return Returns the relative position with respect to the SpaceShip it is mounted on.
+            */
+            inline const Vector3& getRelativePosition() const
                 { return this->relativePosition_; }
 
+            /**
+            @brief Set the maximal forward speed of the Engine.
+            @param speed The speed to be set. Must be non-negative.
+            */
+            //TODO: Better OrxVerify()?
+            inline void setMaxSpeedFront(float speed)
+                { OrxAssert(speed >= 0.0f, "The input speed must be non-negative."); this->maxSpeedFront_ = speed; }
+            /**
+            @brief Set the maximal backward speed of the Engine.
+            @param speed The speed to be set. Must be non-negative.
+            */
+            inline void setMaxSpeedBack(float speed)
+                { OrxAssert(speed >= 0.0f, "The input speed must be non-negative."); this->maxSpeedBack_ = speed; }
+            /**
+            @brief Set the maximal left-right speed of the Engine.
+            @param speed The speed to be set. Must be non-negative.
+            */
+            inline void setMaxSpeedLeftRight(float speed)
+                { OrxAssert(speed >= 0.0f, "The input speed must be non-negative."); this->maxSpeedLeftRight_ = speed; }
+            /**
+            @brief Set the maximal up-down speed of the Engine.
+            @param speed The speed to be set. Must be non-negative.
+            */
+            inline void setMaxSpeedUpDown(float speed)
+                { OrxAssert(speed >= 0.0f, "The input speed must be non-negative."); this->maxSpeedUpDown_ = speed; }
+
+            /**
+            @brief Get the maximal forward speed of the Engine.
+            @return Returns the maximal forward speed of the Engine. Is non-negative.
+            */
+            inline float getMaxSpeedFront() const
+                { return this->maxSpeedFront_; }
+            /**
+            @brief Get the maximal backward speed of the Engine.
+            @return Returns the maximal backward speed of the Engine. Is non-negative.
+            */
+            inline float getMaxSpeedBack() const
+                { return this->maxSpeedBack_; }
+            /**
+            @brief Get the maximal left-right speed of the Engine.
+            @return Returns the maximal left-right speed of the Engine. Is non-negative.
+            */
+            inline float getMaxSpeedLeftRight() const
+                { return this->maxSpeedLeftRight_; }
+            /**
+            @brief Get the maximal up-down speed of the Engine.
+            @return Returns the maximal up-down speed of the Engine. Is non-negative.
+            */
+            inline float getMaxSpeedUpDown() const
+                { return this->maxSpeedUpDown_; }
+
+            /**
+            @brief Set the forward acceleration produced by the Engine.
+            @param acceleration The forward acceleration produced by the Engine. Must be non-negative.
+            */
+            inline void setAccelerationFront(float acceleration)
+                { OrxAssert(acceleration >= 0.0f, "The input acceleration must be non-negative."); this->accelerationFront_ = acceleration; }
+            /**
+            @brief Set the breaking acceleration produced by the Engine.
+            @param acceleration The breaking acceleration produced by the engine. Must be non-negative.
+            */
+            inline void setAccelerationBrake(float acceleration)
+                { OrxAssert(acceleration >= 0.0f, "The input acceleration must be non-negative."); this->accelerationBrake_ = acceleration; }
+            /**
+            @brief Set the backward acceleration produced by the Engine.
+            @param acceleration The backward acceleration produced by the Engine.
+            */
+            inline void setAccelerationBack(float acceleration)
+                { OrxAssert(acceleration >= 0.0f, "The input acceleration must be non-negative."); this->accelerationBack_ = acceleration; }
+            /**
+            @brief Set the left-right acceleration produced by the Engine.
+            @param acceleration The left-right acceleration produced by the Engine.
+            */
+            inline void setAccelerationLeftRight(float acceleration)
+                { OrxAssert(acceleration >= 0.0f, "The input acceleration must be non-negative."); this->accelerationLeftRight_ = acceleration; }
+            /**
+            @brief Set the up-down acceleration produced by the Engine.
+            @param acceleration The
+            */
+            inline void setAccelerationUpDown(float acceleration)
+                { OrxAssert(acceleration >= 0.0f, "The input acceleration must be non-negative."); this->accelerationUpDown_ = acceleration; }
+
+            /**
+            @brief Get the forward acceleration produced by the Engine.
+            @return Returns the forward acceleration produced by the Engine. Is non-negative.
+            */
+            inline float getAccelerationFront() const
+                { return this->accelerationFront_; }
+            /**
+            @brief Get the breaking acceleration produced by the Engine.
+            @return Returns the breaking acceleration produced by the Engine. Is non-negative.
+            */
+            inline float getAccelerationBrake() const
+                { return this->accelerationBrake_; }
+            /**
+            @brief Get the backward acceleration produced by the Engine.
+            @return Returns the backward acceleration produced by the Engine. Is non-negative.
+            */
+            inline float getAccelerationBack() const
+                { return this->accelerationBack_; }
+            /**
+            @brief Get the left-right acceleration produced by the Engine.
+            @return Returns the left-right acceleration produced by the Engine. Is non-negative.
+            */
+            inline float getAccelerationLeftRight() const
+                { return this->accelerationLeftRight_; }
+            /**
+            @brief Get the up-down acceleration produced by the Engine.
+            @return Returns the up-down acceleration produced by the Engine. Is non-negative.
+            */
+            inline float getAccelerationUpDown() const
+                { return this->accelerationUpDown_; }
+
+            /**
+            @brief Set the factor by which boosting increases the forward acceleration of the Engine.
+            @param factor The boost factor. Needs to be positive.
+            */
             inline void setBoostFactor(float factor)
-                { this->boostFactor_ = factor; }
+                { OrxAssert(factor > 0.0f, "The input factor must be positive."); this->boostFactor_ = factor; }
+            /**
+            @brief Get the boost factor of the Engine.
+            @return Returns the factor by which boosting increases the forward acceleration of the Engine. Is positive.
+            */
             inline float getBoostFactor() const
                 { return this->boostFactor_; }
 
-            inline void setSpeedFactor(float factor)
-                { this->speedFactor_ = factor; }
-            inline float getSpeedFactor() const
-                { return this->speedFactor_; }
-
-            inline void setMaxSpeedFront(float speed)
-                { this->maxSpeedFront_ = speed; }
-            inline void setMaxSpeedBack(float speed)
-                { this->maxSpeedBack_ = speed; }
-            inline void setMaxSpeedLeftRight(float speed)
-                { this->maxSpeedLeftRight_ = speed; }
-            inline void setMaxSpeedUpDown(float speed)
-                { this->maxSpeedUpDown_ = speed; }
-
-            inline float getMaxSpeedFront() const
-                { return this->maxSpeedFront_; }
-            inline float getMaxSpeedBack() const
-                { return this->maxSpeedBack_; }
-            inline float getMaxSpeedLeftRight() const
-                { return this->maxSpeedLeftRight_; }
-            inline float getMaxSpeedUpDown() const
-                { return this->maxSpeedUpDown_; }
-
-            inline void setAccelerationFront(float acceleration)
-                { this->accelerationFront_ = acceleration; }
-            inline void setAccelerationBrake(float acceleration)
-                { this->accelerationBrake_ = acceleration; }
-            inline void setAccelerationBack(float acceleration)
-                { this->accelerationBack_ = acceleration; }
-            inline void setAccelerationLeftRight(float acceleration)
-                { this->accelerationLeftRight_ = acceleration; }
-            inline void setAccelerationUpDown(float acceleration)
-                { this->accelerationUpDown_ = acceleration; }
-
-            inline float getAccelerationFront() const
-                { return this->accelerationFront_; }
-            inline float getAccelerationBrake() const
-                { return this->accelerationBrake_; }
-            inline float getAccelerationBack() const
-                { return this->accelerationBack_; }
-            inline float getAccelerationLeftRight() const
-                { return this->accelerationLeftRight_; }
-            inline float getAccelerationUpDown() const
-                { return this->accelerationUpDown_; }
-
+            /**
+            @brief Add to the additional forward speed factor.
+            @param factor The speed that is added to the additional forward speed. Must be non-negative.
+            */
+            inline void addSpeedAdd(float speed)
+                { this->speedAdd_ += speed; }
+            /**
+            @brief Add to the forward speed multiplication factor.
+            @param factor The factor by which the forward speed multiplication factor is multiplied. Must be non-negative.
+            */
+            inline void addSpeedMultiply(float factor)
+                { OrxAssert(factor >= 0.0f, "The factor must be non-negative."); this->speedMultiply_ *= factor; }
+
+            /**
+            @brief Get the additional forward speed.
+            @return Returns the additional forward speed.
+            */
             inline float getSpeedAdd(void)
                 { return this->speedAdd_; }
+            /**
+            @brief Get the forward speed multiplication factor.
+            @return Returns the forward speed multiplication factor.
+            */
             inline float getSpeedMultiply(void)
                 { return this->speedMultiply_; }
 
-            virtual const Vector3& getDirection() const;
-
-            virtual const Vector3& getCarrierPosition(void) const;
-
-            inline void setSpeedAdd(float speedAdd)
-                { this->speedAdd_=speedAdd; }
-            inline void setSpeedMultiply(float speedMultiply)
-                { this->speedMultiply_=speedMultiply; }
-
-            
+            /**
+            @brief Set the engine template, that specifies the parameters for the Engine.
+            @param temp The name of the engine template.
+            */
             inline void setEngineTemplate(const std::string& temp)
                 { this->engineTemplate_ = temp; this->loadEngineTemplate(); }
+            /**
+            @brief Get the engine template, that specifies the parameters for the Engine.
+            @return Returns the name of the engine template.
+            */
             inline const std::string& getEngineTemplate() const
                 { return this->engineTemplate_; }
 
         protected:
-            virtual std::vector<PickupCarrier*>* getCarrierChildren(void) const
-                { return new std::vector<PickupCarrier*>(); }
-            virtual PickupCarrier* getCarrierParent(void) const;
-            
-            void loadEngineTemplate();
+            void loadEngineTemplate(); // Load the engine template.
+
+            virtual const Vector3& getSteering() const; // Get the steering direction imposed upon the Engine.
 
         private:
@@ -141 +259 @@
             void networkcallback_shipID();
 
-            std::string engineTemplate_;
-
-            SpaceShip* ship_;
-            unsigned int shipID_;
-            Vector3 relativePosition_;
-
-            float boostFactor_;
-            float speedFactor_;
-
-            float speedAdd_;
-            float speedMultiply_;
-
-            float maxSpeedFront_;
-            float maxSpeedBack_;
-            float maxSpeedLeftRight_;
-            float maxSpeedUpDown_;
-
-            float accelerationFront_;
-            float accelerationBrake_;
-            float accelerationBack_;
-            float accelerationLeftRight_;
-            float accelerationUpDown_;
+            std::string engineTemplate_; //!< The template that specifies the Engine's parameters.
+
+            SpaceShip* ship_; //!< A pointer to the SpaceShip the Engine is mounted on.
+            unsigned int shipID_; //!< Object ID of the SpaceShip the Engine is mounted on.
+            Vector3 relativePosition_; //!< The relative position of the Engine with respect to the SpaceShip it is mounted on.
+
+            float boostFactor_; //!< The factor by which boosting increases the forward acceleration.
+
+            float speedAdd_; //!< Additional forward speed. Is not bounded by the maximal forward speed.
+            float speedMultiply_; //!< Forward speed multiplication factor. Is not bounded by the maximal forward speed.
+
+            float maxSpeedFront_; //!< The maximal forward speed.
+            float maxSpeedBack_; //!< The maximal backward speed.
+            float maxSpeedLeftRight_; //!< The maximal left-right speed.
+            float maxSpeedUpDown_; //!< The maximal up-down speed.
+
+            float accelerationFront_; //!< Forward acceleration produced by the Engine.
+            float accelerationBrake_; //!< Breaking acceleration produced by the Engine.
+            float accelerationBack_; //!< Backward acceleration produced by the Engine.
+            float accelerationLeftRight_; //!< Left-right acceleration produced by the Engine.
+            float accelerationUpDown_; //!< Up-down acceleration produced by the Engine.
+
     };
 }

code/trunk/src/orxonox/items/MultiStateEngine.cc

@@ -109 +109 @@
     }
 
-    void MultiStateEngine::tick(float dt)
+    void MultiStateEngine::run(float dt)
     {
         if (this->getShip())
@@ -117 +117 @@
             if (this->getShip()->hasLocalController())
             {
-                const Vector3& direction = this->getDirection();
+                const Vector3& direction = this->getSteering();
                 bool forward = (direction.z < 0.0 && velocity.z < -FORWARD_EFFECT_VELOCITY_THRESHOLD);
 
                 this->state_ = 0;
-                if (this->getShip()->getBoost() && forward)
+                if (this->getShip()->isBoosting() && forward)
                     this->state_ = Boost;
                 else if (forward && !this->state_) // this->state_ == Boost
@@ -181 +181 @@
         }
 
-        SUPER(MultiStateEngine, tick, dt);
+        Engine::run(dt);
     }
 

code/trunk/src/orxonox/items/MultiStateEngine.h

@@ -54 +54 @@
             virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
 
-            virtual void tick(float dt);
+            virtual void run(float dt);
 
             virtual void addToSpaceShip(SpaceShip* ship);

code/trunk/src/orxonox/worldentities/MobileEntity.cc

@@ -34 +34 @@
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
+
 #include "Scene.h"
 
@@ -147 +148 @@
         }
 
-        // If not bullet-managed (deprecated? SpaceShip doesn't use this anymore for movement)
+        // If not bullet-managed (deprecated? SpaceShip doesn't use this anymore for movement) TODO: Find out!
         this->linearAcceleration_ = acceleration;
     }
 
+    /**
+    @brief
+        Adds the input acceleration at the input position to the MobileEntity.
+    @param acceleration
+        The acceleration to be additionally applied to the MobileEntity.
+    @param relativePosition
+        The position relative to the MobileEntity at which the acceleration is applied.
+    */
     void MobileEntity::addAcceleration(const Vector3 &acceleration, const Vector3 &relativePosition)
     {

code/trunk/src/orxonox/worldentities/MobileEntity.h

@@ -55 +55 @@
             inline const Vector3& getVelocity() const
                 { return this->linearVelocity_; }
+            /**
+            @brief Get the velocity in the coordinate-system of the MoblieEntity.
+            @return Returns the velocity of the MobileEntity in its coordinate-system.
+            */
             inline Vector3 getLocalVelocity() const
                 { return (this->getOrientation().Inverse() * this->getVelocity()); }
@@ -69 +73 @@
             inline const Vector3& getAcceleration() const
                 { return this->linearAcceleration_; }
-
-            // Added for making N engines work with spaceships
-            void addAcceleration(const Vector3& acceleration, const Vector3 &relativePosition);
-            inline void addAcceleration(float x, float y, float z)
-                { this->addAcceleration(Vector3(x, y, z), Vector3(0,0,0)); }
-            // Getter function above
+            void addAcceleration(const Vector3& acceleration, const Vector3 &relativePosition = Vector3::ZERO); // Adds the input acceleration at the input position to the MobileEntity.
 
             void setAngularAcceleration(const Vector3& acceleration);

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_;
     };
 }