Index: code/branches/campaignHS15/src/orxonox/controllers/FlyingController.cc
===================================================================
--- code/branches/campaignHS15/src/orxonox/controllers/FlyingController.cc	(revision 10923)
+++ code/branches/campaignHS15/src/orxonox/controllers/FlyingController.cc	(revision 10946)
@@ -9,5 +9,5 @@
  *   modify it under the terms of the GNU General Public License
  *   as published by the Free Software Foundation; either version 2
- *   of the License, or ( at your option )any later version.
+ *   of the License, or (at your option)any later version.
  *
  *   This program is distributed in the hope that it will be useful,
@@ -27,9 +27,11 @@
  *
  */
+#include <OgreMatrix3.h>                        //for Quaternion manipulations
+
+#include "util/Math.h"                          
+#include "core/XMLPort.h"
 #include "controllers/FlyingController.h"
-#include "core/XMLPort.h"
-#include "worldentities/pawns/SpaceShip.h"
-#include "util/Math.h"
-#include <OgreMatrix3.h>
+
+#include "worldentities/pawns/SpaceShip.h"      //for boosting
 
 namespace orxonox
@@ -60,17 +62,17 @@
         FormationMode::Value value;
         
-        if ( valUpper == "WALL" )
+        if (valUpper == "WALL")
             value = FormationMode::WALL;
-        else if ( valUpper == "FINGER4" )
+        else if (valUpper == "FINGER4")
             value = FormationMode::FINGER4;
-        else if ( valUpper == "DIAMOND" )
+        else if (valUpper == "DIAMOND")
             value = FormationMode::DIAMOND;
         else
-            ThrowException(ParseError, std::string( "Attempting to set an unknown FormationMode: '" )+ val + "'.");
+            ThrowException(ParseError, std::string("Attempting to set an unknown FormationMode: '")+ val + "'.");
         this->setFormationMode(value);
     }
     std::string FlyingController::getFormationModeXML() const
     {
-        switch ( this->formationMode_ )
+        switch (this->formationMode_)
         {
             case FormationMode::WALL:
@@ -88,4 +90,10 @@
         this->bHasTargetPosition_ = false;
     }
+    /**
+    @brief
+      if distance to targetPosition is smaller than this->tolerance_, no moving should be made, otherwise
+      find amount of yaw and pitch that have to be applied, so that ship looks at targetPosition, then
+      ship is moved forward towards targetPosition. Also target orientation is being applied.
+    */
     void FlyingController::moveToPosition(const Vector3& targetPosition, float dt)
     {
@@ -94,21 +102,33 @@
         ControllableEntity* entity = this->getControllableEntity();
 
-        float distance = ( targetPosition - entity->getPosition() ).length();
-
-        if ( distance >= this->tolerance_ )
-        {
+        float distance = (targetPosition - entity->getPosition()).length();
+
+        if (distance >= this->tolerance_)
+        {
+            //function that calculates how much yaw and pitch are to be applied
             Vector2 coord = get2DViewCoordinates
-                ( entity->getPosition() , 
+                (entity->getPosition() , 
                 entity->getOrientation()  * WorldEntity::FRONT, 
                 entity->getOrientation()  * WorldEntity::UP, 
-                targetPosition );
-            float rotateX = -clamp( coord.x * 10, -1.0f, 1.0f );
-            float rotateY = clamp( coord.y * 10, -1.0f, 1.0f );
-            entity->rotateYaw( ROTATEFACTOR * rotateX * dt );
-            entity->rotatePitch( ROTATEFACTOR * rotateY * dt );
-          
+                targetPosition);
+            //limit yaw and pitch by [-1,1]
+            float rotateX = -clamp(coord.x * 10, -1.0f, 1.0f);
+            float rotateY = clamp(coord.y * 10, -1.0f, 1.0f);
+
+            if (!entity)
+                return;
+
+            //apply yaw and pitch
+            entity->rotateYaw(ROTATEFACTOR * rotateX * dt);
+            entity->rotatePitch(ROTATEFACTOR * rotateY * dt);
+            
+            if (!entity)
+                return;
+           
+            //only move either if ship looks at target with a certain tolerance, or if ship is far enough for it to be ok to move in a curve.
             if (distance > this->tolerance_*1.5f || (rotateX > -0.03 && rotateX < 0.03 && rotateY > -0.03 && rotateY < 0.03))
-                entity->moveFrontBack( SPEED * dt );
-                copyTargetOrientation(dt);
+                entity->moveFrontBack(SPEED * dt);
+            //roll
+            copyTargetOrientation(dt);
         }
         else
@@ -117,9 +137,16 @@
         }
     }
-    
+    /**
+    @brief
+      fly towards a preset targetPosition_
+    */
     void FlyingController::moveToTargetPosition(float dt)
     {
         this->moveToPosition (this->targetPosition_, dt);
     }
+    /**
+    @brief
+      roll ship so that it has same roll as orient
+    */
     void FlyingController::copyOrientation(const Quaternion& orient, float dt)
     {
@@ -155,5 +182,8 @@
         }
     }
-
+    /**
+    @brief
+      roll ship so that it has same roll as a preset targetOrientation_
+    */
     void FlyingController::copyTargetOrientation(float dt)
     {
@@ -163,5 +193,8 @@
         }
     }
-    
+    /**
+    @brief
+      set Vector to fly to
+    */
     void FlyingController::setTargetPosition(const Vector3& target)
     {
@@ -169,5 +202,8 @@
         this->bHasTargetPosition_ = true;
     }
-
+    /**
+    @brief
+      set orientation to apply
+    */
     void FlyingController::setTargetOrientation(const Quaternion& orient)
     {
@@ -175,5 +211,8 @@
         this->bHasTargetOrientation_=true;
     }
-
+    /**
+    @brief
+      set orientation to apply
+    */
     void FlyingController::setTargetOrientation(ControllableEntity* target)
     {
@@ -181,4 +220,8 @@
             this->setTargetOrientation(target->getOrientation());
     }
+    /**
+    @brief
+      boost if you can
+    */
     void FlyingController::boostControl()
     {
@@ -187,5 +230,5 @@
         SpaceShip* ship = orxonox_cast<SpaceShip*>(this->getControllableEntity());
         if(ship == NULL) return;
-        if(ship->getBoostPower()*1.5f > ship->getInitialBoostPower() ) //upper limit ->boost
+        if(ship->getBoostPower()*1.5f > ship->getInitialBoostPower()) //upper limit ->boost
         {
             this->getControllableEntity()->boost(true);
@@ -196,6 +239,12 @@
         }
     }
+    /**
+    @brief
+      keep this ship in a formation with its division
+    */
     void FlyingController::keepFormation(const ControllableEntity* leaderEntity, Vector3& targetRelativePosition)
     {
+        if (!this->getControllableEntity())
+            return;
         ControllableEntity* myEntity = this->getControllableEntity();
         Vector3 myPosition = myEntity->getWorldPosition();
@@ -212,11 +261,15 @@
             return;
         }
+        //calculate where in world coordinates this ship should fly
         Vector3 targetAbsolutePosition = 
             (leaderPosition + (orient*WorldEntity::FRONT) * (leaderEntity->getVelocity().length()/5)
              + (orient* (targetRelativePosition)));
-        //let ship finish rotating. also don't call copyOrientation to often as it is a slow function.
+        //let ship finish rotating. also don't call copyOrientation too often as it is a slow function. Don't know how to do it different
         if (static_cast<int>(rnd(1.0f) * 100) % 3 == 0)
             this->setTargetOrientation (orient);
+        //set a position to fly to
         this->setTargetPosition (targetAbsolutePosition);
+
+        //boost if too far
         if ((targetAbsolutePosition - myPosition).length() > this->tolerance_ * 1.5f)
         {
@@ -225,5 +278,7 @@
         else
         {
-           this->getControllableEntity()->boost(false);
+            if (!this->getControllableEntity())
+                return;
+            this->getControllableEntity()->boost(false);
         }
     }
