Add Clothing Wrappers and Registry Helpers

S1API/Entities/Player.cs

@@ -11,8 +11,10 @@
 using System.Linq;
 using System.Reflection;
 using HarmonyLib;
+using S1API.Avatar;
 using S1API.Entities.Interfaces;
 using S1API.Internal.Abstraction;
+using S1API.Items;
 using S1API.Law;
 using UnityEngine;
 using S1API.Vehicles;
@@ -63,6 +65,11 @@ public class Player : IEntity, IHealth
         /// </summary>
         internal S1PlayerScripts.Player S1Player;
 
+        /// <summary>
+        /// The underlying game player (ScheduleOne.PlayerScripts.Player).
+        /// </summary>
+        public object NativePlayer => S1Player;
+
         /// <summary>
         /// INTERNAL: Constructor to create a new player from an S1 instance.
         /// </summary>
@@ -273,6 +280,65 @@ public PropertyWrapper? LastVisitedProperty {
         /// </summary>
         public object CurrentAvatarSettings => S1Player.CurrentAvatarSettings;
 
+        /// <summary>
+        /// Retrieves the player's current avatar settings as an S1API <see cref="BasicAvatarSettings"/> wrapper.
+        /// Returns a new <see cref="BasicAvatarSettings"/> instance on each call when S1Player.CurrentAvatarSettings is available.
+        /// </summary>
+        public BasicAvatarSettings? GetCurrentBasicAvatarSettings() =>
+            S1Player.CurrentAvatarSettings == null
+                ? null
+                : new BasicAvatarSettings(S1Player.CurrentAvatarSettings);
+
+        /// <summary>
+        /// Inserts clothing into the matching player clothing slot.
+        /// </summary>
+        public void InsertClothing(ClothingItemInstance clothing)
+        {
+            if (clothing == null)
+            {
+                throw new ArgumentNullException(nameof(clothing));
+            }
+
+            S1Player.Clothing.InsertClothing(clothing.S1ClothingInstance);
+        }
+
+        /// <summary>
+        /// Creates and inserts clothing into the matching player clothing slot.
+        /// </summary>
+        /// <param name="definition">The clothing item definition to equip.</param>
+        /// <param name="color">The clothing color to use for the created instance.</param>
+        /// <returns>The clothing instance that was inserted.</returns>
+        public ClothingItemInstance EquipClothing(ClothingItemDefinition definition, ClothingColor color = ClothingColor.White)
+        {
+            if (definition == null)
+            {
+                throw new ArgumentNullException(nameof(definition));
+            }
+
+            ClothingItemInstance clothing = definition.CreateInstance(color);
+            InsertClothing(clothing);
+            return clothing;
+        }
+
+        /// <summary>
+        /// Refreshes the player's avatar from the current clothing slots.
+        /// </summary>
+        public void RefreshClothingAppearance() =>
+            S1Player.Clothing.RefreshAppearance();
+
+        /// <summary>
+        /// Sends updated appearance settings through the game's native appearance flow.
+        /// </summary>
+        public void SendAppearance(BasicAvatarSettings settings)
+        {
+            if (settings == null)
+            {
+                throw new ArgumentNullException(nameof(settings));
+            }
+
+            S1Player.SendAppearance(settings.S1BasicAvatarSettings);
+        }
+
         /// <summary>
         /// Revives the player.
         /// </summary>
@@ -318,6 +384,15 @@ public event Action OnDeath
             remove => EventHelper.RemoveListener(value, S1Player.Health.onDie);
         }
 
+        /// <summary>
+        /// Called when the player revives.
+        /// </summary>
+        public event Action OnRevive
+        {
+            add => EventHelper.AddListener(value, S1Player.Health.onRevive);
+            remove => EventHelper.RemoveListener(value, S1Player.Health.onRevive);
+        }
+
         private static readonly HashSet<S1PlayerScripts.Player> InvinciblePlayers = new HashSet<S1PlayerScripts.Player>();
 
         internal static bool IsPlayerInvincible(S1PlayerScripts.Player player) => InvinciblePlayers.Contains(player);

S1API/Items/ClothingItemCreator.cs

@@ -14,7 +14,7 @@ namespace S1API.Items
 {
     /// <summary>
     /// Provides convenient static methods for creating custom clothing items.
-    /// Use <see cref="CreateBuilder"/> for flexible configuration or <see cref="CloneFrom"/> for variants.
+    /// Use <see cref="CreateBuilder()"/> for flexible configuration or <see cref="CloneFrom(string)"/> for variants.
     /// </summary>
     public static class ClothingItemCreator
     {

S1API/Items/ClothingItemDefinition.cs

@@ -15,8 +15,8 @@ namespace S1API.Items
     /// Extends <see cref="StorableItemDefinition"/> with clothing-specific properties.
     /// </summary>
     /// <remarks>
-    /// Use <see cref="ClothingItemCreator.CreateBuilder"/> to create new clothing items,
-    /// or <see cref="ClothingItemCreator.CloneFrom"/> to create variants of existing items.
+    /// Use <see cref="ClothingItemCreator.CreateBuilder()"/> to create new clothing items,
+    /// or <see cref="ClothingItemCreator.CloneFrom(string)"/> to create variants of existing items.
     /// </remarks>
     public sealed class ClothingItemDefinition : StorableItemDefinition
     {
@@ -34,6 +34,39 @@ internal ClothingItemDefinition(S1Clothing.ClothingDefinition definition)
         /// </summary>
         internal S1Clothing.ClothingDefinition S1ClothingDefinition { get; }
 
+        /// <summary>
+        /// The underlying game clothing definition (ScheduleOne.Clothing.ClothingDefinition).
+        /// </summary>
+        public object NativeClothingDefinition => S1ClothingDefinition;
+
+        /// <summary>
+        /// Creates a clothing instance from this definition using the default color.
+        /// </summary>
+        /// <param name="quantity">The quantity to apply to the created clothing instance.</param>
+        /// <returns>A clothing item instance using this definition's default color.</returns>
+        public override ItemInstance CreateInstance(int quantity = 1) =>
+            CreateInstance(quantity, DefaultColor);
+
+        /// <summary>
+        /// Creates a clothing instance from this definition with the specified color.
+        /// </summary>
+        /// <param name="color">The clothing color to apply to the created instance.</param>
+        /// <returns>A clothing instance using the specified color.</returns>
+        public ClothingItemInstance CreateInstance(ClothingColor color) =>
+            CreateInstance(1, color);
+
+        /// <summary>
+        /// Creates a clothing instance from this definition with the specified quantity and color.
+        /// </summary>
+        /// <param name="quantity">The quantity to apply to the created clothing instance.</param>
+        /// <param name="color">The clothing color to apply to the created instance.</param>
+        /// <returns>A clothing instance using the specified quantity and color.</returns>
+        public ClothingItemInstance CreateInstance(int quantity, ClothingColor color) =>
+            new ClothingItemInstance(new S1Clothing.ClothingInstance(
+                S1ClothingDefinition,
+                quantity,
+                (S1Clothing.EClothingColor)color));
+
         /// <summary>
         /// The clothing slot this item occupies.
         /// </summary>

S1API/Items/ClothingItemDefinitionBuilder.cs

@@ -13,6 +13,8 @@
 #endif
 
 using System.Collections.Generic;
+using S1API.Internal.Utils;
+using S1API.Logging;
 using UnityEngine;
 
 namespace S1API.Items
@@ -23,6 +25,9 @@ namespace S1API.Items
     /// </summary>
     public sealed class ClothingItemDefinitionBuilder
     {
+        private static readonly Log Logger = new Log("ClothingItemDefinitionBuilder");
+        private static readonly HashSet<string> WarnedMissingNativeClothingItemUiReasons = new HashSet<string>(System.StringComparer.OrdinalIgnoreCase);
+
         private readonly S1Clothing.ClothingDefinition _definition;
 
         /// <summary>
@@ -75,6 +80,7 @@ internal ClothingItemDefinitionBuilder(S1Clothing.ClothingDefinition source)
             _definition.UsableInFilters = source.UsableInFilters;
             _definition.StoredItem = source.StoredItem;
             _definition.Equippable = source.Equippable;
+            _definition.CustomItemUI = source.CustomItemUI;
 
             // Copy clothing-specific properties
             _definition.Slot = source.Slot;
@@ -220,6 +226,8 @@ public ClothingItemDefinitionBuilder WithPricing(float basePurchasePrice, float
         /// <returns>A wrapper around the created clothing item definition.</returns>
         public ClothingItemDefinition Build()
         {
+            EnsureNativeClothingItemUi();
+
             // Register with the game's registry
             S1Registry.Instance.AddToRegistry(_definition);
 
@@ -233,8 +241,62 @@ public ClothingItemDefinition Build()
         /// </summary>
         internal S1Clothing.ClothingDefinition BuildInternal()
         {
+            EnsureNativeClothingItemUi();
+
             return _definition;
         }
+
+        private void EnsureNativeClothingItemUi()
+        {
+            if (_definition.CustomItemUI != null)
+            {
+                return;
+            }
+
+            if (S1Registry.Instance == null)
+            {
+                WarnMissingNativeClothingItemUi("S1Registry.Instance is null");
+                return;
+            }
+
+            var allItems = S1Registry.Instance.GetAllItems();
+            if (allItems == null)
+            {
+                WarnMissingNativeClothingItemUi("S1Registry.Instance.GetAllItems() returned null");
+                return;
+            }
+
+            foreach (var item in allItems)
+            {
+                if (item == null ||
+                    !CrossType.Is(item, out S1Clothing.ClothingDefinition clothingDefinition) ||
+                    clothingDefinition.CustomItemUI == null)
+                {
+                    continue;
+                }
+
+                // CustomItemUI is a native UI template. Share the existing template instead of
+                // cloning it here; listing state is bound per item by the game, and cloning
+                // Unity/Il2Cpp UI objects is riskier across runtimes.
+                _definition.CustomItemUI = clothingDefinition.CustomItemUI;
+                return;
+            }
+
+            WarnMissingNativeClothingItemUi("no S1Clothing.ClothingDefinition with S1Clothing.ClothingDefinition.CustomItemUI was found");
+        }
+
+        private static void WarnMissingNativeClothingItemUi(string reason)
+        {
+            if (string.IsNullOrWhiteSpace(reason))
+            {
+                return;
+            }
+
+            if (WarnedMissingNativeClothingItemUiReasons.Add(reason))
+            {
+                Logger.Warning($"Could not borrow a native clothing CustomItemUI template ({reason}). Custom clothing inventory UI may be incomplete. This usually means Build() was called before any native clothing registered.");
+            }
+        }
     }
 }
 

S1API/Items/ClothingItemInstance.cs

@@ -17,6 +17,11 @@ public class ClothingItemInstance : ItemInstance
         /// </summary>
         internal readonly S1Clothing.ClothingInstance S1ClothingInstance;
 
+        /// <summary>
+        /// The underlying game clothing instance (ScheduleOne.Clothing.ClothingInstance).
+        /// </summary>
+        public object NativeClothingInstance => S1ClothingInstance;
+
         /// <summary>
         /// INTERNAL: Creates a ClothingItemInstance wrapper.
         /// </summary>

S1API/Items/ItemDefinition.cs

@@ -26,6 +26,11 @@ public class ItemDefinition : IGUIDReference
         /// </summary>
         internal S1ItemFramework.ItemDefinition S1ItemDefinition { get; }
 
+        /// <summary>
+        /// The underlying game item definition (ScheduleOne.ItemFramework.ItemDefinition).
+        /// </summary>
+        public object NativeDefinition => S1ItemDefinition;
+
         /// <summary>
         /// INTERNAL: Wraps an existing native item definition.
         /// </summary>

S1API/Items/ItemManager.cs

@@ -1,12 +1,10 @@
 #if (IL2CPPMELON)
-using S1 = Il2CppScheduleOne;
 using S1ItemFramework = Il2CppScheduleOne.ItemFramework;
 using S1Product = Il2CppScheduleOne.Product;
 using S1Registry = Il2CppScheduleOne.Registry;
 using S1Clothing = Il2CppScheduleOne.Clothing;
 using S1Packaging = Il2CppScheduleOne.Product.Packaging;
 #elif (MONOMELON || MONOBEPINEX || IL2CPPBEPINEX)
-using S1 = ScheduleOne;
 using S1ItemFramework = ScheduleOne.ItemFramework;
 using S1Product = ScheduleOne.Product;
 using S1Registry = ScheduleOne.Registry;
@@ -35,7 +33,7 @@ public static class ItemManager
         /// <returns>An instance of the item definition.</returns>
         public static ItemDefinition GetItemDefinition(string itemID)
         {
-            S1ItemFramework.ItemDefinition itemDefinition = S1.Registry.GetItem(itemID);
+            S1ItemFramework.ItemDefinition itemDefinition = S1Registry.GetItem(itemID);
 
             if (itemDefinition == null)
                 return null;
@@ -88,6 +86,47 @@ public static void RegisterItem(ItemDefinition definition)
             S1Registry.Instance.AddToRegistry(definition.S1ItemDefinition);
         }
 
+        /// <summary>
+        /// Checks whether an item ID is present in the active game registry.
+        /// </summary>
+        /// <param name="itemID">The ID of the item to look up.</param>
+        /// <returns>True if the item is registered; otherwise, false.</returns>
+        public static bool IsItemRegistered(string itemID)
+        {
+            if (string.IsNullOrWhiteSpace(itemID) || S1Registry.Instance == null)
+            {
+                return false;
+            }
+
+            return S1Registry.ItemExists(itemID);
+        }
+
+        /// <summary>
+        /// Registers an item only when it is missing from the active game registry.
+        /// </summary>
+        /// <param name="definition">The item definition to register.</param>
+        /// <returns>True if the item is registered after the call; otherwise, false.</returns>
+        public static bool EnsureItemRegistered(ItemDefinition definition)
+        {
+            if (definition == null)
+            {
+                throw new ArgumentNullException(nameof(definition), "Cannot register null item definition");
+            }
+
+            if (S1Registry.Instance == null)
+            {
+                return false;
+            }
+
+            if (IsItemRegistered(definition.ID))
+            {
+                return true;
+            }
+
+            S1Registry.Instance.AddToRegistry(definition.S1ItemDefinition);
+            return IsItemRegistered(definition.ID);
+        }
+
         /// <summary>
         /// Prevents a runtime-registered item from being removed during the next scene transition.
         /// This is useful for items that must survive a menu-to-game load sequence.