v0.4.4f10 Game Update

.github/workflows/docs.yml

@@ -256,7 +256,7 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./S1API/_site
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref != 'refs/heads/beta'
 
       # Save cache even if build fails (to enable beta cache priming)
       # Save on PR events AND on pushes to main branches (to update cache after assembly updates)
@@ -273,7 +273,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
-    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/stable' || github.ref == 'refs/heads/beta' || github.ref == 'refs/heads/npc-prefabs'
+    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/stable' || github.ref == 'refs/heads/npc-prefabs'
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

S1API/Entities/NPC.cs

@@ -1664,6 +1664,8 @@ public bool IsInvincible
 
         /// <summary>
         /// Revives the NPC.
+        /// Note: custom NPC revive currently routes through a temporary NPCHealth patch with a reflective fallback meant
+        /// for pre-network-init safety; live multiplayer calls should eventually stay on the authoritative network path.
         /// </summary>
         public void Revive() =>
             S1NPC.Health.Revive();
@@ -1718,9 +1720,18 @@ public void LerpScale(float scale, float lerpTime) =>
 
         /// <summary>
         /// Causes the NPC to become panicked.
+        /// Currently host/server-only: non-host clients hit the SafeIsServer guard below and this becomes a silent no-op,
+        /// which is inconsistent with other server-RPC-style wrappers in the API and with the runtime docs.
         /// </summary>
-        public void Panic() =>
-            S1NPC.SetPanicked();
+        public void Panic()
+        {
+            // TODO: Revisit this guard. Unlike wrappers such as Cartel.SetStatus and CombatBehaviour.SetAndAttackTarget,
+            // Panic() can no longer be invoked meaningfully from multiplayer clients because non-host callers return here.
+            if (!SafeIsServer())
+                return;
+
+            S1NPC.SetPanicked_Server();
+        }
 
         /// <summary>
         /// Causes the NPC to stop panicking, if they are currently.

S1API/Growing/SeedCreator.cs

@@ -1,10 +1,12 @@
 #if (IL2CPPMELON)
 using S1Growing = Il2CppScheduleOne.Growing;
 using S1ItemFramework = Il2CppScheduleOne.ItemFramework;
+using S1CoreItemFramework = Il2CppScheduleOne.Core.Items.Framework;
 using S1Registry = Il2CppScheduleOne.Registry;
 #elif  (MONOMELON || MONOBEPINEX || IL2CPPBEPINEX)
 using S1Growing = ScheduleOne.Growing;
 using S1ItemFramework = ScheduleOne.ItemFramework;
+using S1CoreItemFramework = ScheduleOne.Core.Items.Framework;
 using S1Registry = ScheduleOne.Registry;
 #endif
 
@@ -32,7 +34,7 @@ public static SeedDefinition CreateSeed(
             seed.Name = name;
             seed.Description = description;
             seed.StackLimit = stackLimit;
-            seed.Category = S1ItemFramework.EItemCategory.Agriculture;
+            seed.Category = S1CoreItemFramework.EItemCategory.Agriculture;
 
            // if (icon != null)
            // {

S1API/Internal/Logging/UnityExceptionTraceHook.cs

@@ -0,0 +1,113 @@
+using System;
+using S1API.Logging;
+using UnityEngine;
+#if IL2CPPMELON
+using Il2CppInterop.Runtime;
+#endif
+
+namespace S1API.Internal.Diagnostics
+{
+    /// <summary>
+    /// INTERNAL: Hooks Unity's threaded log callback to emit detailed stack traces for NullReferenceException logs.
+    /// </summary>
+    internal static class UnityExceptionTraceHook
+    {
+        private static readonly Log Logger = new Log("UnityExceptionTrace");
+        private static readonly object Sync = new object();
+#if IL2CPPMELON
+        private static readonly System.Action<string, string, LogType> ManagedCallback = OnUnityLogMessageReceived;
+        private static readonly Application.LogCallback Callback = DelegateSupport.ConvertDelegate<Application.LogCallback>(ManagedCallback);
+#endif
+
+        private static string _lastExceptionSignature;
+        private static DateTime _lastExceptionAtUtc;
+        private static bool _installed;
+
+        internal static void Install()
+        {
+            if (_installed)
+            {
+                return;
+            }
+
+#if IL2CPPMELON
+            Application.add_logMessageReceivedThreaded(Callback);
+#else
+            Application.logMessageReceivedThreaded += OnUnityLogMessageReceived;
+#endif
+            _installed = true;
+        }
+
+        internal static void Remove()
+        {
+            if (!_installed)
+            {
+                return;
+            }
+
+#if IL2CPPMELON
+            _installed = false;
+            return;
+#else
+            try
+            {
+                Application.logMessageReceivedThreaded -= OnUnityLogMessageReceived;
+            }
+            catch (Exception ex)
+            {
+                Logger.Warning($"[Unity] Failed to remove threaded log callback during shutdown: {ex.Message}");
+            }
+
+            _installed = false;
+#endif
+        }
+
+        private static void OnUnityLogMessageReceived(string condition, string stackTrace, LogType type)
+        {
+            if (type != LogType.Exception)
+            {
+                return;
+            }
+
+            if (!LooksLikeNullReference(condition, stackTrace))
+            {
+                return;
+            }
+
+            string signature = string.Concat(condition ?? string.Empty, "\n", stackTrace ?? string.Empty);
+            if (ShouldSuppressDuplicate(signature))
+            {
+                return;
+            }
+
+            Logger.Error($"[Unity] {condition}");
+
+            if (!string.IsNullOrWhiteSpace(stackTrace))
+            {
+                Logger.Error($"[Unity] stack trace:\n{stackTrace}");
+            }
+        }
+
+        private static bool LooksLikeNullReference(string condition, string stackTrace)
+        {
+            string haystack = string.Concat(condition ?? string.Empty, "\n", stackTrace ?? string.Empty);
+            return haystack.Contains("NullReferenceException", StringComparison.Ordinal);
+        }
+
+        private static bool ShouldSuppressDuplicate(string signature)
+        {
+            lock (Sync)
+            {
+                DateTime now = DateTime.UtcNow;
+                if (signature == _lastExceptionSignature && (now - _lastExceptionAtUtc).TotalSeconds < 1)
+                {
+                    return true;
+                }
+
+                _lastExceptionSignature = signature;
+                _lastExceptionAtUtc = now;
+                return false;
+            }
+        }
+    }
+}

S1API/Internal/Patches/LoadingScreenPatches.cs

@@ -211,7 +211,7 @@ private static void CloseLoadingScreenDirectly(S1UI.LoadingScreen loadingScreen)
             {
                 ReflectionUtils.TrySetFieldOrProperty(loadingScreen, "IsOpen", false);
 
-                var musicPlayer = S1DevUtilities.Singleton<S1Audio.MusicPlayer>.Instance;
+                var musicPlayer = S1DevUtilities.Singleton<S1Audio.MusicManager>.Instance;
                 if (musicPlayer != null)
                 {
                     musicPlayer.SetTrackEnabled("Loading Screen", enabled: false);

S1API/Internal/Patches/NPCPatches.cs

@@ -1567,6 +1567,9 @@ private static bool NPCInventory_OnSleepStart_Prefix(S1NPCs.NPCInventory __insta
         /// Temporary patch while S1API NPCs are not networked
         /// Guard Revive() for custom S1API NPCs to avoid Health SyncVar access before FishNet init.
         /// Applies equivalent revive effects without touching the SyncVar setter path.
+        /// TODO: Restrict this reflective fallback to the pre-network-init window only.
+        /// Once a custom NPC is live/networked, revive should stay on the authoritative server/original path instead of
+        /// mutating local health/death state and skipping the replicated revive flow.
         /// </summary>
         [HarmonyPatch(typeof(S1NPCs.NPCHealth), nameof(S1NPCs.NPCHealth.Revive))]
         [HarmonyPrefix]
@@ -1579,8 +1582,39 @@ private static bool NPCHealth_Revive_Prefix(S1NPCs.NPCHealth __instance)
             if (apiNpc == null || !apiNpc.IsCustomNPC)
                 return true; // use original for base NPCs
 
-            // Skip S1API NPCs for now
-            return false;
+            try
+            {
+                // NOTE: This currently mutates revive state locally and then always skips the original revive call below.
+                // That is only safe before networking is initialized; on live/networked NPCs, client-side calls can revive
+                // only the local wrapper copy while server-side calls bypass the authoritative replicated revive path.
+                bool healthSet = Utils.ReflectionUtils.TrySetFieldOrProperty(
+                    __instance, "<Health>k__BackingField", __instance.MaxHealth);
+                bool isDeadSet = Utils.ReflectionUtils.TrySetFieldOrProperty(__instance, "IsDead", false);
+                bool isKnockedOutSet = Utils.ReflectionUtils.TrySetFieldOrProperty(__instance, "IsKnockedOut", false);
+
+                if (!healthSet || !isDeadSet || !isKnockedOutSet)
+                {
+                    MelonLogger.Warning(
+                        $"[S1API] Revive guard reflection failed for custom NPC '{baseNpc?.ID ?? "<unknown>"}' " +
+                        $"(Health={healthSet}, IsDead={isDeadSet}, IsKnockedOut={isKnockedOutSet}); falling back to original revive.");
+                    return true;
+                }
+
+                // Disable behaviours locally (non-networked equivalent of Disable_Server)
+                baseNpc.Behaviour.DeadBehaviour?.Disable();
+                baseNpc.Behaviour.UnconsciousBehaviour?.Disable();
+
+                // Fire revive event so downstream listeners still react
+                __instance.onRevive?.Invoke();
+
+                return false; // skip original to avoid SyncVar/networking calls; revisit for post-init/live NPC revives.
+            }
+            catch (Exception ex)
+            {
+                MelonLogger.Warning(
+                    $"[S1API] Revive guard failed for custom NPC '{baseNpc?.ID ?? "<unknown>"}': {ex.Message}. Falling back to original revive.");
+                return true;
+            }
         }
 
         /// <summary>

S1API/Internal/S1APIPreferences.cs

@@ -9,6 +9,7 @@ internal static class S1APIPreferences
     {
         private static MelonPreferences_Category _category;
         internal static MelonPreferences_Entry<bool> EnableMugshotLoadingScreen;
+        internal static MelonPreferences_Entry<bool> EnableUnityNullReferenceTraceLogging;
 
         /// <summary>
         /// Initializes the S1API preferences category and entries. Call from OnInitializeMelon.
@@ -20,6 +21,11 @@ internal static void Initialize()
                 "EnableMugshotLoadingScreen",
                 true,
                 "When true, the loading screen stays open until custom NPC mugshots finish generating. Set to false to let the base game close the loading screen immediately.");
+
+            EnableUnityNullReferenceTraceLogging = _category.CreateEntry<bool>(
+                "EnableUnityNullReferenceTraceLogging",
+                true,
+                "When true, S1API subscribes to Unity's threaded log callback and emits stack traces for NullReferenceException logs to help diagnose runtime issues.");
         }
     }
 }

S1API/Items/AdditiveDefinitionBuilder.cs

@@ -1,9 +1,11 @@
 #if (IL2CPPMELON)
 using S1ItemFramework = Il2CppScheduleOne.ItemFramework;
+using S1CoreItemFramework = Il2CppScheduleOne.Core.Items.Framework;
 using S1Registry = Il2CppScheduleOne.Registry;
 using S1Storage = Il2CppScheduleOne.Storage;
 #elif (MONOMELON || MONOBEPINEX || IL2CPPBEPINEX)
 using S1ItemFramework = ScheduleOne.ItemFramework;
+using S1CoreItemFramework = ScheduleOne.Core.Items.Framework;
 using S1Registry = ScheduleOne.Registry;
 using S1Storage = ScheduleOne.Storage;
 #endif
@@ -39,11 +41,10 @@ internal AdditiveDefinitionBuilder()
             _definition.StackLimit = 10;
             _definition.BasePurchasePrice = 10f;
             _definition.ResellMultiplier = 0.5f;
-            _definition.Category = S1ItemFramework.EItemCategory.Agriculture;
-            _definition.legalStatus = S1ItemFramework.ELegalStatus.Legal;
+            _definition.Category = S1CoreItemFramework.EItemCategory.Agriculture;
+            _definition.legalStatus = S1CoreItemFramework.ELegalStatus.Legal;
             _definition.AvailableInDemo = true;
             _definition.UsableInFilters = true;
-            _definition.LabelDisplayColor = Color.white;
 
             // Provide a minimal StoredItem placeholder so the field is never null in tooling/inspectors.
             _storedItemPlaceholder = new GameObject("S1API_DefaultStoredItem");
@@ -82,10 +83,8 @@ private void CopyPropertiesFrom(S1ItemFramework.AdditiveDefinition source)
             _definition.Description = source.Description;
             _definition.Category = source.Category;
             _definition.StackLimit = source.StackLimit;
-            _definition.Keywords = source.Keywords;
             _definition.AvailableInDemo = source.AvailableInDemo;
             _definition.UsableInFilters = source.UsableInFilters;
-            _definition.LabelDisplayColor = source.LabelDisplayColor;
             _definition.Icon = source.Icon;
             _definition.legalStatus = source.legalStatus;
             _definition.PickpocketDifficultyMultiplier = source.PickpocketDifficultyMultiplier;
@@ -116,7 +115,7 @@ public AdditiveDefinitionBuilder WithBasicInfo(string id, string name, string de
             _definition.ID = id;
             _definition.Name = name;
             _definition.Description = description;
-            _definition.Category = (S1ItemFramework.EItemCategory)category;
+            _definition.Category = (S1CoreItemFramework.EItemCategory)category;
 
             var displayName = string.IsNullOrEmpty(name) ? id : name;
             if (!string.IsNullOrEmpty(displayName))
@@ -164,25 +163,7 @@ public AdditiveDefinitionBuilder WithPricing(float basePurchasePrice, float rese
         /// </summary>
         public AdditiveDefinitionBuilder WithLegalStatus(LegalStatus status)
         {
-            _definition.legalStatus = (S1ItemFramework.ELegalStatus)status;
-            return this;
-        }
-
-        /// <summary>
-        /// Sets the color of the label displayed in UI.
-        /// </summary>
-        public AdditiveDefinitionBuilder WithLabelColor(Color color)
-        {
-            _definition.LabelDisplayColor = color;
-            return this;
-        }
-
-        /// <summary>
-        /// Sets keywords used for filtering and searching this additive.
-        /// </summary>
-        public AdditiveDefinitionBuilder WithKeywords(params string[] keywords)
-        {
-            _definition.Keywords = keywords;
+            _definition.legalStatus = (S1CoreItemFramework.ELegalStatus)status;
             return this;
         }
 

S1API/Items/BuildableItemDefinition.cs

@@ -41,14 +41,6 @@ public BuildSoundType BuildSoundType
             set => S1BuildableItemDefinition.BuildSoundType = (S1ItemFramework.BuildableItemDefinition.EBuildSoundType)value;
         }
 
-        /// <summary>
-        /// The color displayed on the item's label in the UI.
-        /// </summary>
-        public new Color LabelDisplayColor
-        {
-            get => S1BuildableItemDefinition.LabelDisplayColor;
-            set => S1BuildableItemDefinition.LabelDisplayColor = value;
-        }
     }
 
     /// <summary>