feat(RightClick): implement right-click binding registration and ID management

- Added `RegisterRightClick` method to `RitsuLibFramework` for registering synced right-click bindings for models.
- Introduced `GetQualifiedRightClickId` method in `ModContentRegistry` to build mod-scoped right-click binding IDs.
- Created `ModRightClickBindingId` struct for stable identity management of registered right-click bindings.
- Enhanced `ModRightClickRegistry` to support registration and execution of right-click actions, improving interaction capabilities.

Author: BAKAOLC

Content/ModContentRegistry.cs

@@ -291,6 +291,20 @@ public static string GetQualifiedTopBarButtonId(string modId, string localButton
             return GetCompoundId(modId, "TOPBARBUTTON", localButtonStem);
         }
 
+        /// <summary>
+        ///     Builds a mod-scoped right-click binding id using the ritsulib <c>MODID_CATEGORY_TYPENAME</c>
+        ///     convention with middle segment <c>RIGHTCLICK</c>.
+        ///     使用 ritsulib <c>MODID_CATEGORY_TYPENAME</c> 约定构建 mod 作用域右键绑定 id，
+        ///     中间段为 <c>RIGHTCLICK</c>。
+        /// </summary>
+        public static string GetQualifiedRightClickId(string modId, string localRightClickStem)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(modId);
+            ArgumentException.ThrowIfNullOrWhiteSpace(localRightClickStem);
+
+            return GetCompoundId(modId, "RIGHTCLICK", localRightClickStem);
+        }
+
         /// <summary>
         ///     Returns the singleton registry for <paramref name="modId" /> (created on first use).
         ///     返回 <paramref name="modId" /> 的单例注册表（首次使用时创建）。

Interactions/RightClick/ModRightClickBindingId.cs

@@ -0,0 +1,15 @@
+namespace STS2RitsuLib.Interactions.RightClick
+{
+    /// <summary>
+    ///     Stable identity for a registered right-click binding.
+    ///     已注册右键绑定的稳定身份。
+    /// </summary>
+    public readonly record struct ModRightClickBindingId(string Id)
+    {
+        /// <inheritdoc />
+        public override string ToString()
+        {
+            return Id;
+        }
+    }
+}

Interactions/RightClick/ModRightClickRegistry.cs

@@ -9,6 +9,7 @@
 using MegaCrit.Sts2.Core.Multiplayer.Game;
 using MegaCrit.Sts2.Core.Multiplayer.Serialization;
 using MegaCrit.Sts2.Core.Runs;
+using STS2RitsuLib.Content;
 using STS2RitsuLib.Models.Identity;
 using STS2RitsuLib.Networking.Sidecar;
 
@@ -25,14 +26,21 @@ public static class ModRightClickRegistry
         private const string SidecarNonCombatRequestKey = "model_right_click_noncombat_request";
         private const string SidecarNonCombatApplyKey = "model_right_click_noncombat_apply";
         private const int InitialOffset = 0;
+        private const int InterfaceBindingPriority = int.MinValue;
 
         private static readonly Lock Gate = new();
+        private static long _nextBindingSequence;
 
         private static readonly List<IModRightClickHandler> Handlers =
         [
-            new InterfaceModelRightClickHandler(),
+            new BuiltInModelRightClickHandler(),
         ];
 
+        private static readonly List<RegisteredRightClickBinding> Bindings = [];
+
+        private static readonly ModRightClickBindingId InterfaceBindingId =
+            new(ModContentRegistry.GetQualifiedRightClickId(Const.ModId, "model_interface"));
+
         private static readonly RitsuLibSidecarSyncActionDescriptor<ModRightClickSyncPayload> SyncActionDescriptor =
             new(
                 SidecarModuleId,
@@ -79,6 +87,48 @@ public static void Register(IModRightClickHandler handler)
             }
         }
 
+        /// <summary>
+        ///     Registers a synced right-click binding for models of type <typeparamref name="TModel" />.
+        ///     为 <typeparamref name="TModel" /> 类型的模型注册同步右键绑定。
+        /// </summary>
+        /// <returns>
+        ///     A disposable registration handle.
+        ///     可释放的注册句柄。
+        /// </returns>
+        public static IDisposable Register<TModel>(
+            string modId,
+            string localStem,
+            Func<ModRightClickContext, bool> canHandle,
+            Func<ModRightClickExecutionContext, Task> execute,
+            int priority = 0)
+            where TModel : AbstractModel
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(modId);
+            ArgumentException.ThrowIfNullOrWhiteSpace(localStem);
+            ArgumentNullException.ThrowIfNull(canHandle);
+            ArgumentNullException.ThrowIfNull(execute);
+
+            var id = new ModRightClickBindingId(ModContentRegistry.GetQualifiedRightClickId(modId, localStem));
+            var binding = new RegisteredRightClickBinding(
+                id,
+                typeof(TModel),
+                canHandle,
+                execute,
+                priority,
+                Interlocked.Increment(ref _nextBindingSequence));
+
+            lock (Gate)
+            {
+                if (Bindings.Any(existing => existing.Id == id))
+                    throw new InvalidOperationException($"Right-click binding is already registered: {id}");
+
+                Bindings.Add(binding);
+                SortBindings();
+            }
+
+            return binding;
+        }
+
         /// <summary>
         ///     Attempts to dispatch a local right-click request.
         ///     尝试分发一个本地右键请求。
@@ -101,10 +151,14 @@ internal static void RegisterBuiltInSyncDescriptors()
             RitsuLibSidecarSyncMessages.Register(NonCombatApplyDescriptor);
         }
 
-        private static bool TryRequestSyncedModelAction(ModRightClickContext context)
+        private static bool TryRequestSyncedModelAction(
+            ModRightClickContext context,
+            IReadOnlyList<ModRightClickBindingId> bindingIds)
         {
             if (!TryCreatePayload(context, out var payload))
                 return false;
+
+            payload = payload with { BindingIds = [.. bindingIds] };
             if (!CombatManager.Instance.IsInProgress)
                 return TryRequestNonCombatAction(payload);
 
@@ -127,7 +181,8 @@ private static bool TryCreatePayload(ModRightClickContext context, out ModRightC
                 context.Player.NetId,
                 kind,
                 token,
-                context.Trigger);
+                context.Trigger,
+                []);
             return true;
         }
 
@@ -200,6 +255,7 @@ private static byte[] SerializePayload(ModRightClickSyncPayload payload)
             if (payload.Trigger.Metadata != null)
                 writer.WriteString(payload.Trigger.Metadata);
 
+            SerializeBindingIds(writer, payload.BindingIds);
             writer.ZeroByteRemainder();
             return writer.Buffer.AsSpan(InitialOffset, writer.BytePosition).ToArray();
         }
@@ -215,11 +271,13 @@ private static ModRightClickSyncPayload DeserializePayload(ReadOnlySpan<byte> by
 
             var isController = reader.ReadBool();
             var metadata = reader.ReadBool() ? reader.ReadString() : null;
+            var bindingIds = DeserializeBindingIds(reader);
             return new(
                 ownerNetId,
                 kind,
                 new(identity, modelId),
-                new(isController, metadata));
+                new(isController, metadata),
+                bindingIds);
         }
 
         private static async Task ExecuteSynced(
@@ -238,8 +296,8 @@ private static Task HandleNonCombatRequest(
                 RunManager.Instance?.NetService is not NetHostGameService ||
                 context.Message.OwnerNetId != context.SenderNetId ||
                 !TryGetPlayer(context.Message.OwnerNetId, out var player) ||
-                !TryResolveModel(player, context.Message, out var model) ||
-                model is not IModRightClickableModel)
+                !TryResolveModel(player, context.Message, out _) ||
+                context.Message.BindingIds.Count == 0)
                 return Task.CompletedTask;
 
             _ = RitsuLibSidecarSyncMessages.Broadcast(
@@ -264,16 +322,27 @@ private static async Task ExecutePayload(
                 return;
             if (!TryResolveModel(player, payload, out var model))
                 return;
-            if (model is not IModRightClickableModel rightClickable)
-                return;
 
-            await rightClickable.OnRightClick(new(
+            var executionContext = new ModRightClickExecutionContext(
                 player,
                 model,
                 payload.Trigger,
                 playerChoiceContext,
-                action));
-            model.InvokeExecutionFinished();
+                action);
+            var executed = false;
+            foreach (var bindingId in payload.BindingIds)
+                try
+                {
+                    if (await TryExecuteBinding(bindingId, model, executionContext))
+                        executed = true;
+                }
+                catch (Exception ex)
+                {
+                    RitsuLibFramework.Logger.Warn($"[RightClick] Binding '{bindingId}' failed: {ex.Message}");
+                }
+
+            if (executed)
+                model.InvokeExecutionFinished();
         }
 
         private static bool TryGetPlayer(ulong ownerNetId, out Player player)
@@ -329,20 +398,161 @@ private static bool TryResolveModel(
             }
         }
 
-        private sealed class InterfaceModelRightClickHandler : IModRightClickHandler
+        private static async Task<bool> TryExecuteBinding(
+            ModRightClickBindingId bindingId,
+            AbstractModel model,
+            ModRightClickExecutionContext context)
+        {
+            if (bindingId == InterfaceBindingId)
+            {
+                if (model is not IModRightClickableModel rightClickable)
+                    return false;
+
+                await rightClickable.OnRightClick(context);
+                return true;
+            }
+
+            var binding = TryGetBinding(bindingId);
+            if (binding == null || !binding.ModelType.IsInstanceOfType(model))
+                return false;
+
+            await binding.Execute(context);
+            return true;
+        }
+
+        private static RegisteredRightClickBinding? TryGetBinding(ModRightClickBindingId bindingId)
+        {
+            lock (Gate)
+            {
+                return Bindings.FirstOrDefault(binding => binding.Id == bindingId);
+            }
+        }
+
+        private static RegisteredRightClickBinding[] GetBindingsSnapshot()
+        {
+            lock (Gate)
+            {
+                return [.. Bindings];
+            }
+        }
+
+        private static void SortBindings()
+        {
+            Bindings.Sort((a, b) =>
+            {
+                var priority = b.Priority.CompareTo(a.Priority);
+                return priority != 0 ? priority : a.Sequence.CompareTo(b.Sequence);
+            });
+        }
+
+        private static void SerializeBindingIds(
+            PacketWriter writer,
+            IReadOnlyList<ModRightClickBindingId> bindingIds)
+        {
+            writer.WriteInt(bindingIds.Count);
+            foreach (var bindingId in bindingIds)
+                writer.WriteString(bindingId.Id);
+        }
+
+        private static IReadOnlyList<ModRightClickBindingId> DeserializeBindingIds(PacketReader reader)
+        {
+            var remainingBits = reader.Buffer.Length * 8 - reader.BitPosition;
+            if (remainingBits < 32)
+                return [];
+
+            var count = reader.ReadInt();
+            if (count <= 0)
+                return [];
+
+            var ids = new List<ModRightClickBindingId>(count);
+            for (var i = 0; i < count; i++)
+            {
+                var id = reader.ReadString();
+                if (!string.IsNullOrWhiteSpace(id))
+                    ids.Add(new(id.Trim()));
+            }
+
+            return ids;
+        }
+
+        private sealed class BuiltInModelRightClickHandler : IModRightClickHandler
         {
             public bool TryHandle(ModRightClickContext context)
             {
-                if (context.Model is not IModRightClickableModel rightClickable)
+                var bindingIds = CollectBindingIds(context);
+                return bindingIds.Count > 0 && TryRequestSyncedModelAction(context, bindingIds);
+            }
+
+            private static List<ModRightClickBindingId> CollectBindingIds(ModRightClickContext context)
+            {
+                var bindings = GetBindingsSnapshot();
+                var ids = (from binding in bindings
+                    where binding.ModelType.IsInstanceOfType(context.Model)
+                    where TryCanHandle(binding, context)
+                    select binding.Id).ToList();
+
+                if (context.Model is not IModRightClickableModel rightClickable ||
+                    !rightClickable.CanHandleRightClickLocal(context))
+                    return ids;
+
+                var insertIndex = 0;
+                while (insertIndex < bindings.Length && bindings[insertIndex].Priority > InterfaceBindingPriority)
+                    insertIndex++;
+
+                ids.Insert(Math.Min(insertIndex, ids.Count), InterfaceBindingId);
+                return ids;
+            }
+
+            private static bool TryCanHandle(RegisteredRightClickBinding binding, ModRightClickContext context)
+            {
+                try
+                {
+                    return binding.CanHandle(context);
+                }
+                catch (Exception ex)
+                {
+                    RitsuLibFramework.Logger.Warn(
+                        $"[RightClick] Binding '{binding.Id}' preflight failed: {ex.Message}");
                     return false;
-                return rightClickable.CanHandleRightClickLocal(context) && TryRequestSyncedModelAction(context);
+                }
+            }
+        }
+
+        private sealed class RegisteredRightClickBinding(
+            ModRightClickBindingId id,
+            Type modelType,
+            Func<ModRightClickContext, bool> canHandle,
+            Func<ModRightClickExecutionContext, Task> execute,
+            int priority,
+            long sequence) : IDisposable
+        {
+            private bool _disposed;
+
+            public ModRightClickBindingId Id { get; } = id;
+            public Type ModelType { get; } = modelType;
+            public Func<ModRightClickContext, bool> CanHandle { get; } = canHandle;
+            public Func<ModRightClickExecutionContext, Task> Execute { get; } = execute;
+            public int Priority { get; } = priority;
+            public long Sequence { get; } = sequence;
+
+            public void Dispose()
+            {
+                if (_disposed)
+                    return;
+
+                _disposed = true;
+                lock (Gate)
+                {
+                    Bindings.Remove(this);
+                }
             }
         }
 
         private readonly record struct ModRightClickSyncPayload(
             ulong OwnerNetId,
             ModRightClickModelKind Kind,
             ModModelIdentityToken Token,
-            ModRightClickTrigger Trigger);
+            ModRightClickTrigger Trigger,
+            IReadOnlyList<ModRightClickBindingId> BindingIds);
     }
 }