Merge pull request #277 from ifBars/agent/fix-275-client-npc-contacts

fix(npc): finalize custom NPCs on multiplayer clients

Author: ifBars

S1API.Tests/Entities/CustomNpcReadinessPolicyTests.cs

@@ -0,0 +1,88 @@
+using S1API.Entities;
+using S1API.Internal.Entities;
+using S1API.Internal.Patches;
+
+namespace S1API.Tests.Entities;
+
+public sealed class CustomNpcReadinessPolicyTests
+{
+    [Fact]
+    public void ClientHydrationSignalsReadyOnlyAfterEveryCustomNpcTypeCompletes()
+    {
+        NPC.FinalizedCustomNpcTypes.Clear();
+        NPCPatches.CustomNpcsReady = false;
+
+        try
+        {
+            var dealer = TestObjectFactory.CreateUninitialized<DealerNpc>();
+            var customer = TestObjectFactory.CreateUninitialized<CustomerNpc>();
+
+            dealer.CreateFromClientNetworkSpawn();
+
+            Assert.False(NPC.CustomNpcsReady);
+
+            customer.CreateFromClientNetworkSpawn();
+
+            Assert.True(NPC.CustomNpcsReady);
+        }
+        finally
+        {
+            NPC.FinalizedCustomNpcTypes.Clear();
+            NPCPatches.CustomNpcsReady = false;
+        }
+    }
+
+    [Fact]
+    public void ClientRemainsNotReadyWhileARegisteredTypeIsMissing()
+    {
+        Type[] registeredTypes = { typeof(DealerNpc), typeof(CustomerNpc) };
+        HashSet<Type> finalizedTypes = new() { typeof(DealerNpc) };
+
+        bool ready = CustomNpcReadinessPolicy.AreAllTypesFinalized(
+            registeredTypes,
+            finalizedTypes);
+
+        Assert.False(ready);
+    }
+
+    [Fact]
+    public void ClientBecomesReadyAfterEveryRegisteredTypeIsHydrated()
+    {
+        Type[] registeredTypes = { typeof(DealerNpc), typeof(CustomerNpc) };
+        HashSet<Type> finalizedTypes = new() { typeof(DealerNpc) };
+
+        CustomNpcReadinessPolicy.MarkFinalized(
+            typeof(CustomerNpc),
+            finalizedTypes);
+
+        bool ready = CustomNpcReadinessPolicy.AreAllTypesFinalized(
+            registeredTypes,
+            finalizedTypes);
+
+        Assert.True(ready);
+    }
+
+    [Fact]
+    public void NoRegisteredTypesDoesNotSignalReady()
+    {
+        bool ready = CustomNpcReadinessPolicy.AreAllTypesFinalized(
+            Array.Empty<Type>(),
+            new HashSet<Type>());
+
+        Assert.False(ready);
+    }
+
+    private sealed class DealerNpc : NPC
+    {
+        internal override void CreateInternal()
+        {
+        }
+    }
+
+    private sealed class CustomerNpc : NPC
+    {
+        internal override void CreateInternal()
+        {
+        }
+    }
+}

S1API/Entities/NPC.cs

@@ -3489,6 +3489,8 @@ internal void CreateFromClientNetworkSpawn()
             {
                 _clientNetworkSpawnHydrationDepth--;
             }
+
+            MarkCustomNpcFinalized();
         }
 
         internal override void SaveInternal(string folderPath, ref List<string> extraSaveables)
@@ -4659,9 +4661,7 @@ internal void FinalizeNetworkSpawn()
 
                 // Check if all custom NPCs are now ready (finalized)
                 // This sets the CustomNpcsReady flag once all custom NPCs have been spawned and finalized
-                FinalizedCustomNpcTypes.Add(GetType());
-                ReconcileAllCustomNpcRelationshipConnections();
-                CheckAndSetCustomNpcsReady();
+                MarkCustomNpcFinalized();
             }
             catch (Exception ex)
             {
@@ -4671,7 +4671,7 @@ internal void FinalizeNetworkSpawn()
 
         /// <summary>
         /// Checks if all custom NPCs have been finalized and sets the CustomNpcsReady flag.
-        /// This is called from FinalizeNetworkSpawn to signal when all custom NPCs are ready.
+        /// Called after server finalization and client network-spawn hydration.
         /// </summary>
         internal static void CheckAndSetCustomNpcsReady()
         {
@@ -4689,8 +4689,8 @@ internal static void CheckAndSetCustomNpcsReady()
                 if (customNpcTypes.Count == 0)
                     return;
 
-                bool allTypesFinalized = customNpcTypes.All(
-                    type => FinalizedCustomNpcTypes.Contains(type));
+                bool allTypesFinalized = Internal.Entities.CustomNpcReadinessPolicy
+                    .AreAllTypesFinalized(customNpcTypes, FinalizedCustomNpcTypes);
 
                 if (allTypesFinalized)
                     CustomNpcsReady = true;
@@ -4701,6 +4701,15 @@ internal static void CheckAndSetCustomNpcsReady()
             }
         }
 
+        private void MarkCustomNpcFinalized()
+        {
+            Internal.Entities.CustomNpcReadinessPolicy.MarkFinalized(
+                GetType(),
+                FinalizedCustomNpcTypes);
+            ReconcileAllCustomNpcRelationshipConnections();
+            CheckAndSetCustomNpcsReady();
+        }
+
         internal static void ReconcileAllCustomNpcRelationshipConnections()
         {
             var configuredNpcs = All

S1API/Internal/Entities/CustomNpcReadinessPolicy.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace S1API.Internal.Entities
+{
+    /// <summary>
+    /// Determines whether every registered custom NPC type completed runtime hydration.
+    /// </summary>
+    internal static class CustomNpcReadinessPolicy
+    {
+        internal static void MarkFinalized(Type customNpcType, ISet<Type> finalizedTypes) =>
+            finalizedTypes.Add(customNpcType);
+
+        internal static bool AreAllTypesFinalized(
+            IEnumerable<Type> customNpcTypes,
+            ISet<Type> finalizedTypes)
+        {
+            var expectedTypes = customNpcTypes as IReadOnlyCollection<Type>
+                ?? customNpcTypes.ToList();
+
+            return expectedTypes.Count > 0
+                && expectedTypes.All(finalizedTypes.Contains);
+        }
+    }
+}

S1API/Internal/Patches/NPCPatches.cs

@@ -1277,7 +1277,6 @@ private static void NPCStart(S1NPCs.NPC __instance)
                 else
                 {
                     apiNpc.CreateFromClientNetworkSpawn();
-                    NPC.CheckAndSetCustomNpcsReady();
                 }
 
                 // Ensure visibility is set correctly on clients based on IsPhysical