Document Harmony Patches

Patch/Game/scnGamePatch.cs

@@ -6,10 +6,26 @@ using UnityEngine;
 
 namespace ADOFAIRenderer.Patch.Game;
 
+/// <summary>
+/// Patches of <c>scnGame</c> (custom level scene controller, also used by the editor's play mode): hides tiles and planets
+/// for the "non-tile" render option and replaces the background video player during a render.
+/// </summary>
 [HarmonyPatch(typeof(scnGame))]
 // ReSharper disable once InconsistentNaming
 public static class scnGamePatch
 {
+    /// <summary>
+    /// Postfix of <c>scnGame.Play(int seqID, bool remakeFloors)</c>, which starts (or restarts) play of the custom level:
+    /// it resets the conductor, camera and controller state for the given start tile.
+    /// <para>
+    /// Active from stage Load when <c>AdvancedConfig.NonTile</c> is enabled. Disables the renderers of every floor in
+    /// <c>scrLevelMaker.listFloors</c> (floor mesh, legacy sprite, icon, outline, top/bottom glow, multi-planet line,
+    /// hold mesh, dummy planets) and of every planet of every player (sprite mesh, core/tail/sparks particles, ring, glow,
+    /// face, samurai sprite), so only the background and decorations remain in the rendered video. The renderers are only
+    /// disabled; the objects keep running. Hold meshes re-enable themselves, so <c>RenderManager.OnLastUpdate</c> disables
+    /// them again every frame.
+    /// </para>
+    /// </summary>
     [HarmonyPostfix]
     [HarmonyPatch("Play")]
     public static void ProcessFloors()
@@ -47,6 +63,7 @@ public static class scnGamePatch
         }
         return;
 
+        // Disables every renderer that draws one planet (fire, ice, extra planets and floor dummy planets).
         void DisablePlanetRenderer(PlanetRenderer planet)
         {
             if (planet.sprite) DisableRenderer(planet.sprite.meshRenderer);
@@ -62,12 +79,29 @@ public static class scnGamePatch
             foreach (var renderer in renderers) DisableRenderer(renderer);
         }
 
+        // Sets Renderer.enabled = false; null or destroyed renderers are skipped (Unity null check).
         void DisableRenderer(Renderer? renderer)
         {
             if (renderer) renderer.enabled = false;
         }
     }
         
+    /// <summary>
+    /// Prefix of <c>scnGame.UpdateVideo()</c>, which sets up the level's background video on the native Unity
+    /// <c>VideoPlayer</c> (<c>scnGame.videoBG</c>): it reads <c>miscSettings.bgVideo</c>, loads a <c>VideoClip</c> for internal
+    /// (Resources / Addressables) and bundle levels or sets <c>videoBG.url</c> to the file next to the custom level, then calls
+    /// <c>Stop()</c>, <c>Prepare()</c> and sets <c>isLooping</c> from <c>loopVideo</c>. The game calls it from
+    /// <c>scnGame.FinishCustomLevelLoading</c> and from <c>scnGame.ReloadAssets</c> when <c>force</c> is true.
+    /// <para>
+    /// While <see cref="RenderManager.IsActive"/> (stage &gt;= OnScene), an external video file of a custom level is played by
+    /// <see cref="VideoBGPlayer"/> (FFmpeg decoder), which shows the frame for the render time of each frame. The native
+    /// <c>VideoPlayer</c> plays in real time and would drift from the offline render clock, so it is disabled for that case.
+    /// Internal and bundle levels (built-in <c>VideoClip</c> assets, not files) and a missing file use the original method.
+    /// </para>
+    /// <para>Outside a render, any <see cref="VideoBGPlayer"/> left on the video object is destroyed and the native player re-enabled.</para>
+    /// </summary>
+    /// <param name="__instance">The scene controller.</param>
+    /// <returns>True to run the original UpdateVideo; false when the mod handled the video (or there is none).</returns>
     [HarmonyPrefix]
     [HarmonyPatch("UpdateVideo")]
     // ReSharper disable once InconsistentNaming
@@ -109,7 +143,8 @@ public static class scnGamePatch
             return true; // Let the original print error
         }
 
-        // Disable native VideoPlayer component (to prevent it from attempting real-time playback and sync errors)
+        // Camera for the CameraFarPlane render mode: the VideoPlayer's target camera, or the "BGStaticCam" scene object
+        // when none is assigned.
         var targetCamera = __instance.videoBG.targetCamera;
         if (!targetCamera)
         {
@@ -120,6 +155,7 @@ public static class scnGamePatch
             }
         }
 
+        // Disable the native VideoPlayer so it does not play the video in real time alongside VideoBGPlayer.
         __instance.videoBG.enabled = false;
 
         // Add or retrieve our custom FFmpeg video background player