Index: code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.h
===================================================================
--- code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.h	(revision 11583)
+++ code/branches/ScriptableController_HS17/src/orxonox/scriptablecontroller/scriptable_controller_api.h	(revision 11606)
@@ -15,28 +15,151 @@
 class WorldEntity;
 
+/**
+ * @brief API for ScriptableController's lua-scripts
+ *
+ * Defines the interface that lua can use in the scripts to communicate with orxonox.
+ *
+ * \sa ScriptableController
+ */
 class ScriptableControllerAPI
 {
 public:
+    /**
+     * @brief Constructs the API with the given lua state
+     * @param lua The lua state
+     * @param controller The parent controller
+     *
+     * This will not run any scripts, it'll just make the API visible to lua.
+     */
     ScriptableControllerAPI(lua_State *lua, ScriptableController *controller);
+
+    /**
+     * @brief Destructs the API and closes the lua state.
+     */
     ~ScriptableControllerAPI();
 
-    void testOutput(std::function<void(std::string)> callback);
-
+    // --- API ----------------------------------
+
+    /**
+     * @brief Print a message
+     * @param msg The message
+     *
+     * Use this function instead of printing from lua directly, because that will mess up the
+     * output as it is not synchronized.
+     */
     void orxPrint(std::string msg);
+
+    /**
+     * @brief Register a function that will be called after a timeout
+     * @param callback The function to call after the timeout expired
+     * @param timeout The timeout in seconds
+     */
     void registerAfterTimeout(std::function<void (void)> callback, double timeout);
 
+    /**
+     * @brief Register a function that will be called when two object are close to eachother
+     * @param callback The function to call when the objects are close enough
+     * @param id1 The first object
+     * @param id2 The second object
+     * @param distance If the distance between the two objects is smaller than this value,
+     * the function is called
+     *
+     * Note: Distances are only checked every 0.5s!
+     */
     void registerAtNearObject(std::function<void(std::string, std::string)> callback, std::string id1, std::string id2, double distance);
+
+    /**
+     * @brief Register a function that will be called when an object is close to a certain point
+     * @param callback The function to call when the object is close enough
+     * @param id The object
+     * @param x X-coordinate of the point
+     * @param y Y-coordinate of the point
+     * @param z Z-coordinate of the point
+     * @param distance If the distance between the object and the point is smaller than this value, the
+     * function is called.
+     *
+     * Note: Distances are only checked every 0.5s!
+     */
     void registerAtNearPoint(std::function<void (std::string)> callback, std::string id, double x, double y, double z, double distance);
-    void registerAtAreaEnter(std::function<void (std::string)> callback, std::string obj, int x, int y, int z, int dx, int dy, int dz);
-    void registerAtAreaLeave(std::function<void (std::string)> callback, std::string obj, int x, int y, int z, int dx, int dy, int dz);
-
-    void registerAtObjectDestroyed(std::function<void (std::string)> callback, std::string obj);
-    void registerAtPickup(std::function<void (int)> callback, int pickup_id);
-
-    void destroyObject(std::string obj);
-    void removeObject(std::string obj);
-    void setObjectPosition(std::string obj, double x, double y, double z);
+
+    /**
+     * @brief Register a function that will be called when an object enters a cubic area
+     * @param callback The function to call when the object entered the area
+     * @param id The object
+     * @param x X-coordinate of the top-left corner
+     * @param y Y-coordinate of the top-left corner
+     * @param z Z-coordinate of the top-left corner
+     * @param dx Size in X-direction of the cube
+     * @param dy Size in Y-direction of the cube
+     * @param dz Size in Z-direction of the cube
+     *
+     * Note: Distances are only checked every 0.5s!
+     */
+    void registerAtAreaEnter(std::function<void (std::string)> callback, std::string id, int x, int y, int z, int dx, int dy, int dz);
+
+    /**
+     * @brief Register a function that will be called when an object leaves a cubic area
+     * @param callback The function to call when the object left the area
+     * @param id The object
+     * @param x X-coordinate of the top-left corner
+     * @param y Y-coordinate of the top-left corner
+     * @param z Z-coordinate of the top-left corner
+     * @param dx Size in X-direction of the cube
+     * @param dy Size in Y-direction of the cube
+     * @param dz Size in Z-direction of the cube
+     *
+     * Note: Distances are only checked every 0.5s!
+     */
+    void registerAtAreaLeave(std::function<void (std::string)> callback, std::string id, int x, int y, int z, int dx, int dy, int dz);
+
+    /**
+     * @brief Register a function that will be called when a Pawn is killed
+     * @param callback The function to call as soon as the Pawn is dead
+     * @param id The Pawn
+     *
+     * Note: Once a Pawn is dead, the callback is removed, even if the pawn got magically revived.
+     */
+    void registerAtPawnKilled(std::function<void (std::string)> callback, std::string id);
+
+    /**
+     * @brief Register a function that will be called when a Pawn is hit
+     * @param callback The function to call as soon as the Pawn is hit
+     * @param id The Pawn
+     *
+     * Note: Once a Pawn is dead, the all hit-callbacks are removed, even if the pawn got magically revived.
+     */
+    void registerAtPawnHit(std::function<void (std::string, std::string, double, double)> callback, std::string id);
+
+    /**
+     * @brief Kill a pawn
+     * @param id The pawn to kill
+     *
+     * Note: It might up to 0.5s until the pawn is actually killed.
+     */
+    void killPawn(std::string id);
+
+    // ------------------------------------------
+
+    /**
+     * @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);
+
+    /**
+     * @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);
 
 private:
+    /**
+     * @brief Groups everything together that is needed to handle a near-object event
+     */
     struct NearObjectHandler
     {
@@ -51,4 +174,7 @@
     };
 
+    /**
+     * @brief Groups everything together that is needed to handle a near-poinb event
+     */
     struct NearPointHandler
     {
@@ -64,4 +190,7 @@
     };
 
+    /**
+     * @brief Groups everything together that is needed to handle an area enter/leave event
+     */
     struct AreaHandler
     {
@@ -83,7 +212,18 @@
     std::list<NearPointHandler> nearPointHandlers_;
     std::list<AreaHandler> areaHandlers_;
-    Timer areaCheckTimer;
-
-    void checkAreas(void);
+    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_;
+    Timer periodicTimer;
+    static const double periodic_interval;
+
+    /**
+     * @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.
+     */
+    void periodic(void);
 };
 
