Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/is_callable.h
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/is_callable.h	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/is_callable.h	(revision 11673)
@@ -4,5 +4,7 @@
 #include <type_traits>
 
-// See https://stackoverflow.com/a/15396757/7421666
+/**
+ * @brief Implementation of IsCallable
+ */
 template<typename T>
 struct IsCallableImpl
@@ -27,6 +29,12 @@
 };
 
-// Checks if a type is callable (has an 'operator()'). This will not work for
-// normal functions without modifications, but we don't need that case anyway.
+/**
+ * @brief Checks if a type is callable
+ *
+ * Callable means here, that it has has an 'operator()'. This will not work for
+ * normal functions without modifications, but we don't need that case anyway.
+ *
+ * See https://stackoverflow.com/a/15396757/7421666
+ */
 template<typename T>
 struct IsCallable
Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/luatb.h
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/luatb.h	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/luatb.h	(revision 11673)
@@ -6,14 +6,27 @@
 struct lua_State;
 
-// Makes certain functions visible to lua while staying type-safe on the
-// C++ side.
+/**
+ * @brief Makes certain functions visible to lua while staying type-safe
+ * on the C++ side.
+ */
 template<typename ThisType, typename FunctionType>
 class LuaTB
 {
 public:
-    // Make a function visible to lua. If you want to make a function 'foo'
-    // visible, you should call it like this:
-    //
-    // LuaTB<decltype(foo)>::registerFunction<foo>( ... );
+    /**
+     * @brief Make a function visible to lua
+     * @param _this Pointer to the object that owns the function
+     * @param lua Pointer to the lua state
+     * @param name Name that will be visible to lua for this function
+     *
+     * Only class functions are supported, because that's  all we need at
+     * the moment. Extending it to support normal functions as well should
+     * be fairly easy, though.
+     *
+     * If you want to make a function 'Foo::bar' visible, you should call
+     * it like this (assuming no C++17 support):
+     *
+     * LuaTB<Foo, decltype(&Foo::bar)>::registerFunction<&Foo::bar>( ... );
+     */
     template<FunctionType func>
     static void registerFunction(ThisType *_this, lua_State *lua, std::string name);
@@ -21,5 +34,5 @@
 
 // We need to include all type-dependant template implementations, because the
-// compiler needs to know for which types it has to instantiate those
+// compiler needs to know for which types it has to instantiate those.
 #include "luatb.ipp"
 
Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/luatb_typed_stack.h
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/luatb_typed_stack.h	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/luatb_typed_stack.h	(revision 11673)
@@ -8,13 +8,23 @@
 #include "core/CoreIncludes.h"
 
-// We need a separate class for this because we need to specialize the functions
-// and that's not possible if we didn't specialize the class. And the logical
-// separation makes sense as well.
+
+/**
+ * @brief Represents a typed version of the lua stack
+ *
+ * We need a separate class for this because we need to specialize the functions
+ * and that's not possible if we didn't specialize the class. And the logical
+ * separation makes sense as well.
+ */
 class LuaTBTypedStack
 {
 public:
 
-    // Get a non-function argument from the lua stack and convert it to type 'T'
-    // Pops the value from the stack.
+    /**
+     * @brief Get a non-function argument from the lua stack and convert it to type 'T'
+     * @param lua Pointer to the lua state
+     * @return Top element of the lua stack with the appropriate type
+     *
+     * Note: Pops the value from the stack.
+     */
     template<typename T>
     static typename std::enable_if<!IsCallable<T>::value, T>::type getArgument(lua_State *lua)
@@ -25,8 +35,14 @@
     }
 
-    // Specialization if 'T' is a callable type (std::function). Saves the lua
-    // function in the registry and constructs a function to call it again.
-    // 'decltype(&T::operator())' represents the function signature of the callable
-    // object.
+    /**
+     * @brief Get a function-type argument from the lua stack and convert it to type 'T'
+     * @param lua Pointer to the lua state
+     * @return Top element of the lua stack with the appropriate type
+     *
+     * Specialization if 'T' is a callable type (std::function). Saves the lua
+     * function in the registry and constructs a function to call it again.
+     *
+     * Note: Pops the value from the stack.
+     */
     template<typename T>
     static typename std::enable_if<IsCallable<T>::value, T>::type getArgument(lua_State *lua)
@@ -39,4 +55,5 @@
         LuaTBTypedStack::callbackRefs.push_back(std::unique_ptr<int>(ref));
 
+        // 'decltype(&T::operator())' represents the function signature of the callable object.
         return GetLuaCallback<decltype(&T::operator())>::value(lua, ref);
     }
@@ -47,4 +64,11 @@
     // Gets a value from the top of the lua stack and returns it with the proper type.
     // Does not pop the value!
+    /**
+     * @brief Get a value from the lua stack and convert it to type 'T'
+     * @param lua Pointer to the lua state
+     * @return Top element of the lua stack with the appropriate type
+     *
+     * Note: Does NOT pop the value from the stack.
+     */
     template<typename T> static T getFromLuaStack(lua_State *lua);
 
@@ -52,18 +76,34 @@
     // be a normal function signature because it is the signature of
     // std::function<>::operator(), which is also the reason for the 'const'.
+    /**
+     * @brief Needed to get a lambda to call a lua function
+     *
+     * We need this class, becasue we need to specify the signature of the function
+     * before.
+     */
     template<typename Ret, typename... Args>
     struct GetLuaCallback<void (std::function<Ret(Args...)>::*)(Args...) const>
     {
-        // Returns a lambda that will push the arguments to the lua stack and call
-        // the function afterwards. We can't return 'callLuaFunction' directly,
-        // because we need the additional arguments 'lua' and 'ref' which we would
-        // like to hide from the user.
+        /**
+         * @brief Get a lambda to call a lua function later
+         * @param lua Pointer to the lua state
+         * @param ref Pointer to the lua registry reference where the function is stored
+         * @return Lambda that will call the function specified with ref
+         */
         static std::function<void (Args...)> value(lua_State *lua, int *ref)
         {
+            // We can't return 'callLuaFunction' directly, because we need the
+            // additional arguments 'lua' and 'ref' which we would like to hide
+            // from the user.
             return [lua, ref](Args... args){callLuaFunction<Ret, Args...>(lua, ref, args...);};
         }
     };
 
-    // Pushes all arguments to the lua stack and calls a lua function afterwards
+    /**
+     * @brief Pushes all arguments to the lua stack and calls a lua function afterwards
+     * @param lua Pointer to the lua state
+     * @param ref Pointer to the lua registry reference where the function is stored
+     * @param args Arguments for the function
+     */
     template<typename Ret, typename... Args>
     static void callLuaFunction(lua_State *lua, int *ref, Args... args)
@@ -85,12 +125,22 @@
     }
 
-    // This is needed in case the function has no arguments at all. Otherwise, we
-    // would have a missing argument for such function. This is also why we pass
-    // a dummy argument in 'callLuaFunction', so we have at least one argument.
+    /**
+     * @brief Pushes nothing onto the stack
+     *
+     * This is needed in case the function has no arguments at all. Otherwise, we
+     * would have a missing argument for such a function. This is also why we pass
+     * a dummy argument in 'callLuaFunction', so we have at least one argument. It
+     * is the termination point for the recursive template.
+     */
     template<typename T>
     static void pushArgumentsToLuaStack(lua_State *, T)
     { }
 
-    // Recursively pushes arguments to the lua stack
+    /**
+     * @brief Recursively pushes arguments to the lua stack
+     * @param lua Pointer to the lua state
+     * @param first First argument to push onto the stack
+     * @param args The remaining arguments to push onto the stack
+     */
     template<typename First, typename... Args>
     static void pushArgumentsToLuaStack(lua_State *lua, First first, Args... args)
@@ -100,5 +150,11 @@
     }
 
-    // Pushes a value to the lua stack. Only the specializations are valid.
+    /**
+     * @brief Pushes a value to the lua stack
+     * @param lua Pointer to the lua state
+     * @param value The value to push
+     *
+     * Note: Only the specializations are valid
+     */
     template<typename T>
     static void pushToLuaStack(lua_State *lua, T value);
Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller.cc
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller.cc	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller.cc	(revision 11673)
@@ -50,5 +50,5 @@
     }
 
-    // Remeber the api
+    // Remember the api
     this->apis_.push_back(std::unique_ptr<ScriptableControllerAPI>(api));
 
@@ -73,5 +73,4 @@
 void ScriptableController::registerPawn(std::string id, Pawn *pawn)
 {
-    this->worldEntities_[id] = pawn;
     this->pawns_[id] = pawn;
     this->pawnsReverse_[pawn] = id;
@@ -87,9 +86,11 @@
     }
 
-    for(auto &api : this->apis_)
-        api->pawnKilled(pawn_id_iter->second, pawn);
-
+    // The ID of the pawn should already be invalid when we call the callback
+    std::string id = pawn_id_iter->second;
     this->pawns_.erase(pawn_id_iter->second);
     this->pawnsReverse_.erase(pawn_id_iter);
+
+    for(auto &api : this->apis_)
+        api->pawnKilled(id, pawn);
 }
 
@@ -110,16 +111,4 @@
 }
 
-void ScriptableController::killPawn(std::string id)
-{
-    auto pawn = this->getPawnByID(id);
-    if(pawn == nullptr)
-    {
-        orxout(user_warning) << "Tried to destroy unknown pawn " << id << std::endl;
-        return;
-    }
-
-    pawn->kill();
-}
-
 WorldEntity *ScriptableController::getWorldEntityByID(std::string id) const
 {
@@ -138,5 +127,4 @@
     auto entity = this->mobileEntities_.find(id);
     return entity != this->mobileEntities_.end() ? entity->second : nullptr;
-
 }
 
Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller.h
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller.h	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller.h	(revision 11673)
@@ -98,10 +98,4 @@
 
     /**
-     * @brief Kill a Pawn
-     * @param id The Pawn to kill
-     */
-    void killPawn(std::string id);
-
-    /**
      * @brief Convert an ID to a WorldEntity pointer
      * @param id The ID of the WorldEntity
Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.cc
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.cc	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.cc	(revision 11673)
@@ -18,5 +18,5 @@
     this->controller_ = controller;
 
-    // Haven't found a shorter way yet to write that...
+    // Haven't found a shorter way yet to write that... We need C++17!
     LuaTB<ScriptableControllerAPI, decltype(&ScriptableControllerAPI::orxPrint)>::registerFunction<&ScriptableControllerAPI::orxPrint>(this, lua, "orxPrint");
 
@@ -101,8 +101,9 @@
 void ScriptableControllerAPI::killPawn(std::string id)
 {
-    // We don't kill the pawn here directly, because this function is called from LUA and thus
-    // runs in a different thread. So we schedule the kill for later in the main thread
-    // (in 'periodic').
-    this->pawnsToKill_.push_back(id);
+    Pawn *pawn = this->controller_->getPawnByID(id);
+    if(pawn == nullptr)
+        orxout(user_warning) << "Trying to kill an unknown pawn" << std::endl;
+    else
+        pawn->kill();
 }
 
@@ -168,4 +169,5 @@
     const Vector3 &old = entity->getPosition();
 
+    // If one of the values is NaN, don't change that value
     x = std::isnan(x) ? old.x : x;
     y = std::isnan(y) ? old.y : y;
@@ -189,4 +191,5 @@
     entity->getOrientation().ToAngleAxis(old_angle, old_axis);
 
+    // If one of the values is NaN, don't change that value
     x = std::isnan(x) ? old_axis.x : x;
     y = std::isnan(y) ? old_axis.y : y;
@@ -194,4 +197,5 @@
     angle = std::isnan(x) ? old_angle.valueDegrees() : angle;
 
+
     entity->setOrientation(Vector3(x, y, z), Degree(angle));
 }
@@ -208,4 +212,5 @@
     const Vector3 &old = entity->getVelocity();
 
+    // If one of the values is NaN, don't change that value
     x = std::isnan(x) ? old.x : x;
     y = std::isnan(y) ? old.y : y;
@@ -226,4 +231,5 @@
     const Vector3 &old = entity->getAngularVelocity();
 
+    // If one of the values is NaN, don't change that value
     x = std::isnan(x) ? old.x : x;
     y = std::isnan(y) ? old.y : y;
@@ -248,4 +254,22 @@
         else
             near_obj_handler++;
+    }
+
+    auto near_point_handler = this->nearPointHandlers_.begin();
+    while(near_point_handler != this->nearPointHandlers_.end())
+    {
+        if(near_point_handler->entity_ == pawn)
+            near_point_handler = this->nearPointHandlers_.erase(near_point_handler);
+        else
+            near_point_handler++;
+    }
+
+    auto area_handler = this->areaHandlers_.begin();
+    while(area_handler != this->areaHandlers_.end())
+    {
+        if(area_handler->entity_ == pawn)
+            area_handler = this->areaHandlers_.erase(area_handler);
+        else
+            area_handler++;
     }
 }
@@ -319,13 +343,5 @@
         }
     }
-
-    // Pawns to kill
-    // TODO Possible race condidtion when the player destroys the pawn
-    // between the callback and the next periodic call.
-    for(auto &pawn : this->pawnsToKill_)
-        this->controller_->killPawn(pawn);
-
-    this->pawnsToKill_.clear();
-}
-
-}
+}
+
+}
Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.h
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.h	(revision 11662)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.h	(revision 11673)
@@ -146,4 +146,7 @@
      * @param type Name of the class of the object you want to spawn
      * @param id The newly created ID that can be used to access this object
+     *
+     * IMPORTANT: Do not use this function yet, it only has minimal functionality and is not
+     * really helpful as it is.
      */
     void spawn(std::string type, std::string id);
@@ -196,21 +199,4 @@
 
 private:
-    /**
-     * @brief Called by ScriptableController when a pawn is killed
-     * @param id The dead pawn
-     *
-     * Calls the lua callbacks associated with this event.
-     */
-    void pawnKilled(std::string id, Pawn *pawn);
-
-    /**
-     * @brief Called by ScriptableController when a Pawn is hit
-     * @param target_id The hit Pawn
-     * @param source_id The shooting Pawn
-     * @param new_health The new health of the hit Pawn
-     * @param new_shield The new shield health of the hit Pawn
-     */
-    void pawnHit(std::string target_id, std::string source_id, double new_health, double new_shield);
-
     /**
      * @brief Groups everything together that is needed to handle a near-object event
@@ -260,5 +246,4 @@
     };
 
-
     lua_State *lua_;
     ScriptableController *controller_;
@@ -266,5 +251,4 @@
     std::list<NearPointHandler> nearPointHandlers_;
     std::list<AreaHandler> areaHandlers_;
-    std::list<std::string> pawnsToKill_;
     std::map<std::string, std::list<std::function<void (std::string)> > > pawnDestroyedHandlers_;
     std::map<std::string, std::list<std::function<void (std::string, std::string, double, double)> > > pawnHitHandlers_;
@@ -273,9 +257,25 @@
 
     /**
+     * @brief Called by ScriptableController when a pawn is killed
+     * @param id The dead pawn
+     *
+     * Calls the lua callbacks associated with this event.
+     */
+    void pawnKilled(std::string id, Pawn *pawn);
+
+    /**
+     * @brief Called by ScriptableController when a Pawn is hit
+     * @param target_id The hit Pawn
+     * @param source_id The shooting Pawn
+     * @param new_health The new health of the hit Pawn
+     * @param new_shield The new shield health of the hit Pawn
+     */
+    void pawnHit(std::string target_id, std::string source_id, double new_health, double new_shield);
+
+    /**
      * @brief Called every 0.5s
      *
-     * This handles things that have to be checked periodically (like area events) and
-     * things that are done by lua that have to synchronize with the main thread (like
-     * killing a pawn). Doing this in every tick would be an overkill.
+     * This handles things that have to be checked periodically (like area events)
+     * but doing this in every tick would be an overkill.
      */
     void periodic(void);
