merge: Bring key binding flexibility and localization updates from dev into main

BAKAOLC · BAKAOLC · commit 07f32c2c5625 · 2026-03-25T18:12:23.000+08:00
diff --git a/Const.cs b/Const.cs
@@ -4,7 +4,7 @@ public static class Const
     {
         public const string Name = "RitsuLib";
         public const string ModId = "com.ritsukage.sts2-RitsuLib";
-        public const string Version = "0.0.15";
+        public const string Version = "0.0.16";
         public const string SettingsKey = "settings";
         public const string SettingsFileName = "settings.json";
     }
diff --git a/STS2-RitsuLib.csproj b/STS2-RitsuLib.csproj
@@ -10,7 +10,7 @@
         <NoWarn>CS0436</NoWarn>
         <IsPackable>true</IsPackable>
         <PackageId>STS2.RitsuLib</PackageId>
-        <Version>0.0.15</Version>
+        <Version>0.0.16</Version>
         <Authors>OLC</Authors>
         <Description>Shared framework library for Slay the Spire 2 mods.</Description>
         <PackageReadmeFile>README.md</PackageReadmeFile>
diff --git a/Settings/Localization/ModSettingsUi/deu.json b/Settings/Localization/ModSettingsUi/deu.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Aktionen",
   "button.resetDefault": "Auf Standard zurucksetzen",
   "button.copySelf": "Selbst kopieren",
-  "button.copySubtree": "Mit Unterelementen kopieren"
+  "button.copySubtree": "Mit Unterelementen kopieren",
+  "keybinding.hint.comboNonModifier": "Klicken, um aufzuzeichnen. Tastenkombinationen werden unterstuetzt und muessen eine Nicht-Modifikatortaste enthalten."
 }
diff --git a/Settings/Localization/ModSettingsUi/eng.json b/Settings/Localization/ModSettingsUi/eng.json
@@ -98,6 +98,7 @@
   "color.channel.saturation": "Saturation",
   "color.channel.value": "Value",
   "keybinding.hint.combo": "Click to record. Supports key combinations.",
+  "keybinding.hint.comboNonModifier": "Click to record. Supports key combinations and requires a non-modifier key.",
   "keybinding.hint.single": "Click to record a single key.",
   "keybinding.hint.capturing": "Press a key combination. Esc cancels, Backspace/Delete clears.",
   "keybinding.unbound": "Unbound",
diff --git a/Settings/Localization/ModSettingsUi/esp.json b/Settings/Localization/ModSettingsUi/esp.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Acciones",
   "button.resetDefault": "Restablecer por defecto",
   "button.copySelf": "Copiar este valor",
-  "button.copySubtree": "Copiar con elementos hijos"
+  "button.copySubtree": "Copiar con elementos hijos",
+  "keybinding.hint.comboNonModifier": "Haz clic para registrar. Se admiten combinaciones de teclas y deben incluir una tecla no modificadora."
 }
diff --git a/Settings/Localization/ModSettingsUi/fra.json b/Settings/Localization/ModSettingsUi/fra.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Actions",
   "button.resetDefault": "Retablir par defaut",
   "button.copySelf": "Copier cet element",
-  "button.copySubtree": "Copier avec les elements enfants"
+  "button.copySubtree": "Copier avec les elements enfants",
+  "keybinding.hint.comboNonModifier": "Cliquez pour enregistrer. Les combinaisons de touches sont prises en charge et doivent inclure une touche non modificatrice."
 }
diff --git a/Settings/Localization/ModSettingsUi/ita.json b/Settings/Localization/ModSettingsUi/ita.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Azioni",
   "button.resetDefault": "Ripristina predefinito",
   "button.copySelf": "Copia elemento",
-  "button.copySubtree": "Copia con elementi figli"
+  "button.copySubtree": "Copia con elementi figli",
+  "keybinding.hint.comboNonModifier": "Fai clic per registrare. Le combinazioni di tasti sono supportate e devono includere un tasto non modificatore."
 }
diff --git a/Settings/Localization/ModSettingsUi/jpn.json b/Settings/Localization/ModSettingsUi/jpn.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "操作",
   "button.resetDefault": "デフォルトに戻す",
   "button.copySelf": "この項目をコピー",
-  "button.copySubtree": "子項目込みでコピー"
+  "button.copySubtree": "子項目込みでコピー",
+  "keybinding.hint.comboNonModifier": "クリックして記録します。キーの組み合わせに対応しており、修飾キー以外のキーを1つ含める必要があります。"
 }
diff --git a/Settings/Localization/ModSettingsUi/kor.json b/Settings/Localization/ModSettingsUi/kor.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "동작",
   "button.resetDefault": "기본값으로 되돌리기",
   "button.copySelf": "현재 항목 복사",
-  "button.copySubtree": "하위 항목 포함 복사"
+  "button.copySubtree": "하위 항목 포함 복사",
+  "keybinding.hint.comboNonModifier": "클릭하여 기록합니다. 조합 키를 지원하며, 반드시 비수식 키를 하나 포함해야 합니다."
 }
diff --git a/Settings/Localization/ModSettingsUi/pol.json b/Settings/Localization/ModSettingsUi/pol.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Akcje",
   "button.resetDefault": "Przywroc domyslne",
   "button.copySelf": "Kopiuj ten element",
-  "button.copySubtree": "Kopiuj z elementami podrzednymi"
+  "button.copySubtree": "Kopiuj z elementami podrzednymi",
+  "keybinding.hint.comboNonModifier": "Kliknij, aby nagrac. Obslugiwane sa kombinacje klawiszy i musza zawierac klawisz inny niz modyfikator."
 }
diff --git a/Settings/Localization/ModSettingsUi/ptb.json b/Settings/Localization/ModSettingsUi/ptb.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Acoes",
   "button.resetDefault": "Restaurar padrao",
   "button.copySelf": "Copiar este item",
-  "button.copySubtree": "Copiar com itens filhos"
+  "button.copySubtree": "Copiar com itens filhos",
+  "keybinding.hint.comboNonModifier": "Clique para gravar. Combinacoes de teclas sao suportadas e devem incluir uma tecla nao modificadora."
 }
diff --git a/Settings/Localization/ModSettingsUi/rus.json b/Settings/Localization/ModSettingsUi/rus.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Действия",
   "button.resetDefault": "Сбросить по умолчанию",
   "button.copySelf": "Скопировать элемент",
-  "button.copySubtree": "Скопировать с дочерними элементами"
+  "button.copySubtree": "Скопировать с дочерними элементами",
+  "keybinding.hint.comboNonModifier": "Нажмите, чтобы записать. Поддерживаются сочетания клавиш, и они должны включать хотя бы одну немодифицирующую клавишу."
 }
diff --git a/Settings/Localization/ModSettingsUi/spa.json b/Settings/Localization/ModSettingsUi/spa.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Acciones",
   "button.resetDefault": "Restablecer por defecto",
   "button.copySelf": "Copiar este valor",
-  "button.copySubtree": "Copiar con elementos hijos"
+  "button.copySubtree": "Copiar con elementos hijos",
+  "keybinding.hint.comboNonModifier": "Haz clic para registrar. Se admiten combinaciones de teclas y deben incluir una tecla no modificadora."
 }
diff --git a/Settings/Localization/ModSettingsUi/tha.json b/Settings/Localization/ModSettingsUi/tha.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "การทำงาน",
   "button.resetDefault": "คืนค่าเริ่มต้น",
   "button.copySelf": "คัดลอกเฉพาะรายการนี้",
-  "button.copySubtree": "คัดลอกรวมรายการย่อย"
+  "button.copySubtree": "คัดลอกรวมรายการย่อย",
+  "keybinding.hint.comboNonModifier": "คลิกเพื่อบันทึก รองรับชุดปุ่ม และต้องมีปุ่มที่ไม่ใช่ปุ่มเสริมอย่างน้อยหนึ่งปุ่ม"
 }
diff --git a/Settings/Localization/ModSettingsUi/tur.json b/Settings/Localization/ModSettingsUi/tur.json
@@ -113,5 +113,6 @@
   "button.actionsShort": "Islemler",
   "button.resetDefault": "Varsayilana sifirla",
   "button.copySelf": "Bu ogeyi kopyala",
-  "button.copySubtree": "Alt ogelerle birlikte kopyala"
+  "button.copySubtree": "Alt ogelerle birlikte kopyala",
+  "keybinding.hint.comboNonModifier": "Kaydetmek icin tiklayin. Tus kombinasyonlari desteklenir ve modifiye olmayan bir tus icermelidir."
 }
diff --git a/Settings/Localization/ModSettingsUi/zhs.json b/Settings/Localization/ModSettingsUi/zhs.json
@@ -98,6 +98,7 @@
   "color.channel.saturation": "饱和度",
   "color.channel.value": "明度",
   "keybinding.hint.combo": "点击后录制按键，支持组合键。",
+  "keybinding.hint.comboNonModifier": "点击后录制按键，支持组合键，并且必须包含一个非修饰键。",
   "keybinding.hint.single": "点击后录制单个按键。",
   "keybinding.hint.capturing": "请按下按键组合。Esc 取消，Backspace/Delete 清空。",
   "keybinding.unbound": "未绑定",
diff --git a/Settings/ModSettingsDefinitions.cs b/Settings/ModSettingsDefinitions.cs
@@ -503,11 +503,15 @@ public sealed class KeyBindingModSettingsEntryDefinition(
         ModSettingsText label,
         IModSettingsValueBinding<string> binding,
         bool allowModifierCombos,
+        bool allowModifierOnly,
+        bool distinguishModifierSides,
         ModSettingsText? description)
         : ModSettingsEntryDefinition(id, label, description)
     {
         public IModSettingsValueBinding<string> Binding { get; } = binding;
         public bool AllowModifierCombos { get; } = allowModifierCombos;
+        public bool AllowModifierOnly { get; } = allowModifierOnly;
+        public bool DistinguishModifierSides { get; } = distinguishModifierSides;
 
         internal override Control CreateControl(ModSettingsUiContext context)
         {
@@ -1135,10 +1139,13 @@ public ModSettingsSectionBuilder AddKeyBinding(
             ModSettingsText label,
             IModSettingsValueBinding<string> binding,
             bool allowModifierCombos = true,
+            bool allowModifierOnly = true,
+            bool distinguishModifierSides = false,
             ModSettingsText? description = null)
         {
             AddEntry(id,
-                new KeyBindingModSettingsEntryDefinition(id, label, binding, allowModifierCombos, description));
+                new KeyBindingModSettingsEntryDefinition(id, label, binding, allowModifierCombos, allowModifierOnly,
+                    distinguishModifierSides, description));
             return this;
         }
 
diff --git a/Settings/ModSettingsUiControls.cs b/Settings/ModSettingsUiControls.cs
@@ -236,6 +236,8 @@ public static Control CreateKeyBindingEntry(ModSettingsUiContext context,
             var control = new ModSettingsKeyBindingControl(
                 entry.Binding.Read(),
                 entry.AllowModifierCombos,
+                entry.AllowModifierOnly,
+                entry.DistinguishModifierSides,
                 value =>
                 {
                     entry.Binding.Write(value);
@@ -1867,15 +1869,20 @@ private static string FormatColor(Color color)
     internal sealed partial class ModSettingsKeyBindingControl : VBoxContainer
     {
         private readonly bool _allowModifierCombos;
+        private readonly bool _allowModifierOnly;
+        private readonly bool _distinguishModifierSides;
         private readonly Action<string>? _onChanged;
         private Button? _captureButton;
         private bool _capturing;
         private string _currentValue = string.Empty;
         private Label? _hintLabel;
 
-        public ModSettingsKeyBindingControl(string initialValue, bool allowModifierCombos, Action<string> onChanged)
+        public ModSettingsKeyBindingControl(string initialValue, bool allowModifierCombos, bool allowModifierOnly,
+            bool distinguishModifierSides, Action<string> onChanged)
         {
             _allowModifierCombos = allowModifierCombos;
+            _allowModifierOnly = allowModifierOnly;
+            _distinguishModifierSides = distinguishModifierSides;
             _onChanged = onChanged;
             _currentValue = initialValue;
 
@@ -1964,7 +1971,8 @@ public override void _UnhandledKeyInput(InputEvent @event)
                     return;
             }
 
-            var binding = FormatKeyBinding(keyEvent, _allowModifierCombos);
+            var binding = FormatKeyBinding(keyEvent, _allowModifierCombos, _allowModifierOnly,
+                _distinguishModifierSides);
             if (string.IsNullOrWhiteSpace(binding))
                 return;
 
@@ -1998,12 +2006,16 @@ private void RefreshText()
                 ? ModSettingsLocalization.Get("keybinding.hint.capturing",
                     "Press a key combination. Esc cancels, Backspace/Delete clears.")
                 : _allowModifierCombos
-                    ? ModSettingsLocalization.Get("keybinding.hint.combo",
-                        "Click to record. Supports key combinations.")
+                    ? _allowModifierOnly
+                        ? ModSettingsLocalization.Get("keybinding.hint.combo",
+                            "Click to record. Supports key combinations.")
+                        : ModSettingsLocalization.Get("keybinding.hint.comboNonModifier",
+                            "Click to record. Supports key combinations and requires a non-modifier key.")
                     : ModSettingsLocalization.Get("keybinding.hint.single", "Click to record a single key.");
         }
 
-        private static string FormatKeyBinding(InputEventKey keyEvent, bool allowModifierCombos)
+        private static string FormatKeyBinding(InputEventKey keyEvent, bool allowModifierCombos, bool allowModifierOnly,
+            bool distinguishModifierSides)
         {
             var parts = new List<string>();
             if (allowModifierCombos && keyEvent.CtrlPressed)
@@ -2015,15 +2027,26 @@ private static string FormatKeyBinding(InputEventKey keyEvent, bool allowModifie
             if (allowModifierCombos && keyEvent.MetaPressed)
                 parts.Add("Meta");
 
+            if (!allowModifierOnly && IsModifierKey(keyEvent.Keycode))
+                return string.Empty;
+
             if (!IsModifierKey(keyEvent.Keycode) || parts.Count == 0)
-                parts.Add(keyEvent.Keycode.ToString());
+                parts.Add(GetRecordedKeyName(keyEvent.Keycode, distinguishModifierSides));
 
             if (!allowModifierCombos && IsModifierKey(keyEvent.Keycode))
-                return keyEvent.Keycode.ToString();
+                return GetRecordedKeyName(keyEvent.Keycode, distinguishModifierSides);
 
             return string.Join('+', parts);
         }
 
+        private static string GetRecordedKeyName(Key key, bool distinguishModifierSides)
+        {
+            if (!distinguishModifierSides || !IsModifierKey(key))
+                return key.ToString();
+
+            return key.ToString();
+        }
+
         private static bool IsModifierKey(Key key)
         {
             return key is Key.Shift or Key.Ctrl or Key.Alt or Key.Meta;
diff --git a/mod_manifest.json b/mod_manifest.json
@@ -4,7 +4,7 @@
   "name": "RitsuLib",
   "author": "OLC",
   "description": "A shared Slay the Spire 2 mod framework library providing reusable patching, persistence, lifecycle, localization, and utility APIs for other mods.",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "has_pck": false,
   "has_dll": true,
   "affects_gameplay": false,

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ public static class Const`
`4`	`4`	`{`
`5`	`5`	`public const string Name = "RitsuLib";`
`6`	`6`	`public const string ModId = "com.ritsukage.sts2-RitsuLib";`
`7`		`- public const string Version = "0.0.15";`
	`7`	`+ public const string Version = "0.0.16";`
`8`	`8`	`public const string SettingsKey = "settings";`
`9`	`9`	`public const string SettingsFileName = "settings.json";`
`10`	`10`	`}`
Original file line number	Diff line number	Diff line change
`@@ -113,5 +113,6 @@`
`113`	`113`	`"button.actionsShort": "Aktionen",`
`114`	`114`	`"button.resetDefault": "Auf Standard zurucksetzen",`
`115`	`115`	`"button.copySelf": "Selbst kopieren",`
`116`		`- "button.copySubtree": "Mit Unterelementen kopieren"`
	`116`	`+ "button.copySubtree": "Mit Unterelementen kopieren",`
	`117`	`+ "keybinding.hint.comboNonModifier": "Klicken, um aufzuzeichnen. Tastenkombinationen werden unterstuetzt und muessen eine Nicht-Modifikatortaste enthalten."`
`117`	`118`	`}`