Camo: generalize brightness + add persistent saturation

Move brightness out of the half-lambert diffuse term to a final exposure
multiply on the whole shaded body color (diffuse + GI + specular), and add
a saturation grade (0 = neutral, -1 = grayscale, >0 = boosted) on the same
final stage. Saturation rides as a 4th component on CamoKnobs (Vector3 ->
Vector4) so it inherits all three persistence paths: HUD JSON, network
replication (_camo NetworkVariable), and painting-slot metadata. Wires the
renamed Slider_Brightness and new Slider_Saturation. Bumps HudFileVersion
and PaintMetaVersion with load-time remaps so existing paintings keep their
look (old 1=neutral saturation remaps to 0=neutral).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Assets/Scripts/Components/MeshPainter/MeshPainter.Persistence.cs

@@ -30,7 +30,8 @@ public partial class MeshPainter
     // is), so saves without a fur.png load fine - the fur map stays seeded (bald). NOTE: the fur.png layout
     // changed to R = length (was RGB colour + A length); pre-change fur.png files load stale length data and
     // should be repainted.
-    private const int PaintMetaVersion = 6;
+    // v8: camoSaturation semantics changed to an offset (0 = neutral, -1 = greyscale; was 1 = neutral in v7).
+    private const int PaintMetaVersion = 8;
 
     private const string MetaFileName = "painting.json";
     private const string AlbedoFileName = "albedo.png";
@@ -57,6 +58,7 @@ public partial class MeshPainter
         public float camoHalfLambert;
         public float camoHalfLambertBrightness;
         public float camoSpecularDampen;
+        public float camoSaturation; // v7+; remapped on load per meta.version (semantics changed in v8)
         public float occlusionThreshold;
         public float heightNormalIntensity;
         public float parallaxIntensity;
@@ -149,6 +151,7 @@ public partial class MeshPainter
                 camoHalfLambert = CamoHalfLambert,
                 camoHalfLambertBrightness = CamoHalfLambertBrightness,
                 camoSpecularDampen = CamoSpecularDampen,
+                camoSaturation = CamoSaturation,
                 occlusionThreshold = OcclusionThreshold,
                 heightNormalIntensity = HeightNormalIntensity,
                 parallaxIntensity = ParallaxIntensity,
@@ -200,6 +203,12 @@ public partial class MeshPainter
             CamoHalfLambert = meta.camoHalfLambert;
             CamoHalfLambertBrightness = meta.camoHalfLambertBrightness;
             CamoSpecularDampen = meta.camoSpecularDampen;
+            // Saturation semantics changed in v8 (0 = neutral, -1 = greyscale; was 1 = neutral in v7).
+            // v7 stored the old scheme -> shift by -1 to preserve its look. Pre-v7 has no field (deserializes
+            // to 0), which is already neutral under the new scheme.
+            CamoSaturation = meta.version >= 8 ? meta.camoSaturation
+                           : meta.version == 7 ? meta.camoSaturation - 1f
+                           : 0f;
             OcclusionThreshold = meta.occlusionThreshold;
             HeightNormalIntensity = meta.heightNormalIntensity;
             ParallaxIntensity = meta.parallaxIntensity;

Assets/Scripts/Components/MeshPainter/MeshPainter.cs

@@ -78,6 +78,16 @@ public partial class MeshPainter : MonoBehaviour
         set => SetMatFloat(SpecularDampenId, value);
     }
 
+    /// <summary>General colour saturation of the shaded body (0 = neutral, -1 = greyscale, &gt;0 = punchier).
+    /// A camo body-tone knob alongside <see cref="CamoHalfLambertBrightness"/>; drives the material's
+    /// <c>_Saturation</c> (offset: shader lerps to grey by 1 + value). Persisted + replicated with the
+    /// other camo knobs (see <see cref="CamoKnobs"/>).</summary>
+    public float CamoSaturation
+    {
+        get => GetMatFloat(SaturationId, 0f);
+        set => SetMatFloat(SaturationId, value);
+    }
+
     // Painted-height look knobs on the same material instance, surfaced/guarded/persisted/replicated
     // like the camo knobs above. Defaults match the shader so the unpainted look is unchanged.
 
@@ -104,11 +114,12 @@ public partial class MeshPainter : MonoBehaviour
         set => SetMatFloat(ParallaxId, Mathf.Max(0f, value) * ParallaxBase);
     }
 
-    /// <summary>The three camo knobs as one vector (x = half-Lambert, y = its brightness, z = specular dampen).</summary>
-    public Vector3 CamoKnobs
+    /// <summary>The four camo knobs as one vector (x = half-Lambert, y = brightness, z = specular dampen,
+    /// w = saturation) - one payload for persistence + network replication.</summary>
+    public Vector4 CamoKnobs
     {
-        get => new(CamoHalfLambert, CamoHalfLambertBrightness, CamoSpecularDampen);
-        set { CamoHalfLambert = value.x; CamoHalfLambertBrightness = value.y; CamoSpecularDampen = value.z; }
+        get => new(CamoHalfLambert, CamoHalfLambertBrightness, CamoSpecularDampen, CamoSaturation);
+        set { CamoHalfLambert = value.x; CamoHalfLambertBrightness = value.y; CamoSpecularDampen = value.z; CamoSaturation = value.w; }
     }
 
     /// <summary>The three painted-height knobs as one vector (x = occlusion threshold, y = relief normal intensity, z = parallax intensity).</summary>
@@ -454,6 +465,7 @@ public partial class MeshPainter : MonoBehaviour
     private const float ParallaxBase = 0.02f;
     private static readonly int HalfLambertId = Shader.PropertyToID("_HalfLambert");
     private static readonly int HalfLambertBrightnessId = Shader.PropertyToID("_HalfLambertBrightness");
+    private static readonly int SaturationId = Shader.PropertyToID("_Saturation");
     private static readonly int SpecularDampenId = Shader.PropertyToID("_SpecularDampen");
     private static readonly int XRayColorId = Shader.PropertyToID("_XRayColor");
     private static readonly int XRayPulseSpeedId = Shader.PropertyToID("_XRayPulseSpeed");

Assets/Scripts/Components/UI/PaintHud/PaintHud.Persistence.cs

@@ -20,9 +20,11 @@ public partial class PaintHud
              "defaults every session.")]
     public bool persistHud = true;
 
-    // v2: HudValues gained fur (toggle) + furLength. Bumping discards pre-v2 saves so the new fur fields
-    // fall back to the painter's prefab defaults instead of deserializing as 0/false.
-    private const int HudFileVersion = 2;
+    // v2: HudValues gained fur (toggle) + furLength. v3: gained camoSaturation. v4: camoSaturation
+    // semantics changed to an offset (0 = neutral, was 1). Bumping discards older saves so the fields
+    // fall back to the painter's prefab/material defaults instead of stale/old-scheme values (a v3 save
+    // stored saturation 1 = old-neutral, which would read as punchier now).
+    private const int HudFileVersion = 4;
 
     // Auto-save bookkeeping. Brush edits are debounced (sliders fire every frame while dragged): the due
     // time is pushed forward and written once they settle.
@@ -41,7 +43,7 @@ public partial class PaintHud
     // Camo knobs live on the material instance, which only exists after the painter's Start: a restored
     // (disk) or carried (respawn) value waits here and is applied in the LateUpdate ready-gate.
     // _camoEverReady gates carry/save so the not-yet-ready 0 never overwrites the authored value.
-    private Vector3 _pendingCamo;
+    private Vector4 _pendingCamo; // (x,y,z,w) = CamoKnobs (halfLambert, brightness, specularDampen, saturation)
     private bool _hasPendingCamo;
     private bool _camoEverReady;
 
@@ -95,7 +97,7 @@ public partial class PaintHud
         public int activeBrushIndex;
         public int sprayDots;
         public float sprayDotSizeMin, sprayDotSizeMax, sprayDotAlphaMin, sprayDotAlphaMax;
-        public float camoHalfLambert, camoHalfLambertBrightness, camoSpecularDampen; // PlayerCamoLit material knobs
+        public float camoHalfLambert, camoHalfLambertBrightness, camoSpecularDampen, camoSaturation; // PlayerCamoLit material knobs
         public float occlusionThreshold, heightNormalIntensity, parallaxIntensity;   // painted-height knobs (material-backed)
     }
 
@@ -170,9 +172,10 @@ public partial class PaintHud
         // save files (applying their 0 would clobber the authored camo).
         if (state.hasCamoValues && state.values != null)
         {
-            _pendingCamo = new Vector3(state.values.camoHalfLambert,
+            _pendingCamo = new Vector4(state.values.camoHalfLambert,
                                        state.values.camoHalfLambertBrightness,
-                                       state.values.camoSpecularDampen);
+                                       state.values.camoSpecularDampen,
+                                       state.values.camoSaturation);
             _hasPendingCamo = true;
         }
 
@@ -228,6 +231,7 @@ public partial class PaintHud
                 _savedValues.camoHalfLambert = _lastSeenValues.camoHalfLambert = painter.CamoHalfLambert;
                 _savedValues.camoHalfLambertBrightness = _lastSeenValues.camoHalfLambertBrightness = painter.CamoHalfLambertBrightness;
                 _savedValues.camoSpecularDampen = _lastSeenValues.camoSpecularDampen = painter.CamoSpecularDampen;
+                _savedValues.camoSaturation = _lastSeenValues.camoSaturation = painter.CamoSaturation;
                 _savedValues.occlusionThreshold = _lastSeenValues.occlusionThreshold = painter.OcclusionThreshold;
                 _savedValues.heightNormalIntensity = _lastSeenValues.heightNormalIntensity = painter.HeightNormalIntensity;
                 _savedValues.parallaxIntensity = _lastSeenValues.parallaxIntensity = painter.ParallaxIntensity;
@@ -298,6 +302,7 @@ public partial class PaintHud
             && p.CamoHalfLambert == v.camoHalfLambert
             && p.CamoHalfLambertBrightness == v.camoHalfLambertBrightness
             && p.CamoSpecularDampen == v.camoSpecularDampen
+            && p.CamoSaturation == v.camoSaturation
             && p.OcclusionThreshold == v.occlusionThreshold
             && p.HeightNormalIntensity == v.heightNormalIntensity
             && p.ParallaxIntensity == v.parallaxIntensity;
@@ -322,9 +327,10 @@ public partial class PaintHud
         // by _camoEverReady so a carry taken before any material was ready can't apply a stale 0.
         if (_camoEverReady)
         {
-            _pendingCamo = new Vector3(_carry.camoHalfLambert,
+            _pendingCamo = new Vector4(_carry.camoHalfLambert,
                                        _carry.camoHalfLambertBrightness,
-                                       _carry.camoSpecularDampen);
+                                       _carry.camoSpecularDampen,
+                                       _carry.camoSaturation);
             _hasPendingCamo = true;
             _pendingHeight = new Vector3(_carry.occlusionThreshold,
                                          _carry.heightNormalIntensity,
@@ -365,6 +371,7 @@ public partial class PaintHud
             v.camoHalfLambert = from.CamoHalfLambert;
             v.camoHalfLambertBrightness = from.CamoHalfLambertBrightness;
             v.camoSpecularDampen = from.CamoSpecularDampen;
+            v.camoSaturation = from.CamoSaturation;
             v.occlusionThreshold = from.OcclusionThreshold;
             v.heightNormalIntensity = from.HeightNormalIntensity;
             v.parallaxIntensity = from.ParallaxIntensity;
@@ -401,6 +408,7 @@ public partial class PaintHud
         to.CamoHalfLambert = v.camoHalfLambert;
         to.CamoHalfLambertBrightness = v.camoHalfLambertBrightness;
         to.CamoSpecularDampen = v.camoSpecularDampen;
+        to.CamoSaturation = v.camoSaturation;
         to.OcclusionThreshold = v.occlusionThreshold;
         to.HeightNormalIntensity = v.heightNormalIntensity;
         to.ParallaxIntensity = v.parallaxIntensity;
@@ -459,6 +467,7 @@ public partial class PaintHud
         _defaults.camoHalfLambert = painter.CamoHalfLambert;
         _defaults.camoHalfLambertBrightness = painter.CamoHalfLambertBrightness;
         _defaults.camoSpecularDampen = painter.CamoSpecularDampen;
+        _defaults.camoSaturation = painter.CamoSaturation;
         _defaults.occlusionThreshold = painter.OcclusionThreshold;
         _defaults.heightNormalIntensity = painter.HeightNormalIntensity;
         _defaults.parallaxIntensity = painter.ParallaxIntensity;

Assets/Scripts/Components/UI/PaintHud/PaintHud.cs

@@ -59,7 +59,8 @@ public partial class PaintHud : MonoBehaviour
     private const string SliderSprayDotAlphaMin = "Slider_SprayDotAlphaMin";
     private const string SliderSprayDotAlphaMax = "Slider_SprayDotAlphaMax";
     private const string SliderHalfLambert = "Slider_HalfLambert";
-    private const string SliderHalfLambertBrightness = "Slider_HalfLambertBrightness";
+    private const string SliderBrightness = "Slider_Brightness";
+    private const string SliderSaturation = "Slider_Saturation";
     private const string SliderSpecularDamp = "Slider_SpecularDamp";
     private const string SliderOcclusionThreshold = "Slider_OcclusionThreshold";
     private const string SliderNormalIntensity = "Slider_NormalIntensity";
@@ -253,7 +254,8 @@ public partial class PaintHud : MonoBehaviour
         // 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, SliderBrightness, painter ? painter.CamoHalfLambertBrightness : 0f, v => { if (painter) painter.CamoHalfLambertBrightness = v; });
+        WireSlider(panel, SliderSaturation, painter ? painter.CamoSaturation : 0f, v => { if (painter) painter.CamoSaturation = v; });
         WireSlider(panel, SliderSpecularDamp, painter ? painter.CamoSpecularDampen : 0f, v => { if (painter) painter.CamoSpecularDampen = v; });
 
         // Painted-height knobs: material-backed like the camo sliders above.
@@ -333,7 +335,8 @@ public partial class PaintHud : MonoBehaviour
         if (!_panel || !painter) return;
         var panel = _panel.transform;
         SetSlider(panel, SliderHalfLambert, painter.CamoHalfLambert);
-        SetSlider(panel, SliderHalfLambertBrightness, painter.CamoHalfLambertBrightness);
+        SetSlider(panel, SliderBrightness, painter.CamoHalfLambertBrightness);
+        SetSlider(panel, SliderSaturation, painter.CamoSaturation);
         SetSlider(panel, SliderSpecularDamp, painter.CamoSpecularDampen);
         // Painted-height knobs share the same material-ready timing as the camo sliders.
         SetSlider(panel, SliderOcclusionThreshold, painter.OcclusionThreshold);