Docs: reduce over-documentation across gameplay scripts

Trim restated narration, dead commented-out code, and oversized class
headers; keep all why-comments (authority, timing, edge cases), tooltips,
and serialization caveats.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Assets/Scripts/PaintHud.cs

@@ -8,21 +8,13 @@ using UnityEngine.InputSystem.UI;
 
 /// <summary>
 /// In-game paint UI. Shows its panels only while the active <see cref="GameMode"/> is
-/// <see cref="PaintMode"/> (it follows the manager's ModeChanged event) and binds its
-/// widgets directly to the live <see cref="MeshPainter"/> fields, so edits apply immediately.
+/// <see cref="PaintMode"/> (follows the manager's ModeChanged) and binds its widgets directly to the
+/// live <see cref="MeshPainter"/> fields, so edits apply immediately.
 ///
-/// The layout is a transparent root holding one independently positioned sub-panel per channel
-/// (Albedo, Metallic+Smoothness, Occlusion, Emission) plus a global Brush card, each with a title
-/// bar and draggable from any of its non-widget surface. The layout comes from one of two sources:
-///  - an authored prefab assigned to <see cref="layoutPrefab"/> (instantiated, then bound), or
-///  - generated in code (the fallback when no prefab is set).
-/// Either way the *bindings* (listeners, picker gradient sprites, painter values) live in code
-/// and are (re)applied at runtime by <see cref="WirePanel"/>. A prefab stores only the visual
-/// layout, never the behaviour, so both paths run the exact same wiring against the same stable
-/// widget names - there is no separate "dead" prefab path.
-///
-/// Widgets: channel toggles, an HSV colour picker for albedo, metallic / smoothness / occlusion
-/// sliders, an HSV picker + intensity for emission, and brush size. Attach to an empty GameObject.
+/// The layout (independently draggable sub-panels per channel + a global brush card) comes from an
+/// authored prefab (<see cref="layoutPrefab"/>) or is generated in code as the fallback. Either way
+/// the BINDINGS live in code and are (re)applied at runtime by <see cref="WirePanel"/> against the
+/// same stable widget names - a prefab stores only the visual layout, never behaviour.
 /// </summary>
 [DisallowMultipleComponent]
 public partial class PaintHud : MonoBehaviour
@@ -137,10 +129,8 @@ public partial class PaintHud : MonoBehaviour
         // The paint library now lives inside the authored layout prefab; bind its widgets like the brush panel.
         BindLibrary(_panel ? _panel.transform : null);
 
-        // Bind to a painter as soon as one exists. With networked spawn-on-connect there is none
-        // at scene start; BindLocalPlayer then raises PainterChanged when the local avatar spawns
-        // and OnPainterChanged wires the widgets. In a non-networked scene the painter is already
-        // present and binds here immediately.
+        // Bind as soon as a painter exists. With networked spawn-on-connect there is none at scene
+        // start; PainterChanged then wires the widgets once the local avatar spawns.
         var p = painter;
         if (!p) p = modeManager ? modeManager.Painter : null;
         if (!p) p = FindFirstObjectByType<MeshPainter>();
@@ -180,14 +170,12 @@ public partial class PaintHud : MonoBehaviour
         // Re-sync the brush-size slider when Shift+wheel resizes the brush in-world (painter -> HUD).
         painter.BrushSizeChanged += SyncBrushSize;
 
-        // Snapshot the painter's prefab-default brush values before carry/restore mutate them; the reset
-        // button returns to exactly these. Once per HUD (a freshly spawned respawn painter holds the same
-        // prefab defaults, so re-capturing would be redundant).
+        // Snapshot the prefab-default brush values before carry/restore mutate them (the reset button
+        // returns to exactly these). Once per HUD.
         CaptureDefaults();
 
-        // First bind this session: restore panel positions + brush values from disk (cross-session).
-        // A later bind is an avatar respawn (scene switch) -> carry the in-session brush values onto the
-        // fresh painter instead, so they are not reset to its prefab defaults.
+        // First bind this session: restore from disk. A later bind is an avatar respawn -> carry the
+        // in-session values onto the fresh painter instead.
         if (_hasCarry) ApplyCarry();
         else RestoreHudState();
         CaptureCarry(); // seed/refresh the mirror from the now-current painter
@@ -207,9 +195,8 @@ public partial class PaintHud : MonoBehaviour
 
     private void OnModeChanged(GameMode mode)
     {
-        // Require a bound painter too: pre-spawn the manager sits in a player-less Paint mode (no
-        // PlayerControl without an avatar), but there is nothing to paint yet - keep the HUD hidden until
-        // the local avatar spawns and a painter is bound.
+        // Require a bound painter too: pre-spawn the manager sits in a player-less Paint mode, but there
+        // is nothing to paint yet - keep the HUD hidden until a painter is bound.
         bool paint = mode is PaintMode && painter;
         if (_panel) _panel.SetActive(paint); // toggles the brush panels and the library panel together
         if (paint)
@@ -270,7 +257,6 @@ public partial class PaintHud : MonoBehaviour
         WireToggle(panel, ToggleSpray, painter && painter.spray, v => { if (painter) painter.spray = v; });
         WireToggle(panel, TogglePipette, painter && painter.pipette, v => { if (painter) painter.pipette = v; });
 
-        // Dim a channel panel to 0.5 alpha while its toggle is off, full alpha while on.
         WirePanelFade(panel, PanelAlbedo, ToggleAlbedo);
         WirePanelFade(panel, PanelMetallicSmoothness, ToggleMetallicSmoothness);
         WirePanelFade(panel, PanelOcclusion, ToggleOcclusion);
@@ -305,16 +291,13 @@ public partial class PaintHud : MonoBehaviour
         WireSlider(panel, SliderSprayDotAlphaMin, painter ? painter.sprayDotAlphaMin : .2f, v => { if (painter) painter.sprayDotAlphaMin = v; });
         WireSlider(panel, SliderSprayDotAlphaMax, painter ? painter.sprayDotAlphaMax : .6f, v => { if (painter) painter.sprayDotAlphaMax = v; });
 
-        // Camouflage knobs on the player's PlayerCamoLit material instance (material-backed, not painter
-        // fields). The values are not readable here yet - the HUD binds in the avatar's OnNetworkSpawn,
-        // which runs before the painter's Start builds the instance - so SyncCamoSliders re-seeds them
-        // once the painter reports IsReady (see LateUpdate). Setting a slider before then is a safe no-op.
+        // Camo knobs are material-backed and not readable yet (the HUD binds before the painter's Start);
+        // SyncCamoSliders re-seeds them once IsReady. Setting a slider before then is a safe no-op.
         WireSlider(panel, SliderHalfLambert, painter ? painter.CamoHalfLambert : 0f, v => { if (painter) painter.CamoHalfLambert = v; });
         WireSlider(panel, SliderHalfLambertBrightness, painter ? painter.CamoHalfLambertBrightness : 0f, v => { if (painter) painter.CamoHalfLambertBrightness = v; });
         WireSlider(panel, SliderSpecularDamp, painter ? painter.CamoSpecularDampen : 0f, v => { if (painter) painter.CamoSpecularDampen = v; });
 
-        // Painted-height knobs: material-backed like the camo sliders above, so they are seeded once the
-        // painter is ready (SyncCamoSliders) and a set before then is a safe no-op.
+        // Painted-height knobs: material-backed like the camo sliders above.
         WireSlider(panel, SliderOcclusionThreshold, painter ? painter.OcclusionThreshold : 0.2f, v => { if (painter) painter.OcclusionThreshold = v; });
         WireSlider(panel, SliderNormalIntensity, painter ? painter.HeightNormalIntensity : 1.4f, v => { if (painter) painter.HeightNormalIntensity = v; });
         WireSlider(panel, SliderParallaxIntensity, painter ? painter.ParallaxIntensity : 1f, v => { if (painter) painter.ParallaxIntensity = v; });
@@ -375,11 +358,9 @@ public partial class PaintHud : MonoBehaviour
     }
 
     /// <summary>
-    /// Seeds the camouflage sliders from the player's live PlayerCamoLit material (painter -> HUD). The
-    /// values live on the material instance the painter builds in its Start, but the HUD binds earlier
-    /// (the avatar's OnNetworkSpawn fires before Start), so they are not readable at WirePanel time. This
-    /// runs once the painter reports <see cref="MeshPainter.IsReady"/> (see LateUpdate) so the sliders
-    /// show the material's authored values instead of the placeholder 0 from the bind-time read.
+    /// Seeds the camo + height sliders from the live material (painter -> HUD). The HUD binds before the
+    /// painter's Start builds the instance, so the values are not readable at WirePanel time; this runs
+    /// once the painter reports <see cref="MeshPainter.IsReady"/> (see LateUpdate).
     /// </summary>
     private void SyncCamoSliders()
     {
@@ -416,9 +397,7 @@ public partial class PaintHud : MonoBehaviour
         if (picker) picker.SetColor(color);
     }
 
-    // Albedo/emission colour is split across two widgets: the picker drives RGB (keeping the painter's
-    // current alpha), the standalone alpha slider drives alpha (keeping RGB). Kept independent so neither
-    // widget's edit clobbers the other's channel.
+    // Split colour editing: the picker drives RGB, the alpha slider drives alpha - neither clobbers the other.
     private static Color WithRgb(Color current, Color rgb) => new Color(rgb.r, rgb.g, rgb.b, current.a);
     private static Color WithAlpha(Color current, float a) => new Color(current.r, current.g, current.b, a);