feat(ModelCloneRegistry): add model-clone listener registry functionality

- Introduced `ModelCloneRegistry` for per-mod registration of model clone listeners, enhancing modularity and organization.
- Implemented methods for creating and managing listener registrations, including support for custom predicates.
- Updated documentation to reflect changes and improve clarity on usage within the framework.

Author: BAKAOLC

Models/ModelCloneRegistry.cs

@@ -3,49 +3,69 @@
 namespace STS2RitsuLib.Models
 {
     /// <summary>
-    ///     Global listeners for vanilla model clone operations.
-    ///     原版模型复制操作的全局监听器。
+    ///     Per-mod registration surface for vanilla model clone listeners.
+    ///     原版模型复制监听器的按 mod 注册入口。
     /// </summary>
-    public static class ModelCloneRegistry
+    public sealed class ModelCloneRegistry
     {
         private static readonly Lock SyncRoot = new();
+
+        private static readonly Dictionary<string, ModelCloneRegistry> Registries =
+            new(StringComparer.OrdinalIgnoreCase);
+
         private static readonly Dictionary<(string ModId, string ListenerId), ListenerEntry> Listeners = [];
         private static long _nextRegistrationOrder;
 
+        private readonly string _modId;
+
+        private ModelCloneRegistry(string modId)
+        {
+            _modId = modId;
+        }
+
         /// <summary>
-        ///     Registers or replaces a listener for <paramref name="modId" /> that receives every completed
-        ///     <see cref="AbstractModel.MutableClone" />.
-        ///     为 <paramref name="modId" /> 注册或替换一个监听器，以接收每次完成的
-        ///     <see cref="AbstractModel.MutableClone" />。
+        ///     Returns the singleton clone registry for <paramref name="modId" />, creating it on first use.
+        ///     返回 <paramref name="modId" /> 对应的单例复制注册表，并在首次使用时创建。
+        /// </summary>
+        public static ModelCloneRegistry For(string modId)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(modId);
+
+            lock (SyncRoot)
+            {
+                if (Registries.TryGetValue(modId, out var existing))
+                    return existing;
+
+                var created = new ModelCloneRegistry(modId);
+                Registries[modId] = created;
+                return created;
+            }
+        }
+
+        /// <summary>
+        ///     Registers or replaces a listener that receives every completed <see cref="AbstractModel.MutableClone" />.
+        ///     注册或替换一个监听器，以接收每次完成的 <see cref="AbstractModel.MutableClone" />。
         /// </summary>
-        /// <param name="modId">
-        ///     Owning mod identifier.
-        ///     所属 mod 标识符。
-        /// </param>
         /// <param name="listenerId">
-        ///     Unique listener id within the mod.
-        ///     此监听器在 mod 内的唯一标识符。
+        ///     Unique listener id within this registry's mod.
+        ///     此监听器在当前注册表 mod 内的唯一标识符。
         /// </param>
         /// <param name="listener">
         ///     Listener invoked after the clone has been created and initialized.
         ///     在复制体创建并初始化后调用的监听器。
         /// </param>
-        public static void Register(string modId, string listenerId, Action<ModelCloneContext> listener)
+        public void Register(string listenerId, Action<ModelCloneContext> listener)
         {
-            Register(modId, listenerId, _ => true, listener);
+            Register(listenerId, _ => true, listener);
         }
 
         /// <summary>
-        ///     Registers or replaces a listener with a custom predicate for <paramref name="modId" />.
-        ///     为 <paramref name="modId" /> 注册或替换一个带自定义谓词的监听器。
+        ///     Registers or replaces a listener with a custom predicate.
+        ///     注册或替换一个带自定义谓词的监听器。
         /// </summary>
-        /// <param name="modId">
-        ///     Owning mod identifier.
-        ///     所属 mod 标识符。
-        /// </param>
         /// <param name="listenerId">
-        ///     Unique listener id within the mod.
-        ///     此监听器在 mod 内的唯一标识符。
+        ///     Unique listener id within this registry's mod.
+        ///     此监听器在当前注册表 mod 内的唯一标识符。
         /// </param>
         /// <param name="predicate">
         ///     Predicate used to select clone operations for this listener.
@@ -55,69 +75,57 @@ public static void Register(string modId, string listenerId, Action<ModelCloneCo
         ///     Listener invoked after the clone has been created and initialized.
         ///     在复制体创建并初始化后调用的监听器。
         /// </param>
-        public static void Register(
-            string modId,
+        public void Register(
             string listenerId,
             Func<ModelCloneContext, bool> predicate,
             Action<ModelCloneContext> listener)
         {
-            ArgumentException.ThrowIfNullOrWhiteSpace(modId);
             ArgumentException.ThrowIfNullOrWhiteSpace(listenerId);
             ArgumentNullException.ThrowIfNull(predicate);
             ArgumentNullException.ThrowIfNull(listener);
 
             lock (SyncRoot)
             {
-                var key = (modId, listenerId);
+                var key = (_modId, listenerId);
                 var registrationOrder = Listeners.TryGetValue(key, out var existing)
                     ? existing.RegistrationOrder
                     : _nextRegistrationOrder++;
 
-                Listeners[key] = new(modId, listenerId, predicate, listener, registrationOrder);
+                Listeners[key] = new(_modId, listenerId, predicate, listener, registrationOrder);
             }
         }
 
         /// <summary>
-        ///     Registers or replaces a typed listener for a model family, including vanilla model types, for
-        ///     <paramref name="modId" />.
-        ///     为 <paramref name="modId" /> 注册或替换某个模型族的类型化监听器，包括原版模型类型。
+        ///     Registers or replaces a typed listener for a model family, including vanilla model types.
+        ///     注册或替换某个模型族的类型化监听器，包括原版模型类型。
         /// </summary>
         /// <typeparam name="TModel">
         ///     Model base or concrete type to listen for.
         ///     要监听的模型基类或具体类型。
         /// </typeparam>
-        /// <param name="modId">
-        ///     Owning mod identifier.
-        ///     所属 mod 标识符。
-        /// </param>
         /// <param name="listenerId">
-        ///     Unique listener id within the mod.
-        ///     此监听器在 mod 内的唯一标识符。
+        ///     Unique listener id within this registry's mod.
+        ///     此监听器在当前注册表 mod 内的唯一标识符。
         /// </param>
         /// <param name="listener">
         ///     Typed listener invoked when both prototype and cloned model are <typeparamref name="TModel" />.
         ///     当原型和复制体均为 <typeparamref name="TModel" /> 时调用的类型化监听器。
         /// </param>
-        public static void Register<TModel>(string modId, string listenerId, Action<TModel, TModel> listener)
+        public void Register<TModel>(string listenerId, Action<TModel, TModel> listener)
             where TModel : AbstractModel
         {
             ArgumentNullException.ThrowIfNull(listener);
 
             Register(
-                modId,
                 listenerId,
                 context => context is { Prototype: TModel, ClonedModel: TModel },
                 context => listener((TModel)context.Prototype, (TModel)context.ClonedModel));
         }
 
         /// <summary>
-        ///     Removes a previously registered listener.
-        ///     移除先前注册的监听器。
+        ///     Removes a previously registered listener from this registry's mod.
+        ///     从当前注册表 mod 移除先前注册的监听器。
         /// </summary>
-        /// <param name="modId">
-        ///     Mod identifier used at registration.
-        ///     注册时使用的 mod 标识符。
-        /// </param>
         /// <param name="listenerId">
         ///     Listener id used at registration.
         ///     注册时使用的监听器标识符。
@@ -126,14 +134,13 @@ public static void Register<TModel>(string modId, string listenerId, Action<TMod
         ///     <see langword="true" /> if an entry was removed.
         ///     如果移除了条目，则为 <see langword="true" />。
         /// </returns>
-        public static bool Unregister(string modId, string listenerId)
+        public bool Unregister(string listenerId)
         {
-            ArgumentException.ThrowIfNullOrWhiteSpace(modId);
             ArgumentException.ThrowIfNullOrWhiteSpace(listenerId);
 
             lock (SyncRoot)
             {
-                return Listeners.Remove((modId, listenerId));
+                return Listeners.Remove((_modId, listenerId));
             }
         }
 

RitsuLibFramework.cs

@@ -21,6 +21,7 @@
 using STS2RitsuLib.Keywords;
 using STS2RitsuLib.Localization;
 using STS2RitsuLib.Localization.SmartFormat;
+using STS2RitsuLib.Models;
 using STS2RitsuLib.Patching.Core;
 using STS2RitsuLib.Platform;
 using STS2RitsuLib.RunData;
@@ -564,6 +565,15 @@ public static ModUnlockRegistry GetUnlockRegistry(string modId)
             return ModUnlockRegistry.For(modId);
         }
 
+        /// <summary>
+        ///     Returns the model-clone listener registry for <paramref name="modId" />.
+        ///     返回 <paramref name="modId" /> 的模型复制监听器注册表。
+        /// </summary>
+        public static ModelCloneRegistry GetModelCloneRegistry(string modId)
+        {
+            return ModelCloneRegistry.For(modId);
+        }
+
         /// <summary>
         ///     Registers a non-power health bar forecast source type through the framework.
         ///     通过框架注册非能力生命条预测来源类型。