Document Harmony Patches

Patch/Game/PersistencePatch.cs

@@ -3,9 +3,23 @@ using HarmonyLib;
 
 namespace ADOFAIRenderer.Patch.Game;
 
+/// <summary>
+/// Overrides two player settings read from <c>Persistence</c> during a render: the "skip intro" option and the planet colors.
+/// </summary>
 [HarmonyPatch(typeof(Persistence))]
 public static class PersistencePatch
 {
+    /// <summary>
+    /// Postfix of the <c>Persistence.skipIntroBehavior</c> getter (setting values Off / AfterFirstTry / Always).
+    /// <para>
+    /// <c>scrConductor.StartMusicCo</c> reads this setting when the song is scheduled and, for AfterFirstTry (after a death) or
+    /// Always (long intro, no checkpoint), sets <c>skipOffset</c>, which moves <c>dspTimeSong</c> back by the level offset and
+    /// starts the song part-way in. While <see cref="RenderManager.IsActive"/> (stage &gt;= OnScene) and the song has not
+    /// started yet (<c>scrConductor.hasSongStarted</c> false), the getter returns Off, so <c>skipOffset</c> stays false and the
+    /// song always plays from its start. The mod's offline BGM mixing, spectrum and video background timing assume this.
+    /// </para>
+    /// </summary>
+    /// <param name="__result">Value returned by the getter; replaced with <c>SkipIntroBehavior.Off</c> under the conditions above.</param>
     [HarmonyPostfix]
     [HarmonyPatch("skipIntroBehavior", MethodType.Getter)]
     // ReSharper disable once InconsistentNaming
@@ -19,6 +33,18 @@ public static class PersistencePatch
         }
     }
 
+    /// <summary>
+    /// Postfix of <c>Persistence.GetPlayerColor(bool red)</c>, which returns the player's saved planet color
+    /// (preset name or hex color from the general preferences; default red/blue otherwise). <c>PlanetRenderer</c> uses it to
+    /// color the fire (red) and ice (blue) planets.
+    /// <para>
+    /// Active from stage Load (render started, scene loading) until the stage returns to None. When the render configuration
+    /// sets <c>AdvancedConfig.firePlanetColor</c> (red) or <c>AdvancedConfig.icePlanetColor</c> (blue), that color replaces the
+    /// saved color; an unset (null) override keeps the game value. The saved preference itself is not changed.
+    /// </para>
+    /// </summary>
+    /// <param name="red">True for the fire (red) planet, false for the ice (blue) planet.</param>
+    /// <param name="__result">Color returned by the game; replaced by the configured override when set.</param>
     [HarmonyPostfix]
     [HarmonyPatch("GetPlayerColor")]
     // ReSharper disable once InconsistentNaming