Document Atmospherics ExcitedGroups (#41269)

Document ExcitedGroups

Content.Server/Atmos/EntitySystems/AtmosphereSystem.ExcitedGroup.cs

@@ -4,10 +4,31 @@ using Content.Shared.Atmos.Components;
 using Robust.Shared.Map.Components;
 using Robust.Shared.Utility;
 
-namespace Content.Server.Atmos.EntitySystems
+namespace Content.Server.Atmos.EntitySystems;
-{
+
 public sealed partial class AtmosphereSystem
 {
+    /*
+     Handles Excited Groups, an optimization routine executed during LINDA
+     that groups active tiles together.
+
+     Groups of active tiles that have very low mole deltas between them
+     are dissolved after a cooldown period, performing a final equalization
+     on all tiles in the group before deactivating them.
+
+     If tiles are so close together in pressure that the final equalization
+     would result in negligible gas transfer, the group is dissolved without
+     performing an equalization.
+
+     This prevents LINDA from constantly transferring tiny amounts of gas
+     between tiles that are already nearly equalized.
+     */
+
+    /// <summary>
+    /// Adds a tile to an <see cref="ExcitedGroups"/>, resetting the group's cooldowns in the process.
+    /// </summary>
+    /// <param name="excitedGroup">The <see cref="ExcitedGroups"/> to add the tile to.</param>
+    /// <param name="tile">The <see cref="TileAtmosphere"/> to add.</param>
     private void ExcitedGroupAddTile(ExcitedGroup excitedGroup, TileAtmosphere tile)
     {
         DebugTools.Assert(!excitedGroup.Disposed, "Excited group is disposed!");
@@ -17,6 +38,11 @@ namespace Content.Server.Atmos.EntitySystems
         ExcitedGroupResetCooldowns(excitedGroup);
     }
 
+    /// <summary>
+    /// Removes a tile from an <see cref="ExcitedGroups"/>.
+    /// </summary>
+    /// <param name="excitedGroup">The <see cref="ExcitedGroups"/> to remove the tile from.</param>
+    /// <param name="tile">The <see cref="TileAtmosphere"/> to remove.</param>
     private void ExcitedGroupRemoveTile(ExcitedGroup excitedGroup, TileAtmosphere tile)
     {
         DebugTools.Assert(!excitedGroup.Disposed, "Excited group is disposed!");
@@ -25,6 +51,14 @@ namespace Content.Server.Atmos.EntitySystems
         excitedGroup.Tiles.Remove(tile);
     }
 
+    /// <summary>
+    /// Merges two <see cref="ExcitedGroups"/>, transferring all tiles from one to the other.
+    /// The larger group receives the tiles of the smaller group.
+    /// The smaller group is then disposed of without deactivating its tiles.
+    /// </summary>
+    /// <param name="gridAtmosphere">The <see cref="GridAtmosphereComponent"/> of the grid.</param>
+    /// <param name="ourGroup">The first <see cref="ExcitedGroups"/> to merge.</param>
+    /// <param name="otherGroup">The second <see cref="ExcitedGroups"/> to merge.</param>
     private void ExcitedGroupMerge(GridAtmosphereComponent gridAtmosphere, ExcitedGroup ourGroup, ExcitedGroup otherGroup)
     {
         DebugTools.Assert(!ourGroup.Disposed, "Excited group is disposed!");
@@ -59,6 +93,10 @@ namespace Content.Server.Atmos.EntitySystems
         ExcitedGroupResetCooldowns(winner);
     }
 
+    /// <summary>
+    /// Resets the cooldowns of an excited group.
+    /// </summary>
+    /// <param name="excitedGroup">The <see cref="ExcitedGroups"/> to reset cooldowns for.</param>
     private void ExcitedGroupResetCooldowns(ExcitedGroup excitedGroup)
     {
         DebugTools.Assert(!excitedGroup.Disposed, "Excited group is disposed!");
@@ -66,6 +104,11 @@ namespace Content.Server.Atmos.EntitySystems
         excitedGroup.DismantleCooldown = 0;
     }
 
+    /// <summary>
+    /// Performs a final equalization on all tiles in an excited group before deactivating it.
+    /// </summary>
+    /// <param name="ent">The grid.</param>
+    /// <param name="excitedGroup">The <see cref="ExcitedGroups"/> to equalize and dissolve.</param>
     private void ExcitedGroupSelfBreakdown(
         Entity<GridAtmosphereComponent, GasTileOverlayComponent, MapGridComponent, TransformComponent> ent,
         ExcitedGroup excitedGroup)
@@ -85,6 +128,8 @@ namespace Content.Server.Atmos.EntitySystems
             return;
         }
 
+        // Combine all gasses in the group into a single mixture
+        // for distribution into each individual tile.
         foreach (var tile in excitedGroup.Tiles)
         {
             if (tile?.Air == null)
@@ -92,6 +137,8 @@ namespace Content.Server.Atmos.EntitySystems
 
             Merge(combined, tile.Air);
 
+            // If this tile is space and space is all-consuming, the final equalization
+            // will result in a vacuum, so we can skip the rest of the equalization.
             if (!ExcitedGroupsSpaceIsAllConsuming || !tile.Space)
                 continue;
 
@@ -101,6 +148,7 @@ namespace Content.Server.Atmos.EntitySystems
 
         combined.Multiply(1 / (float)tileSize);
 
+        // Distribute the combined mixture evenly to all tiles in the group.
         foreach (var tile in excitedGroup.Tiles)
         {
             if (tile?.Air == null)
@@ -114,8 +162,11 @@ namespace Content.Server.Atmos.EntitySystems
     }
 
     /// <summary>
-        /// This de-activates and removes all tiles in an excited group.
+    /// Deactivates and removes all tiles from an excited group without performing a final equalization.
+    /// Used when an excited group is expected to be nearly equalized already to avoid unnecessary processing.
     /// </summary>
+    /// <param name="gridAtmosphere">The <see cref="GridAtmosphereComponent"/> of the grid.</param>
+    /// <param name="excitedGroup">The <see cref="ExcitedGroups"/> to dissolve.</param>
     private void DeactivateGroupTiles(GridAtmosphereComponent gridAtmosphere, ExcitedGroup excitedGroup)
     {
         foreach (var tile in excitedGroup.Tiles)
@@ -128,7 +179,8 @@ namespace Content.Server.Atmos.EntitySystems
     }
 
     /// <summary>
-        /// This removes an excited group without de-activating its tiles.
+    /// Removes and disposes of an excited group without performing any final equalization
+    /// or deactivation of its tiles.
     /// </summary>
     private void ExcitedGroupDispose(GridAtmosphereComponent gridAtmosphere, ExcitedGroup excitedGroup)
     {
@@ -148,4 +200,3 @@ namespace Content.Server.Atmos.EntitySystems
         excitedGroup.Tiles.Clear();
     }
 }
-}

Content.Server/Atmos/EntitySystems/AtmosphereSystem.LINDA.cs

@@ -129,9 +129,16 @@ namespace Content.Server.Atmos.EntitySystems
 
             switch (tile.LastShare)
             {
+                // Refresh this tile's suspension cooldown if it had significant sharing.
                 case > Atmospherics.MinimumAirToSuspend:
                     ExcitedGroupResetCooldowns(tile.ExcitedGroup);
                     break;
+
+                // If this tile moved a very small amount of air, but not enough to matter,
+                // we set the dismantle cooldown to 0.
+                // This dissolves the group without performing an equalization as we expect
+                // the group to be mostly equalized already if we're moving around miniscule
+                // amounts of air.
                 case > Atmospherics.MinimumMolesDeltaToMove:
                     tile.ExcitedGroup.DismantleCooldown = 0;
                     break;

Content.Server/Atmos/EntitySystems/AtmosphereSystem.Processing.cs

@@ -365,7 +365,6 @@ namespace Content.Server.Atmos.EntitySystems
                     ExcitedGroupSelfBreakdown(ent, excitedGroup);
                 else if (excitedGroup.DismantleCooldown > Atmospherics.ExcitedGroupsDismantleCycles)
                     DeactivateGroupTiles(gridAtmosphere, excitedGroup);
-                // TODO ATMOS. What is the point of this? why is this only de-exciting the group? Shouldn't it also dismantle it?
 
                 if (number++ < LagCheckIterations)
                     continue;

Content.Server/Atmos/ExcitedGroup.cs

@@ -1,13 +1,44 @@
-namespace Content.Server.Atmos
+namespace Content.Server.Atmos;
-{
+
+/// <summary>
+/// <para>Internal Atmospherics class that stores data about a group of <see cref="TileAtmosphere"/>s
+/// that are excited and need to be processed.</para>
+///
+/// <para>Excited Groups is an optimization routine executed during LINDA
+/// that bunches small groups of active <see cref="TileAtmosphere"/>s
+/// together and performs equalization processing on the entire group when the group dissolves.
+/// Dissolution happens when LINDA operations between the tiles decrease to very low mole deltas.</para>
+/// </summary>
 public sealed class ExcitedGroup
 {
-        [ViewVariables] public bool Disposed = false;
+    /// <summary>
+    /// Whether this Active Group has been disposed of.
+    /// Used to make sure we don't perform operations on active groups that
+    /// we've already dissolved.
+    /// </summary>
+    [ViewVariables]
+    public bool Disposed = false;
 
-        [ViewVariables] public readonly List<TileAtmosphere> Tiles = new(100);
+    /// <summary>
+    /// List of tiles that belong to this excited group.
+    /// </summary>
+    [ViewVariables]
+    public readonly List<TileAtmosphere> Tiles = new(100);
 
-        [ViewVariables] public int DismantleCooldown { get; set; } = 0;
+    /// <summary>
+    /// Cycles before this excited group will be queued for dismantling.
+    /// Dismantling is the process of equalizing the atmosphere
+    /// across all tiles in the excited group and removing the group.
+    /// </summary>
+    [ViewVariables]
+    public int DismantleCooldown = 0;
 
-        [ViewVariables] public int BreakdownCooldown { get; set; } = 0;
+    /// <summary>
-    }
+    /// Cycles before this excited group will be allowed to break down and deactivate.
+    /// Breakdown occurs when the excited group is small enough and inactive enough
+    /// to be safely removed without equalization. Used where the mole deltas across
+    /// the group are very low but not high enough for an equalization to occur.
+    /// </summary>
+    [ViewVariables]
+    public int BreakdownCooldown = 0;
 }