[Add] Pilot death explosion sounds.

[Add] More documentation.

src/pilot.c

@@ -271,7 +271,17 @@ static void pilot_shootWeapon(Pilot* p, PilotOutfit* w, const unsigned int t) {
   }
 }
 
-/* Damage the pilot. */
+/**
+ * @fn void pilot_hit(Pilot* p, const Solid* w, const unsigned int shooter,
+ *                    const DamageType dtype, const double damage)
+ *
+ * @brief Damages the pilot.
+ *    @param p Pilot that is taking damage.
+ *    @param w Solid that is hitting pilot.
+ *    @param shooter Attacker that shot the pilot.
+ *    @param dtype type of damage.
+ *    @param damage Amount of damage.
+ */
 void pilot_hit(Pilot* p, const Solid* w, const unsigned int shooter,
     const DamageType dtype, const double damage) {
 
@@ -322,6 +332,12 @@ void pilot_hit(Pilot* p, const Solid* w, const unsigned int shooter,
       knockback * (w->vel.y * (dam_mod/6. + w->mass/p->solid->mass/6.)));
 }
 
+/**
+ * @fn void pilot_dead(Pilot* p)
+ *
+ * @brief Pilot is dead, now will slowly explode.
+ *    @param p Pilot that just died.
+ */
 void pilot_dead(Pilot* p) {
   if(pilot_isFlag(p, PILOT_DEAD)) return; /* She's already dead. */
   /* Basically just set the timers.. */
@@ -343,6 +359,13 @@ void pilot_dead(Pilot* p) {
     hook_runID(p->hook);
 }
 
+/**
+ * @fn void pilot_setSecondary(Pilot* p, const char* secondary)
+ *
+ * @brief Set the pilots secondary weapon based on its name.
+ *    @param p Pilot to set secondary weapon.
+ *    @param secondary Name of the secondary weapon to set.
+ */
 void pilot_setSecondary(Pilot* p, const char* secondary) {
   int i;
 
@@ -367,7 +390,12 @@ void pilot_setSecondary(Pilot* p, const char* secondary) {
   p->ammo = NULL;
 }
 
-/* Set the pilot's ammo based on their secondary weapon. */
+/**
+ * @fn void pilot_setAmmo(Pilot* p)
+ *
+ * @param Set the pilots ammo based on their secondary weapon.
+ *    @param p Pilot to set ammo.
+ */
 void pilot_setAmmo(Pilot* p) {
   int i;
   char* name;
@@ -391,7 +419,12 @@ void pilot_setAmmo(Pilot* p) {
   p->ammo = NULL;
 }
 
-/* Set the pilots afterburner. */
+/**
+ * @fn void pilot_setAfterburner(Pilot* p)
+ *
+ * @brief Set the pilots afterburner if she has one.
+ *    @param p Pilot to set afterburner.
+ */
 void pilot_setAfterburner(Pilot* p) {
   int i;
 
@@ -403,18 +436,30 @@ void pilot_setAfterburner(Pilot* p) {
   p->afterburner = NULL;
 }
 
-/* Render the pilot. */
+/**
+ * @fn void pilot_render(Pilot* p)
+ *
+ * @brief Render the pilot.
+ *    @param p Pilot to render.
+ */
 void pilot_render(Pilot* p) {
   gl_blitSprite(p->ship->gfx_space,
                 p->solid->pos.x, p->solid->pos.y,
                 p->tsx, p->tsy, NULL);
 }
 
-/* Update the pilot. */
+/**
+ * @fn static void pilot_update(Pilot* pilot, const double dt)
+ *
+ * @brief Updates the pilot.
+ *    @param pilot Pilot to update.
+ *    @param dt Current delta tick.
+ */
 static void pilot_update(Pilot* pilot, const double dt) {
   int i;
   unsigned int t, l;
   double a, px, py, vx, vy;
+  char buf[16];
 
   /* She's dead D: */
   if(pilot_isFlag(pilot, PILOT_DEAD)) {
@@ -427,8 +472,17 @@ static void pilot_update(Pilot* pilot, const double dt) {
       return;
     }
 
+    /* Pilot death sound. */
+    if(!pilot_isFlag(pilot, PILOT_DEATH_SOUND) && (t > pilot->ptimer - 50)) {
+      /* Play random explosion sound. */
+      snprintf(buf, 16, "explosion%d", RNG(0,2));
+      sound_playPos(sound_get(buf), pilot->solid->pos.x, pilot->solid->pos.y);
+
+      pilot_setFlag(pilot, PILOT_DEATH_SOUND);
+    }
+
     /* Final explosion. */
-    if(!pilot_isFlag(pilot, PILOT_EXPLODED) && (t > pilot->ptimer - 200)) {
+    else if(!pilot_isFlag(pilot, PILOT_EXPLODED) && (t > pilot->ptimer - 200)) {
       spfx_add(spfx_get("ExpL"),
                VX(pilot->solid->pos), VY(pilot->solid->pos),
                VX(pilot->solid->vel), VY(pilot->solid->vel), SPFX_LAYER_BACK);

src/pilot.h

@@ -31,22 +31,23 @@
 #define pilot_setFlag(p,f)  (p->flags |= (f))
 #define pilot_rmFlag(p,f)   (p->flags ^= (f))
 /* Creation. */
-#define PILOT_PLAYER        (1<<0)  /* Pilot is a player. */
-#define PILOT_HASTURRET     (1<<20) /* Pilot has turrets. */
-#define PILOT_NO_OUTFITS    (1<<21) /* Do not create the pilot with outfits. */
-#define PILOT_EMPTY         (1<<22) /* Do not add pilot to stack. */
+#define PILOT_PLAYER        (1<<0)  /**< Pilot is a player. */
+#define PILOT_HASTURRET     (1<<20) /**< Pilot has turrets. */
+#define PILOT_NO_OUTFITS    (1<<21) /**< Do not create the pilot with outfits. */
+#define PILOT_EMPTY         (1<<22) /**< Do not add pilot to stack. */
 /* Dynamic. */
-#define PILOT_HOSTILE       (1<<1)  /* Pilot is hostile to the player. */
-#define PILOT_COMBAT        (1<<2)  /* Pilot is engaged in combat. */
-#define PILOT_AFTERBURNER   (1<<3)  /* Pilot has her afterburner activated. */
-#define PILOT_HYP_PREP      (1<<5)  /* Pilot is getting ready for hyperspace. */
-#define PILOT_HYP_BEGIN     (1<<6)  /* Pilot is starting engines. */
-#define PILOT_HYPERSPACE    (1<<7)  /* Pilot is in hyperspace. */
-#define PILOT_BOARDED       (1<<8)  /* Pilot has been boarded already! */
-#define PILOT_DISABLED      (1<<9)  /* Pilot is disabled. */
-#define PILOT_DEAD          (1<<10) /* Pilot is on it's death bed. */
-#define PILOT_EXPLODED      (1<<11) /* Pilot did final death explosion. */
-#define PILOT_DELETE        (1<<15) /* Pilot will get delete asap. */
+#define PILOT_HOSTILE       (1<<1)  /**< Pilot is hostile to the player. */
+#define PILOT_COMBAT        (1<<2)  /**< Pilot is engaged in combat. */
+#define PILOT_AFTERBURNER   (1<<3)  /**< Pilot has her afterburner activated. */
+#define PILOT_HYP_PREP      (1<<5)  /**< Pilot is getting ready for hyperspace. */
+#define PILOT_HYP_BEGIN     (1<<6)  /**< Pilot is starting engines. */
+#define PILOT_HYPERSPACE    (1<<7)  /**< Pilot is in hyperspace. */
+#define PILOT_BOARDED       (1<<8)  /**< Pilot has been boarded already! */
+#define PILOT_DISABLED      (1<<9)  /**< Pilot is disabled. */
+#define PILOT_DEAD          (1<<10) /**< Pilot is on it's death bed. */
+#define PILOT_DEATH_SOUND   (1<<11) /**< Pilot just did death explosion. */
+#define PILOT_EXPLODED      (1<<12) /**< Pilot did final death explosion. */
+#define PILOT_DELETE        (1<<15) /**< Pilot will get delete asap. */
 
 /* Just makes life simpler. */
 #define pilot_isPlayer(p)   ((p)->flags & PILOT_PLAYER)
@@ -65,65 +66,80 @@ typedef struct PilotCommodity_ {
   unsigned int id;  /* Special mission id for cargo. */
 } PilotCommodity;
 
-/* Primary pilot structure. */
+/**
+ * @struct Pilot
+ *
+ * @brief The representation of an ingame pilot.
+ */
 typedef struct Pilot_ {
-  unsigned int id;  /* Pilots id. */
-  char* name;       /* Pilot's name (if unique). */
-  char* title;      /* Title - Usuall indicating special properties - TODO. */
+  unsigned int id;  /**< Pilots id. */
+  char* name;       /**< Pilot's name (if unique). */
+  char* title;      /**< Title - Usuall indicating special properties - TODO. */
 
-  int faction;      /* Pilot faction. */
+  int faction;      /**< Pilot faction. */
 
   /* Object characteristics. */
-  Ship* ship;     /* Pilots ship. */
-  Solid* solid;   /* Associated solid (physics). */
-  int tsx, tsy;   /* Current sprite, calculated on update. */
+  Ship* ship;     /**< Pilots ship. */
+  Solid* solid;   /**< Associated solid (physics). */
+  int tsx;        /**< Current sprite x position, calculated on update. */
+  int tsy;        /**< Current sprite y position, calculated on update. */
 
-  double thrust, turn, speed;
+  double thrust;  /**< Pilots thrust. */
+  double turn;    /**< Pilots turn. */
+  double speed;   /**< Pilots speed. */
 
   /* Current health. */
-  double armour, shield, energy, fuel;
-  double armour_max, shield_max, energy_max, fuel_max;
-  double armour_regen, shield_regen, energy_regen;
+  double armour;        /**< Current armour. */
+  double shield;        /**< Current shield. */
+  double energy;        /**< Current energy. */
+  double fuel;          /**< Current fuel. */
+  double armour_max;    /**< Max armour. */
+  double shield_max;    /**< Max shield. */
+  double energy_max;    /**< Max energy. */
+  double fuel_max;      /**< Max fuel. */
+  double armour_regen;  /**< Armour regeneration rate (per second). */
+  double shield_regen;  /**< Shield regeneration rate (per second). */
+  double energy_regen;  /**< Energy regeneration rate (per second). */
 
-  void (*think)(struct Pilot_*); /* AI thinking for the pilot. */
-  void (*update)(struct Pilot_*, const double); /* Update the pilot. */
-  void (*render)(struct Pilot_*); /* Rendering the pilot. */
+  void (*think)(struct Pilot_*);                /**< AI thinking for the pilot. */
+  void (*update)(struct Pilot_*, const double); /**< Update the pilot. */
+  void (*render)(struct Pilot_*);               /**< Rendering the pilot. */
 
   /* Outfit management. */
-  PilotOutfit* outfits;
-  int noutfits;
-  PilotOutfit* secondary;   /* Secondary weapon. */
-  PilotOutfit* ammo;        /* Secondary ammo (if needed). */
-  PilotOutfit* afterburner; /* Ze afterburner. */
+  PilotOutfit* outfits;     /**< Pilot outfit stack. */
+  int noutfits;             /**< Pilot number of outfits. */
+  PilotOutfit* secondary;   /**< Secondary weapon. */
+  PilotOutfit* ammo;        /**< Secondary ammo (if needed). */
+  PilotOutfit* afterburner; /**< The afterburner. */
 
   /* Jamming. */
-  double jam_range;
-  double jam_chance;
+  double jam_range;         /**< Range at wich pilot starts jamming. */
+  double jam_chance;        /**< Jam chance. */
 
   /* Cargo. */
-  int credits; /* Moniez the pilot has. */
-  PilotCommodity* commodities; /* Commodity and quantity. */
-  int ncommodities;
-  int cargo_free;
+  int credits;                  /**< Moniez the pilot has. */
+  PilotCommodity* commodities;  /**< Commodity and quantity. */
+  int ncommodities;             /**< Number of commodies. */
+  int cargo_free;               /**< Free commodity space. */
 
   /* Weapon Properties. */
-  double weap_range; /* Average range of primary weapons */
-  double weap_speed; /* Average speed of primary weapons. */
+  double weap_range; /**< Average range of primary weapons. */
+  double weap_speed; /**< Average speed of primary weapons. */
 
   /* Misc. */
-  uint32_t flags;       /* Used for AI etc. */
-  unsigned int ptimer;  /* Generic timer for internal pilot use. */
-  int lockons;          /* Stores how many seeking weapons are targetting pilot. */
+  uint32_t flags;       /**< Used for AI etc. */
+  unsigned int ptimer;  /**< Generic timer for internal pilot use. */
+  int lockons;          /**< Stores how many seeking weapons are targetting pilot. */
 
   /* Hook attached to the pilot. */
-  int hook_type;
-  int hook;
+  int hook_type;  /**< Type of the hook atached to the pilot. */
+  int hook;       /**< Hook id. */
 
   /* AI. */
-  AI_Profile* ai; /* Ai personality profile. */
-  unsigned int tcontrol; /* Timer for control tick. */
-  unsigned int timer[MAX_AI_TIMERS]; /* Timers for AI. */
-  Task* task; /* Current action. */
+  AI_Profile* ai;                     /**< Ai personality profile. */
+  unsigned int tcontrol;              /**< Timer for control tick. */
+  unsigned int timer[MAX_AI_TIMERS];  /**< Timers for AI. */
+  Task* task;                         /**< Current action. */
 } Pilot;
 
 /* Fleets. */