Fix cross-clock UI/sound artifacts at mixed speeds

Three composable mechanisms behind the remaining mixed-speed flicker
and re-firing notification sounds:

World-tick faction restore hardened: PreContext swaps every map onto
the spectator faction's data (resource counter, zone/area/designation
managers) and the restore was conditional on the popped context, with
SetFaction silently no-oping when a map lacks the faction's data. Any
leak left maps on spectator data, alternating with frames that ran a
world tick - which only happens at mixed speeds. Restore now falls back
to the local player faction (identical to a balanced pop), the skip
warns once per map/faction, and a log-only diagnostic reports residue
at UI time.

Sustainer/sample cross-clock lifetime: most sustainers have no map (the
constructor downgrades defs without world sub-sounds to OnCamera), so
their tick math ran under the viewed map's clock while Maintain()
stamped other clocks - a viewer clock ahead of the stamp ends and
respawns the sustainer every frame. Sound brackets now fall back to the
world clock for map-less sounds; a tolerant end-check re-stamps
tick-stale sustainers that were realtime-maintained within 1s (truly
abandoned ones still die, at most 1s late); the one-shot reaper runs
under the world clock so a paused viewer keeps reaping.

Frame-order and tween: Root_Play.Update runs RealTime/portraits/
UIRootUpdate before the frame's viewer clock was installed - install it
at frame start too; PawnTweener brackets carried pawns with MapHeld
instead of the null Map.

All render/audio/UI-side; no simulation-visible changes.

Author: CormacOConnor72

Source/Client/AsyncTime/AsyncWorldTimeComp.cs

@@ -237,7 +237,18 @@ public void PostContext()
     {
         if (Multiplayer.GameComp.multifaction)
         {
-            var f = FactionExtensions.PopFaction();
+            // Restore must be unconditional: PreContext swapped EVERY map onto
+            // the spectator faction's data (resourceCounter, zone/area/
+            // designation managers), and leaving any map on it corrupts every
+            // UI read until something else swaps it back (alternating only on
+            // frames that ran a world tick - a per-frame flicker/re-ping
+            // shape). A balanced pop returns the pre-world-tick OfPlayer,
+            // which is the client-local faction, so falling back to
+            // RealPlayerFaction on an unbalanced pop restores the same thing
+            // the balanced path would have. This is the faction half of the
+            // same PreContext/PostContext imbalance whose speed half caused
+            // the paused-map time-context bug.
+            var f = FactionExtensions.PopFaction() ?? Multiplayer.RealPlayerFaction;
             foreach (var map in Find.Maps)
                 map.MpComp().SetFaction(f);
         }

Source/Client/AsyncTime/SetMapTime.cs

@@ -139,7 +139,11 @@ static class PreDrawPosCalculationMapTime
         static void Prefix(PawnTweener __instance, ref TimeSnapshot? __state)
         {
             if (Multiplayer.Client == null || Current.ProgramState != ProgramState.Playing) return;
-            __state = TimeSnapshot.GetAndSetFromMap(__instance.pawn.Map);
+            // MapHeld, not Map: a carried/transported pawn has no map of its
+            // own, and with no install its tween ran under the viewer's clock
+            // (stamping lastDrawTick with it), then hard-snapped when a real
+            // clock returned. The holder's map clock is the motion's basis.
+            __state = TimeSnapshot.GetAndSetFromMap(__instance.pawn.MapHeld);
         }
 
         static void Postfix(TimeSnapshot? __state) => __state?.Set();
@@ -169,7 +173,16 @@ static IEnumerable<MethodBase> TargetMethods()
         static void Prefix(Sustainer __instance, ref TimeSnapshot? __state)
         {
             if (Multiplayer.game == null) return;
-            __state = TimeSnapshot.GetAndSetFromMap(__instance.info.Maker.Map);
+            // Most sustainers have no map: the Sustainer constructor
+            // downgrades any def without world sub-sounds to OnCamera, making
+            // Maker invalid. Falling through with no install left those
+            // running under the viewed map's clock while Maintain() stamps
+            // the maintainer's ambient tick - a cross-clock pair that ends
+            // (and respawns) the sustainer every frame when the viewer's
+            // clock is ahead. The world clock is the only session-wide
+            // monotone basis, so install it for map-less sound code.
+            __state = TimeSnapshot.GetAndSetFromMap(__instance.info.Maker.Map)
+                      ?? TimeSnapshot.GetAndSetFromWorld();
         }
 
         static void Postfix(TimeSnapshot? __state) => __state?.Set();
@@ -181,12 +194,36 @@ static class SampleUpdateMapTime
         static void Prefix(Sample __instance, ref TimeSnapshot? __state)
         {
             if (Multiplayer.game == null) return;
-            __state = TimeSnapshot.GetAndSetFromMap(__instance.Map);
+            // World-clock fallback for map-less samples - see
+            // SustainerUpdateMapTime above
+            __state = TimeSnapshot.GetAndSetFromMap(__instance.Map)
+                      ?? TimeSnapshot.GetAndSetFromWorld();
         }
 
         static void Postfix(TimeSnapshot? __state) => __state?.Set();
     }
 
+    // The one-shot reaper decides "finished" partly from Find.TickManager.Paused,
+    // which under the viewer install is the VIEWED map's pause state: a paused
+    // viewer never reaps finished tempo-affected one-shots, they accumulate, and
+    // the voice limiter then cuts/restarts sounds on every new play. The world
+    // clock pauses only when the whole session does, so reaping tracks actual
+    // sim activity. Per-sample Update calls nest their own map/world snapshots
+    // inside this bracket (SampleUpdateMapTime).
+    [HarmonyPatch(typeof(SampleOneShotManager), nameof(SampleOneShotManager.SampleOneShotManagerUpdate))]
+    static class OneShotReaperWorldTime
+    {
+        [HarmonyPriority(MpPriority.MpFirst)]
+        static void Prefix(ref TimeSnapshot? __state)
+        {
+            if (Multiplayer.game == null) return;
+            __state = TimeSnapshot.GetAndSetFromWorld();
+        }
+
+        [HarmonyPriority(MpPriority.MpLast)]
+        static void Finalizer(TimeSnapshot? __state) => __state?.Set();
+    }
+
     [HarmonyPatch(typeof(TipSignal), MethodType.Constructor, new[] { typeof(Func<string>), typeof(int) })]
     static class TipSignalCtor
     {

Source/Client/Comp/Map/MultiplayerMapComp.cs

@@ -5,6 +5,7 @@
 using Multiplayer.Client.Factions;
 using Multiplayer.Client.Persistent;
 using Multiplayer.Client.Saving;
+using Multiplayer.Client.Util;
 using Multiplayer.Common;
 using RimWorld;
 using RimWorld.Planet;
@@ -121,10 +122,22 @@ public void DoTick()
             }
         }
 
+        private static readonly HashSet<long> warnedMissingFactionData = new();
+
         public void SetFaction(Faction faction)
         {
             if (!factionData.TryGetValue(faction.loadID, out FactionMapData data))
+            {
+                // Skipping the swap leaves the map on whatever faction's data
+                // is currently installed - if that was a transient context
+                // (e.g. the world tick's spectator swap), the map stays wrong
+                // until the next successful SetFaction. Never fail this
+                // silently: name the map and faction once so a leak is
+                // attributable.
+                if (warnedMissingFactionData.Add(((long)map.uniqueID << 32) | (uint)faction.loadID))
+                    MpLog.Warn($"SetFaction skipped: map {map.uniqueID} has no FactionMapData for faction {faction.loadID} ({faction.Name}) - map keeps the previously installed faction data");
                 return;
+            }
 
             map.designationManager = data.designationManager;
             map.areaManager = data.areaManager;

Source/Client/Patches/FactionResidueDiag.cs

@@ -0,0 +1,53 @@
+using HarmonyLib;
+using Multiplayer.Client.Util;
+using RimWorld;
+using UnityEngine;
+using Verse;
+
+namespace Multiplayer.Client.Patches
+{
+    // Diagnostic only. The world tick swaps every map onto the spectator
+    // faction's data and restores afterwards; if any path leaves a map on the
+    // wrong faction's managers, UI reads (resource readout, zones, areas,
+    // low-food alert nutrition) alternate between factions' data on frames
+    // that ran a world tick - a flicker/re-ping shape that only exists at
+    // mixed speeds. The restore is hardened now, but this check catches ANY
+    // residue source red-handed at UI time, named and counted. Log-only.
+    [HarmonyPatch(typeof(UIRoot_Play), nameof(UIRoot_Play.UIRootUpdate))]
+    static class FactionResidueDiag
+    {
+        private static int residueFrames;
+        private static float lastReport;
+        private const float ReportIntervalSeconds = 60f;
+
+        static void Postfix()
+        {
+            if (Multiplayer.Client == null || !Multiplayer.GameComp.multifaction) return;
+
+            var map = Find.CurrentMap;
+            var realFaction = Multiplayer.RealPlayerFaction;
+            if (map == null || realFaction == null) return;
+
+            var comp = map.MpComp();
+            if (comp == null || !comp.factionData.TryGetValue(realFaction.loadID, out var ownData)) return;
+
+            if (ReferenceEquals(map.resourceCounter, ownData.resourceCounter)) return;
+
+            residueFrames++;
+            var now = Time.realtimeSinceStartup;
+            if (now - lastReport < ReportIntervalSeconds) return;
+            lastReport = now;
+
+            var installedFactionId = -1;
+            foreach (var kv in comp.factionData)
+                if (ReferenceEquals(map.resourceCounter, kv.Value.resourceCounter))
+                    installedFactionId = kv.Key;
+
+            MpLog.Warn(
+                $"Faction residue: map {map.uniqueID} has faction {installedFactionId}'s data installed at UI time " +
+                $"(local faction {realFaction.loadID}, OfPlayer {Faction.OfPlayer?.loadID}); " +
+                $"{residueFrames} affected frames since last report");
+            residueFrames = 0;
+        }
+    }
+}

Source/Client/Patches/SustainerClockPatches.cs

@@ -0,0 +1,105 @@
+using System.Collections.Generic;
+using HarmonyLib;
+using Multiplayer.Client.Util;
+using UnityEngine;
+using Verse;
+using Verse.Sound;
+
+namespace Multiplayer.Client.Patches
+{
+    // Sustainers with PerTick/PerTickRare maintenance compare an ambient tick
+    // against lastMaintainTick, but under per-map clocks the stamp and the
+    // check can come from different clocks: Maintain() runs under whatever
+    // context the maintainer had (often a map's tick loop), while
+    // SustainerUpdate runs under the sound bracket's clock (owner map, or the
+    // world clock for map-less sustainers). A stamp clock behind the check
+    // clock reads as "unmaintained" and ends the sustainer even though its
+    // owner maintained it microseconds ago - and owners respawn ended
+    // sustainers, so the sound restarts every frame.
+    //
+    // Fix: before the vanilla staleness check runs, if the sustainer LOOKS
+    // tick-stale but was really maintained within the grace window (measured
+    // in realtime, which no clock swap can touch), re-stamp it under the
+    // clock the check will use. Truly abandoned sustainers still die, at most
+    // GraceSeconds late - audio-only, imperceptible. PerFrame maintenance is
+    // untouched (frame counts are global). Vanilla paused behavior is
+    // untouched (a frozen clock never reads as stale).
+    public static class SustainerRealtimeMaintenance
+    {
+        public static readonly Dictionary<Sustainer, float> lastMaintainRealTime = new();
+
+        public const float GraceSeconds = 1f;
+
+        private static float lastRescueReport;
+        private static int rescueCount;
+
+        public static void NoteRescue(Sustainer sustainer, int ambientTicks, int staleStamp)
+        {
+            rescueCount++;
+            var now = Time.realtimeSinceStartup;
+            if (now - lastRescueReport < 60f) return;
+            lastRescueReport = now;
+            MpLog.Debug($"Sustainer cross-clock rescue: {sustainer.def} ambient={ambientTicks} stamp={staleStamp} ({rescueCount} rescues since last report)");
+            rescueCount = 0;
+        }
+    }
+
+    [HarmonyPatch(typeof(Sustainer), MethodType.Constructor, typeof(SoundDef), typeof(SoundInfo))]
+    static class SustainerCtorRealtimeStamp
+    {
+        static void Postfix(Sustainer __instance)
+        {
+            if (Multiplayer.Client == null) return;
+            SustainerRealtimeMaintenance.lastMaintainRealTime[__instance] = Time.realtimeSinceStartup;
+        }
+    }
+
+    [HarmonyPatch(typeof(Sustainer), nameof(Sustainer.Maintain))]
+    static class SustainerMaintainRealtimeStamp
+    {
+        static void Postfix(Sustainer __instance)
+        {
+            if (Multiplayer.Client == null) return;
+            SustainerRealtimeMaintenance.lastMaintainRealTime[__instance] = Time.realtimeSinceStartup;
+        }
+    }
+
+    [HarmonyPatch(typeof(Sustainer), nameof(Sustainer.End))]
+    static class SustainerEndCleanup
+    {
+        static void Postfix(Sustainer __instance)
+            => SustainerRealtimeMaintenance.lastMaintainRealTime.Remove(__instance);
+    }
+
+    [HarmonyPatch(typeof(Sustainer), nameof(Sustainer.SustainerUpdate))]
+    static class SustainerTolerantEndCheck
+    {
+        // Runs after SustainerUpdateMapTime's prefix so the re-stamp uses the
+        // same clock the vanilla staleness check is about to read
+        [HarmonyPriority(Priority.Low)]
+        static void Prefix(Sustainer __instance)
+        {
+            if (Multiplayer.Client == null || __instance.Ended) return;
+
+            var maintenance = __instance.info.Maintenance;
+            int staleAfter;
+            if (maintenance == MaintenanceType.PerTick)
+                staleAfter = 1;
+            else if (maintenance == MaintenanceType.PerTickRare)
+                staleAfter = 250;
+            else
+                return;
+
+            var ambientTicks = Find.TickManager.TicksGame;
+            if (ambientTicks <= __instance.lastMaintainTick + staleAfter)
+                return; // not stale, vanilla keeps it
+
+            if (!SustainerRealtimeMaintenance.lastMaintainRealTime.TryGetValue(__instance, out var maintainedAt) ||
+                Time.realtimeSinceStartup - maintainedAt > SustainerRealtimeMaintenance.GraceSeconds)
+                return; // truly abandoned, let vanilla end it
+
+            SustainerRealtimeMaintenance.NoteRescue(__instance, ambientTicks, __instance.lastMaintainTick);
+            __instance.lastMaintainTick = ambientTicks;
+        }
+    }
+}

Source/Client/Patches/TickPatch.cs

@@ -198,7 +198,7 @@ static void Postfix()
         // and every sim path installs its own context on entry (the world
         // tick installs its own count), so this value is never a simulation
         // input.
-        private static void InstallViewerTimeContext()
+        internal static void InstallViewerTimeContext()
         {
             // Null checks cover the join/load window where Multiplayer.game
             // (and with it the async comps) lags Multiplayer.Client
@@ -371,6 +371,23 @@ public static void Reset()
         public static ITickable TickableById(int tickableId) => AllTickables.FirstOrDefault(t => t.TickableId == tickableId);
     }
 
+    // Root_Play.Update runs RealTime.Update, PortraitsCache and UIRootUpdate
+    // BEFORE TickManagerUpdate, where the frame's viewer context is normally
+    // installed - so those consumers read the PREVIOUS frame's residual
+    // ambient (e.g. unpausedTime advances by a stale TickRateMultiplier,
+    // making pausable-animated materials move in bursts). Install the viewer
+    // context at the top of the frame too; the sim still installs its own
+    // contexts on entry, so this is render/UI-only like the post-tick install.
+    [HarmonyPatch(typeof(Root_Play), nameof(Root_Play.Update))]
+    static class FrameStartViewerContext
+    {
+        static void Prefix()
+        {
+            if (Multiplayer.Client == null) return;
+            TickPatch.InstallViewerTimeContext();
+        }
+    }
+
     public class SimulatingData
     {
         public int? target;