Merge pull request #78159 from truewis/hoard_mob_type_implementation

Commented codes related to mongroup functionality.

src/map.cpp

@@ -9287,6 +9287,8 @@ void map::spawn_monsters_submap_group( const tripoint_rel_sm &gp, mongroup &grou
                 // Give monster a random point near horde's expected destination
                 const tripoint_sm_ms pos_in_sm( rng( 0, SEEX ), rng( 0, SEEY ), local_pos.z() );
                 const tripoint_abs_ms rand_dest = project_combine( group.target, pos_in_sm );
+
+                // The monster will wander to the rand_dest for several turns which is determined by the distance and interest
                 const int turns = rl_dist( abs_pos, rand_dest ) + group.interest;
                 tmp.wander_to( rand_dest, turns );
                 add_msg_debug( debugmode::DF_MAP, "%s targeting %s", tmp.disp_name(),

src/mongroup.cpp

@@ -84,6 +84,10 @@ void mongroup::clear()
     monsters.clear();
 }
 
+/**
+ * The average speed of the monsters in the group.
+ * If monsters vector is empty, the average speed of the group is calculated.
+ */
 float mongroup::avg_speed() const
 {
     float avg_speed = 0.0f;

src/mongroup.h

@@ -86,26 +86,39 @@ struct MonsterGroupResult {
     }
 };
 
+/**
+ * MonsterGroup is a theoretical distribution of monsters to spawn, as opposed to a mongroup which is an instance of group of monsters to be spawned together.
+*/
 struct MonsterGroup {
     mongroup_id name;
     mtype_id defaultMonster;
     FreqDef monsters;
     bool IsMonsterInGroup( const mtype_id &id ) const;
     bool is_animal = false;
-    // replaces this group after a period of
-    // time when exploring an unexplored portion of the map
+
+    /*replaces this group after a period of time when exploring an unexplored portion of the map. Used for monster evolution. */
     bool replace_monster_group = false;
+    /* The monster group to replace this if replace_monster_group == true. */
     mongroup_id new_monster_group;
+    /* Time until replacement if replace_monster_group == true. */
     time_duration monster_group_time = 0_turns;
-    bool is_safe = false; /// Used for @ref mongroup::is_safe()
+
+    /** Encapsulated by mongroup::is_safe(), but currently not used anywhere.*/
+    bool is_safe = false;
     int freq_total = 0; // max number to roll for spawns (non-event)
     std::map<holiday, int> event_freq; // total freq for each event
     // Get the total frequency of entries that are valid for the specified event.
     // This includes entries that have an event of "none". By default, use the current holiday.
     int event_adjusted_freq_total( holiday event = holiday::num_holiday ) const;
 };
 
+/**
+ * A mongroup is a group of monsters that are spawned together. There are two uses for mongroups:
+ * 1. spawning new monsters.
+ * 2. unload monsters out of sight of the player into hordes and spawn them back in when the player is close enough.
+ */
 struct mongroup {
+    /** The type of the mongroup, which is only used to spawn new monsters and not for hordes. */
     mongroup_id type;
     /** The monsters vector will be ignored if the vector is empty.
      *  Otherwise it will keep track of the individual monsters that
@@ -115,12 +128,25 @@ struct mongroup {
     std::vector<monster> monsters;
     // Note: position is not saved as such in the json
     // Instead, a vector of positions is saved for
-    tripoint_abs_sm abs_pos; // position of the mongroup in absolute submap coordinates
+
+    /** position of the mongroup in absolute submap coordinates*/
+    tripoint_abs_sm abs_pos;
+
+    /**
+     * Number of monsters in the group. If the monsters vector is not empty, this will be ignored.
+     */
     unsigned int population = 1;
-    point_abs_sm target; // location the horde is interested in.
-    point_abs_sm nemesis_target; // abs target for nemesis hordes
-    int interest = 0; //interest to target in percents
+
+    /** location the horde is interested in. Do not set this directly, use set_target instead. */
+    point_abs_sm target;
+    /** abs target for nemesis hordes. */
+    point_abs_sm nemesis_target; //
+    /** interest to target in percents. Used to determine movement speed(overmap::move_hordes), or reaction to signal sources(overmap::signal_hordes), etc.*/
+    int interest = 0;
+
+    /** If true, overmap::process_mongroups decreases the population by a fixed ratio every time the function is called. */
     bool dying = false;
+    /** If false, this group is not a horde, and instead is likely an attempt to spawn new monsters through map::spawn_monsters_submap from overmap_buffer. */
     bool horde = false;
 
     enum class horde_behaviour : short {
@@ -157,18 +183,32 @@ struct mongroup {
         nemesis_target = p;
     }
     void wander( const overmap & );
+
+    /**
+     * This function increases the interest of the group, but ensures that it does not exceed 100 percent.
+     *
+     */
     void inc_interest( int inc ) {
         interest += inc;
         if( interest > 100 ) {
             interest = 100;
         }
     }
+
+    /**
+     * This function decreases the interest of the group, but ensures that it does not fall below 15 percent.
+     *
+     */
     void dec_interest( int dec ) {
         interest -= dec;
         if( interest < 15 ) {
             interest = 15;
         }
     }
+    /**
+     * This function sets the interest of the group, but ensures that it does not fall below 15 percent or exceed 100 percent.
+     *
+     */
     void set_interest( int set ) {
         if( set < 15 ) {
             set = 15;

src/overmap.cpp

@@ -4345,7 +4345,9 @@ void overmap::place_special_forced( const overmap_special_id &special_id,
     static city invalid_city;
     place_special( *special_id, p, dir, invalid_city, false, true );
 }
-
+/**
+ * Let the group wander aimlessly, unless behaviour is set to city, in which case it will move to the city center.
+ */
 void mongroup::wander( const overmap &om )
 {
     const city *target_city = nullptr;
@@ -4376,11 +4378,17 @@ void mongroup::wander( const overmap &om )
         target = target_abs + delta;
         interest = 100;
     } else {
+
+        // No city to target, wander aimlessly.
         target = abs_pos.xy() + point( rng( -10, 10 ), rng( -10, 10 ) );
         interest = 30;
     }
 }
 
+/**
+ * Moves hordes around the map according to their behaviour and target.
+ * Also, emerge hordes from monsters that are outside the player's view. Currently only works for zombies.
+ */
 void overmap::move_hordes()
 {
     // Prevent hordes to be moved twice by putting them in here after moving.
@@ -4532,6 +4540,11 @@ void overmap::move_hordes()
     }
 }
 
+/**
+ * Move the nemesis horde towards the player.
+ * Currently only works for the first nemesis horde. If there are multiple, only the first one will be moved.
+ *
+ */
 void overmap::move_nemesis()
 {
     // Prevent hordes to be moved twice by putting them in here after moving.
@@ -4620,6 +4633,8 @@ bool overmap::remove_nemesis()
 }
 
 /**
+ * Alert hordes to the signal source such as a loud explosion.
+ *
 * @param p location of signal relative to this overmap origin
 * @param sig_power - power of signal or max distance for reaction of zombies
 */