Merge f73ffd1fd0 into 2c8edaf89e

src/Ryujinx.Common/Configuration/Hid/KeyboardHotkeys.cs

@@ -1,3 +1,5 @@
+using System.Collections.Generic;
+
 namespace Ryujinx.Common.Configuration.Hid
 {
     public class KeyboardHotkeys
@@ -13,5 +15,6 @@ namespace Ryujinx.Common.Configuration.Hid
         public Key VolumeDown { get; set; }
         public Key CustomVSyncIntervalIncrement { get; set; }
         public Key CustomVSyncIntervalDecrement { get; set; }
+        public List<Key> CycleControllers { get; set; }
     }
 }

src/Ryujinx/AppHost.cs

@@ -40,6 +40,7 @@ using Ryujinx.HLE;
 using Ryujinx.HLE.FileSystem;
 using Ryujinx.HLE.HOS;
 using Ryujinx.HLE.HOS.Services.Account.Acc;
+using Ryujinx.HLE.HOS.Services.Hid;
 using Ryujinx.HLE.HOS.SystemState;
 using Ryujinx.Input;
 using Ryujinx.Input.HLE;
@@ -49,6 +50,7 @@ using System;
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.IO;
+using System.Linq;
 using System.Runtime.InteropServices;
 using System.Threading;
 using System.Threading.Tasks;
@@ -1308,6 +1310,18 @@ namespace Ryujinx.Ava
 
                             _viewModel.Volume = Device.GetVolume();
                             break;
+                        case KeyboardHotkeyState.CycleControllersPlayer1:
+                        case KeyboardHotkeyState.CycleControllersPlayer2:
+                        case KeyboardHotkeyState.CycleControllersPlayer3:
+                        case KeyboardHotkeyState.CycleControllersPlayer4:
+                        case KeyboardHotkeyState.CycleControllersPlayer5:
+                        case KeyboardHotkeyState.CycleControllersPlayer6:
+                        case KeyboardHotkeyState.CycleControllersPlayer7:
+                        case KeyboardHotkeyState.CycleControllersPlayer8:
+                            var player = currentHotkeyState - KeyboardHotkeyState.CycleControllersPlayer1;
+                            var ivm = new UI.ViewModels.Input.InputViewModel();
+                            Dispatcher.UIThread.Invoke(() => ivm.CyclePlayerDevice(player));
+                            break;
                         case KeyboardHotkeyState.None:
                             (_keyboardInterface as AvaloniaKeyboard).Clear();
                             break;
@@ -1390,6 +1404,15 @@ namespace Ryujinx.Ava
                 state = KeyboardHotkeyState.CustomVSyncIntervalDecrement;
             }
 
+            foreach (var cycle in ConfigurationState.Instance.Hid.Hotkeys.Value.CycleControllers?.Select((value, index) => (value, index)) ?? [])
+            {
+                if (_keyboardInterface.IsPressed((Key)cycle.value))
+                {
+                    state = KeyboardHotkeyState.CycleControllersPlayer1 + cycle.index;
+                    break;
+                }
+            }
+
             return state;
         }
     }

src/Ryujinx/Assets/locales.json

@@ -5672,6 +5672,31 @@
         "zh_TW": "啟用警告日誌"
       }
     },
+    {
+      "ID": "SettingsTabHotkeysCycleControllers",
+      "Translations": {
+        "ar_SA": "",
+        "de_DE": "",
+        "el_GR": "",
+        "en_US": "Cycle Controllers",
+        "es_ES": "",
+        "fr_FR": "",
+        "he_IL": "",
+        "it_IT": "",
+        "ja_JP": "",
+        "ko_KR": "",
+        "no_NO": "",
+        "pl_PL": "",
+        "pt_BR": "",
+        "ru_RU": "",
+        "sv_SE": "",
+        "th_TH": "",
+        "tr_TR": "",
+        "uk_UA": "",
+        "zh_CN": "",
+        "zh_TW": ""
+      }
+    },
     {
       "ID": "SettingsTabLoggingEnableErrorLogs",
       "Translations": {

src/Ryujinx/Common/KeyboardHotkeyState.cs

@@ -14,5 +14,13 @@ namespace Ryujinx.Ava.Common
         VolumeDown,
         CustomVSyncIntervalIncrement,
         CustomVSyncIntervalDecrement,
+        CycleControllersPlayer1,
+        CycleControllersPlayer2,
+        CycleControllersPlayer3,
+        CycleControllersPlayer4,
+        CycleControllersPlayer5,
+        CycleControllersPlayer6,
+        CycleControllersPlayer7,
+        CycleControllersPlayer8
     }
 }

src/Ryujinx/DiscordIntegrationModule.cs

@@ -126,14 +126,16 @@ namespace Ryujinx.Ava
             if (!TitleIDs.CurrentApplication.Value.HasValue) return;
             if (_discordPresencePlaying is null) return;
 
-            Analyzer.FormattedValue formattedValue =
+            FormattedValue formattedValue =
                 PlayReports.Analyzer.Format(TitleIDs.CurrentApplication.Value, _currentApp, playReport);
 
             if (!formattedValue.Handled) return;
 
-            _discordPresencePlaying.Details = formattedValue.Reset 
-                ? $"Playing {_currentApp.Title}" 
-                : formattedValue.FormattedString;
+            _discordPresencePlaying.Details = TruncateToByteLength(
+                formattedValue.Reset
+                    ? $"Playing {_currentApp.Title}"
+                    : formattedValue.FormattedString
+            );
 
             if (_discordClient.CurrentPresence.Details.Equals(_discordPresencePlaying.Details))
                 return; //don't trigger an update if the set presence Details are identical to current

src/Ryujinx/UI/Models/Input/HotkeyConfig.cs

@@ -1,6 +1,11 @@
 using CommunityToolkit.Mvvm.ComponentModel;
+using DynamicData;
+using Ryujinx.Ava.UI.Helpers;
 using Ryujinx.Ava.UI.ViewModels;
 using Ryujinx.Common.Configuration.Hid;
+using System.Collections.ObjectModel;
+using System.Linq;
+using System.Windows.Input;
 
 namespace Ryujinx.Ava.UI.Models.Input
 {
@@ -28,8 +33,15 @@ namespace Ryujinx.Ava.UI.Models.Input
 
         [ObservableProperty] private Key _customVSyncIntervalDecrement;
 
+        public ObservableCollection<CycleController> CycleControllers { get; set; } = new ObservableCollection<CycleController>();
+        public ICommand AddCycleController { get; set; }
+        public ICommand RemoveCycleController { get; set; }
+        public bool CanRemoveCycleController => CycleControllers.Count > 0 && CycleControllers.Count < 8;
+
         public HotkeyConfig(KeyboardHotkeys config)
         {
+            AddCycleController = MiniCommand.Create(() => CycleControllers.Add(new CycleController(CycleControllers.Count + 1, Key.Unbound)));
+            RemoveCycleController = MiniCommand.Create(() => CycleControllers.Remove(CycleControllers.Last()));
             if (config == null)
                 return;
 
@@ -44,6 +56,7 @@ namespace Ryujinx.Ava.UI.Models.Input
             VolumeDown = config.VolumeDown;
             CustomVSyncIntervalIncrement = config.CustomVSyncIntervalIncrement;
             CustomVSyncIntervalDecrement = config.CustomVSyncIntervalDecrement;
+            CycleControllers.AddRange((config.CycleControllers ?? []).Select((x, i) => new CycleController(i + 1, x)));
         }
 
         public KeyboardHotkeys GetConfig() =>
@@ -60,6 +73,7 @@ namespace Ryujinx.Ava.UI.Models.Input
                 VolumeDown = VolumeDown,
                 CustomVSyncIntervalIncrement = CustomVSyncIntervalIncrement,
                 CustomVSyncIntervalDecrement = CustomVSyncIntervalDecrement,
+                CycleControllers = CycleControllers.Select(x => x.Hotkey).ToList()
             };
     }
 }

src/Ryujinx/UI/ViewModels/CycleController.cs

@@ -0,0 +1,48 @@
+using Ryujinx.Ava.Common.Locale;
+using Ryujinx.Common.Configuration.Hid;
+
+namespace Ryujinx.Ava.UI.ViewModels
+{
+    public class CycleController : BaseModel
+    {
+        private string _player;
+        private Key _hotkey;
+
+        public string Player
+        {
+            get => _player;
+            set
+            {
+                _player = value;
+                OnPropertyChanged(nameof(Player));
+            }
+        }
+
+        public Key Hotkey
+        {
+            get => _hotkey;
+            set
+            {
+                _hotkey = value;
+                OnPropertyChanged(nameof(Hotkey));
+            }
+        }
+
+        public CycleController(int v, Key x)
+        {
+            Player = v switch
+            {
+                1 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer1],
+                2 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer2],
+                3 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer3],
+                4 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer4],
+                5 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer5],
+                6 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer6],
+                7 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer7],
+                8 => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer8],
+                _ => LocaleManager.Instance[LocaleKeys.ControllerSettingsPlayer] + " " + v
+            };
+            Hotkey = x;
+        }
+    }
+}

src/Ryujinx/UI/ViewModels/Input/InputViewModel.cs

@@ -897,5 +897,13 @@ namespace Ryujinx.Ava.UI.ViewModels.Input
 
             AvaloniaKeyboardDriver.Dispose();
         }
+
+        public void CyclePlayerDevice(int player)
+        {
+            LoadDevices();
+            PlayerId = (PlayerIndex)player;
+            Device = (Device + 1) % Devices.Count;
+            Save();
+        }
     }
 }

src/Ryujinx/UI/Views/Settings/SettingsHotkeysView.axaml

@@ -1,4 +1,4 @@
-<UserControl
+<UserControl
     x:Class="Ryujinx.Ava.UI.Views.Settings.SettingsHotkeysView"
     xmlns="https://github.com/avaloniaui"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
@@ -15,17 +15,18 @@
         <viewModels:SettingsViewModel />
     </Design.DataContext>
     <UserControl.Styles>
-        <Style Selector="StackPanel > StackPanel">
+        <Style Selector="StackPanel StackPanel">
             <Setter Property="Margin" Value="10, 0, 0, 0" />
             <Setter Property="Orientation" Value="Horizontal" />
         </Style>
-        <Style Selector="StackPanel > StackPanel > TextBlock">
+        <Style Selector="StackPanel StackPanel > TextBlock">
             <Setter Property="VerticalAlignment" Value="Center" />
             <Setter Property="Width" Value="230" />
         </Style>
-        <Style Selector="ToggleButton">
+        <Style Selector="ToggleButton, Button">
             <Setter Property="Width" Value="90" />
             <Setter Property="Height" Value="27" />
+            <Setter Property="Padding" Value="0,5,0,5" /> <!-- Added vertical padding -->
         </Style>
         <Style Selector="ToggleButton > TextBlock">
             <Setter Property="TextAlignment" Value="Center" />
@@ -39,79 +40,123 @@
         VerticalScrollBarVisibility="Auto">
         <Border Classes="settings">
             <StackPanel
-                Name="SettingButtons"
                 Margin="10"
+                HorizontalAlignment="Stretch"
                 Orientation="Vertical"
-                Spacing="10">
+                Spacing="10"
+                Name="SettingButtons">
                 <TextBlock
                     Classes="h1"
                     Text="{ext:Locale SettingsTabHotkeysHotkeys}" />
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysToggleVSyncModeHotkey}" />
-                    <ToggleButton Name="ToggleVSyncMode">
-                        <TextBlock Text="{Binding KeyboardHotkey.ToggleVSyncMode, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
+                <StackPanel
+                    Margin="10,0,0,0"
+                    Spacing="10"
+                    Orientation="Vertical">
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysToggleVSyncModeHotkey}" />
+                        <ToggleButton Name="ToggleVSyncMode">
+                            <TextBlock Text="{Binding KeyboardHotkey.ToggleVSyncMode, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysScreenshotHotkey}" />
+                        <ToggleButton Name="Screenshot">
+                            <TextBlock Text="{Binding KeyboardHotkey.Screenshot, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysShowUiHotkey}" />
+                        <ToggleButton Name="ShowUI">
+                            <TextBlock Text="{Binding KeyboardHotkey.ShowUI, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysPauseHotkey}" />
+                        <ToggleButton Name="Pause">
+                            <TextBlock Text="{Binding KeyboardHotkey.Pause, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysToggleMuteHotkey}" />
+                        <ToggleButton Name="ToggleMute">
+                            <TextBlock Text="{Binding KeyboardHotkey.ToggleMute, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysResScaleUpHotkey}" />
+                        <ToggleButton Name="ResScaleUp">
+                            <TextBlock Text="{Binding KeyboardHotkey.ResScaleUp, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysResScaleDownHotkey}" />
+                        <ToggleButton Name="ResScaleDown">
+                            <TextBlock Text="{Binding KeyboardHotkey.ResScaleDown, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysVolumeUpHotkey}" />
+                        <ToggleButton Name="VolumeUp">
+                            <TextBlock Text="{Binding KeyboardHotkey.VolumeUp, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel>
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysVolumeDownHotkey}" />
+                        <ToggleButton Name="VolumeDown">
+                            <TextBlock Text="{Binding KeyboardHotkey.VolumeDown, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel Margin="10,0,0,0" Orientation="Horizontal">
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysIncrementCustomVSyncIntervalHotkey}" />
+                        <ToggleButton Name="CustomVSyncIntervalIncrement">
+                            <TextBlock Text="{Binding KeyboardHotkey.CustomVSyncIntervalIncrement, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
+                    <StackPanel Margin="10,0,0,0" Orientation="Horizontal">
+                        <TextBlock Text="{ext:Locale SettingsTabHotkeysDecrementCustomVSyncIntervalHotkey}" />
+                        <ToggleButton Name="CustomVSyncIntervalDecrement">
+                            <TextBlock Text="{Binding KeyboardHotkey.CustomVSyncIntervalDecrement, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                        </ToggleButton>
+                    </StackPanel>
                 </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysScreenshotHotkey}" />
-                    <ToggleButton Name="Screenshot">
-                        <TextBlock Text="{Binding KeyboardHotkey.Screenshot, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysShowUiHotkey}" />
-                    <ToggleButton Name="ShowUI">
-                        <TextBlock Text="{Binding KeyboardHotkey.ShowUI, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysPauseHotkey}" />
-                    <ToggleButton Name="Pause">
-                        <TextBlock Text="{Binding KeyboardHotkey.Pause, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysToggleMuteHotkey}" />
-                    <ToggleButton Name="ToggleMute">
-                        <TextBlock Text="{Binding KeyboardHotkey.ToggleMute, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysResScaleUpHotkey}" />
-                    <ToggleButton Name="ResScaleUp">
-                        <TextBlock Text="{Binding KeyboardHotkey.ResScaleUp, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysResScaleDownHotkey}" />
-                    <ToggleButton Name="ResScaleDown">
-                        <TextBlock Text="{Binding KeyboardHotkey.ResScaleDown, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysVolumeUpHotkey}" />
-                    <ToggleButton Name="VolumeUp">
-                        <TextBlock Text="{Binding KeyboardHotkey.VolumeUp, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel>
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysVolumeDownHotkey}" />
-                    <ToggleButton Name="VolumeDown">
-                        <TextBlock Text="{Binding KeyboardHotkey.VolumeDown, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel Margin="10,0,0,0" Orientation="Horizontal">
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysIncrementCustomVSyncIntervalHotkey}" />
-                    <ToggleButton Name="CustomVSyncIntervalIncrement">
-                        <TextBlock Text="{Binding KeyboardHotkey.CustomVSyncIntervalIncrement, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
-                </StackPanel>
-                <StackPanel Margin="10,0,0,0" Orientation="Horizontal">
-                    <TextBlock Text="{ext:Locale SettingsTabHotkeysDecrementCustomVSyncIntervalHotkey}" />
-                    <ToggleButton Name="CustomVSyncIntervalDecrement">
-                        <TextBlock Text="{Binding KeyboardHotkey.CustomVSyncIntervalDecrement, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
-                    </ToggleButton>
+                <Separator Height="1" />
+                <StackPanel Margin="0">
+                    <TextBlock
+                        Classes="h1"
+                        Text="{ext:Locale SettingsTabHotkeysCycleControllers}" />
+                    <StackPanel Orientation="Horizontal" Spacing="10">
+                        <Button
+                            Content="{ext:Locale SettingsTabGeneralAdd}"
+                            Margin="10,0,0,0"
+                            Command="{Binding KeyboardHotkey.AddCycleController}" />
+                        <Button
+                            Content="{ext:Locale SettingsTabGeneralRemove}"
+                            IsEnabled="{Binding KeyboardHotkey.CanRemoveCycleController}"
+                            Command="{Binding KeyboardHotkey.RemoveCycleController}" />
+                    </StackPanel>
                 </StackPanel>
+                <ItemsControl ItemsSource="{Binding KeyboardHotkey.CycleControllers}"
+                    Name="CycleControllers">
+                    <ItemsControl.ItemsPanel>
+                        <ItemsPanelTemplate>
+                            <StackPanel
+                                Margin="10,0,0,0"
+                                Orientation="Vertical"
+                                Spacing="10" />
+                        </ItemsPanelTemplate>
+                    </ItemsControl.ItemsPanel>
+                    <ItemsControl.ItemTemplate>
+                        <DataTemplate>
+                            <StackPanel>
+                                <TextBlock Text="{Binding Player}" />
+                                <ToggleButton>
+                                    <TextBlock
+                                        Text="{Binding Hotkey, Converter={x:Static helpers:KeyValueConverter.Instance}}" />
+                                </ToggleButton>
+                            </StackPanel>
+                        </DataTemplate>
+                    </ItemsControl.ItemTemplate>
+                </ItemsControl>
             </StackPanel>
         </Border>
    </ScrollViewer>

src/Ryujinx/UI/Views/Settings/SettingsHotkeysView.axaml.cs

@@ -3,11 +3,14 @@ using Avalonia.Controls.Primitives;
 using Avalonia.Input;
 using Avalonia.Interactivity;
 using Avalonia.LogicalTree;
+using Avalonia.VisualTree;
+using DynamicData;
 using Ryujinx.Ava.Input;
 using Ryujinx.Ava.UI.Helpers;
 using Ryujinx.Ava.UI.ViewModels;
 using Ryujinx.Input;
 using Ryujinx.Input.Assigner;
+using System.Linq;
 using Button = Ryujinx.Input.Button;
 using Key = Ryujinx.Common.Configuration.Hid.Key;
 
@@ -21,16 +24,21 @@ namespace Ryujinx.Ava.UI.Views.Settings
         public SettingsHotkeysView()
         {
             InitializeComponent();
+            RegisterEvents();
+            _avaloniaKeyboardDriver = new AvaloniaKeyboardDriver(this);
+            CycleControllers.LayoutUpdated += (_, _1) => RegisterEvents();
+        }
 
+        private void RegisterEvents()
+        {
             foreach (ILogical visual in SettingButtons.GetLogicalDescendants())
             {
                 if (visual is ToggleButton button and not CheckBox)
                 {
+                    button.IsCheckedChanged -= Button_IsCheckedChanged;
                     button.IsCheckedChanged += Button_IsCheckedChanged;
                 }
             }
-
-            _avaloniaKeyboardDriver = new AvaloniaKeyboardDriver(this);
         }
 
         protected override void OnPointerReleased(PointerReleasedEventArgs e)
@@ -116,6 +124,13 @@ namespace Ryujinx.Ava.UI.Views.Settings
                                     case "CustomVSyncIntervalDecrement":
                                         viewModel.KeyboardHotkey.CustomVSyncIntervalDecrement = buttonValue.AsHidType<Key>();
                                         break;
+                                    default:
+                                        var index = button.FindAncestorOfType<ItemsControl>().GetLogicalDescendants().OfType<ToggleButton>().IndexOf(button);
+                                        if (index >= 0 && viewModel.KeyboardHotkey.CycleControllers != null)
+                                        {
+                                            viewModel.KeyboardHotkey.CycleControllers[index].Hotkey = buttonValue.AsHidType<Key>();
+                                        }
+                                        break;
                                 }
                             }
                         };

src/Ryujinx/Utilities/PlayReport/Analyzer.cs

@@ -78,7 +78,7 @@ namespace Ryujinx.Ava.Utilities.PlayReport
             return this;
         }
 
-        
+
         /// <summary>
         /// Runs the configured <see cref="GameSpec.FormatterSpec"/> for the specified game title ID.
         /// </summary>
@@ -98,261 +98,48 @@ namespace Ryujinx.Ava.Utilities.PlayReport
             if (!_specs.TryGetFirst(s => runningGameId.EqualsAnyIgnoreCase(s.TitleIds), out GameSpec spec))
                 return FormattedValue.Unhandled;
 
-            foreach (GameSpec.FormatterSpec formatSpec in spec.SimpleValueFormatters.OrderBy(x => x.Priority))
+            foreach (FormatterSpec formatSpec in spec.SimpleValueFormatters.OrderBy(x => x.Priority))
             {
                 if (!playReport.AsDictionary().TryGetValue(formatSpec.ReportKey, out MessagePackObject valuePackObject))
                     continue;
 
-                return formatSpec.ValueFormatter(new Value
-                {
-                    Application = appMeta, PackedValue = valuePackObject
-                });
+                return formatSpec.Formatter(new Value { Application = appMeta, PackedValue = valuePackObject });
             }
-            
-            foreach (GameSpec.MultiFormatterSpec formatSpec in spec.MultiValueFormatters.OrderBy(x => x.Priority))
+
+            foreach (MultiFormatterSpec formatSpec in spec.MultiValueFormatters.OrderBy(x => x.Priority))
             {
                 List<MessagePackObject> packedObjects = [];
                 foreach (var reportKey in formatSpec.ReportKeys)
                 {
                     if (!playReport.AsDictionary().TryGetValue(reportKey, out MessagePackObject valuePackObject))
                         continue;
-                    
+
                     packedObjects.Add(valuePackObject);
                 }
-                
+
                 if (packedObjects.Count != formatSpec.ReportKeys.Length)
                     return FormattedValue.Unhandled;
-                
-                return formatSpec.ValueFormatter(packedObjects
+
+                return formatSpec.Formatter(packedObjects
                     .Select(packObject => new Value { Application = appMeta, PackedValue = packObject })
                     .ToArray());
             }
 
+            foreach (SparseMultiFormatterSpec formatSpec in spec.SparseMultiValueFormatters.OrderBy(x => x.Priority))
+            {
+                Dictionary<string, Value> packedObjects = [];
+                foreach (var reportKey in formatSpec.ReportKeys)
+                {
+                    if (!playReport.AsDictionary().TryGetValue(reportKey, out MessagePackObject valuePackObject))
+                        continue;
+
+                    packedObjects.Add(reportKey, new Value { Application = appMeta, PackedValue = valuePackObject });
+                }
+
+                return formatSpec.Formatter(packedObjects);
+            }
+
             return FormattedValue.Unhandled;
         }
-
-        /// <summary>
-        /// A potential formatted value returned by a <see cref="ValueFormatter"/>.
-        /// </summary>
-        public readonly struct FormattedValue
-        {
-            /// <summary>
-            /// Was any handler able to match anything in the Play Report?
-            /// </summary>
-            public bool Handled { get; private init; }
-
-            /// <summary>
-            /// Did the handler request the caller of the <see cref="Analyzer"/> to reset the existing value?
-            /// </summary>
-            public bool Reset { get; private init; }
-
-            /// <summary>
-            /// The formatted value, only present if <see cref="Handled"/> is true, and <see cref="Reset"/> is false.
-            /// </summary>
-            public string FormattedString { get; private init; }
-
-            /// <summary>
-            /// The intended path of execution for having a string to return: simply return the string.
-            /// This implicit conversion will make the struct for you.<br/><br/>
-            ///
-            /// If the input is null, <see cref="Unhandled"/> is returned.
-            /// </summary>
-            /// <param name="formattedValue">The formatted string value.</param>
-            /// <returns>The automatically constructed <see cref="FormattedValue"/> struct.</returns>
-            public static implicit operator FormattedValue(string formattedValue)
-                => formattedValue is not null 
-                    ? new FormattedValue { Handled = true, FormattedString = formattedValue }
-                    : Unhandled;
-
-            /// <summary>
-            /// Return this to tell the caller there is no value to return.
-            /// </summary>
-            public static FormattedValue Unhandled => default;
-            
-            /// <summary>
-            /// Return this to suggest the caller reset the value it's using the <see cref="Analyzer"/> for.
-            /// </summary>
-            public static FormattedValue ForceReset => new() { Handled = true, Reset = true };
-
-            /// <summary>
-            /// A delegate singleton you can use to always return <see cref="ForceReset"/> in a <see cref="ValueFormatter"/>.
-            /// </summary>
-            public static readonly ValueFormatter AlwaysResets = _ => ForceReset;
-
-            /// <summary>
-            /// A delegate factory you can use to always return the specified
-            /// <paramref name="formattedValue"/> in a <see cref="ValueFormatter"/>.
-            /// </summary>
-            /// <param name="formattedValue">The string to always return for this delegate instance.</param>
-            public static ValueFormatter AlwaysReturns(string formattedValue) => _ => formattedValue;
-        }
     }
-
-    /// <summary>
-    /// A mapping of title IDs to value formatter specs.
-    ///
-    /// <remarks>Generally speaking, use the <see cref="Analyzer"/>.AddSpec(...) methods instead of creating this class yourself.</remarks>
-    /// </summary>
-    public class GameSpec
-    {
-        public required string[] TitleIds { get; init; }
-        public List<FormatterSpec> SimpleValueFormatters { get; } = [];
-        public List<MultiFormatterSpec> MultiValueFormatters { get; } = [];
-
-        /// <summary>
-        /// Add a value formatter to the current <see cref="GameSpec"/>
-        /// matching a specific key that could exist in a Play Report for the previously specified title IDs.
-        /// </summary>
-        /// <param name="reportKey">The key name to match.</param>
-        /// <param name="valueFormatter">The function which can return a potential formatted value.</param>
-        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
-        public GameSpec AddValueFormatter(string reportKey, ValueFormatter valueFormatter)
-        {
-            SimpleValueFormatters.Add(new FormatterSpec
-            {
-                Priority = SimpleValueFormatters.Count, ReportKey = reportKey, ValueFormatter = valueFormatter
-            });
-            return this;
-        }
-
-        /// <summary>
-        /// Add a value formatter at a specific priority to the current <see cref="GameSpec"/>
-        /// matching a specific key that could exist in a Play Report for the previously specified title IDs.
-        /// </summary>
-        /// <param name="priority">The resolution priority of this value formatter. Higher resolves sooner.</param>
-        /// <param name="reportKey">The key name to match.</param>
-        /// <param name="valueFormatter">The function which can return a potential formatted value.</param>
-        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
-        public GameSpec AddValueFormatter(int priority, string reportKey,
-            ValueFormatter valueFormatter)
-        {
-            SimpleValueFormatters.Add(new FormatterSpec
-            {
-                Priority = priority, ReportKey = reportKey, ValueFormatter = valueFormatter
-            });
-            return this;
-        }
-        
-        /// <summary>
-        /// Add a multi-value formatter to the current <see cref="GameSpec"/>
-        /// matching a specific set of keys that could exist in a Play Report for the previously specified title IDs.
-        /// </summary>
-        /// <param name="reportKeys">The key names to match.</param>
-        /// <param name="valueFormatter">The function which can format the values.</param>
-        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
-        public GameSpec AddMultiValueFormatter(string[] reportKeys, MultiValueFormatter valueFormatter)
-        {
-            MultiValueFormatters.Add(new MultiFormatterSpec
-            {
-                Priority = SimpleValueFormatters.Count, ReportKeys = reportKeys, ValueFormatter = valueFormatter
-            });
-            return this;
-        }
-        
-        /// <summary>
-        /// Add a multi-value formatter at a specific priority to the current <see cref="GameSpec"/>
-        /// matching a specific set of keys that could exist in a Play Report for the previously specified title IDs.
-        /// </summary>
-        /// <param name="priority">The resolution priority of this value formatter. Higher resolves sooner.</param>
-        /// <param name="reportKeys">The key names to match.</param>
-        /// <param name="valueFormatter">The function which can format the values.</param>
-        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
-        public GameSpec AddMultiValueFormatter(int priority, string[] reportKeys,
-            MultiValueFormatter valueFormatter)
-        {
-            MultiValueFormatters.Add(new MultiFormatterSpec
-            {
-                Priority = priority, ReportKeys = reportKeys, ValueFormatter = valueFormatter
-            });
-            return this;
-        }
-
-        /// <summary>
-        /// A struct containing the data for a mapping of a key in a Play Report to a formatter for its potential value.
-        /// </summary>
-        public struct FormatterSpec
-        {
-            public required int Priority { get; init; }
-            public required string ReportKey { get; init; }
-            public ValueFormatter ValueFormatter { get; init; }
-        }
-        
-        /// <summary>
-        /// A struct containing the data for a mapping of an arbitrary key set in a Play Report to a formatter for their potential values.
-        /// </summary>
-        public struct MultiFormatterSpec
-        {
-            public required int Priority { get; init; }
-            public required string[] ReportKeys { get; init; }
-            public MultiValueFormatter ValueFormatter { get; init; }
-        }
-    }
-
-    /// <summary>
-    /// The input data to a <see cref="ValueFormatter"/>,
-    /// containing the currently running application's <see cref="ApplicationMetadata"/>,
-    /// and the matched <see cref="MessagePackObject"/> from the Play Report.
-    /// </summary>
-    public class Value
-    {
-        /// <summary>
-        /// The currently running application's <see cref="ApplicationMetadata"/>.
-        /// </summary>
-        public ApplicationMetadata Application { get; init; }
-
-        /// <summary>
-        /// The matched value from the Play Report.
-        /// </summary>
-        public MessagePackObject PackedValue { get; init; }
-
-        /// <summary>
-        /// Access the <see cref="PackedValue"/> as its underlying .NET type.<br/>
-        /// 
-        /// Does not seem to work well with comparing numeric types,
-        /// so use XValue properties for that.
-        /// </summary>
-        public object BoxedValue => PackedValue.ToObject();
-
-        #region AsX accessors
-
-        public bool BooleanValue => PackedValue.AsBoolean();
-        public byte ByteValye => PackedValue.AsByte();
-        public sbyte SByteValye => PackedValue.AsSByte();
-        public short ShortValye => PackedValue.AsInt16();
-        public ushort UShortValye => PackedValue.AsUInt16();
-        public int IntValye => PackedValue.AsInt32();
-        public uint UIntValye => PackedValue.AsUInt32();
-        public long LongValye => PackedValue.AsInt64();
-        public ulong ULongValye => PackedValue.AsUInt64();
-        public float FloatValue => PackedValue.AsSingle();
-        public double DoubleValue => PackedValue.AsDouble();
-        public string StringValue => PackedValue.AsString();
-        public Span<byte> BinaryValue => PackedValue.AsBinary();
-
-        #endregion
-    }
-
-    /// <summary>
-    /// The delegate type that powers single value formatters.<br/>
-    /// Takes in the result value from the Play Report, and outputs:
-    /// <br/>
-    /// a formatted string,
-    /// <br/>
-    /// a signal that nothing was available to handle it,
-    /// <br/>
-    /// OR a signal to reset the value that the caller is using the <see cref="Analyzer"/> for. 
-    /// </summary>
-    public delegate Analyzer.FormattedValue ValueFormatter(Value value);
-    
-    /// <summary>
-    /// The delegate type that powers multiple value formatters.<br/>
-    /// Takes in the result value from the Play Report, and outputs:
-    /// <br/>
-    /// a formatted string,
-    /// <br/>
-    /// a signal that nothing was available to handle it,
-    /// <br/>
-    /// OR a signal to reset the value that the caller is using the <see cref="Analyzer"/> for. 
-    /// </summary>
-    public delegate Analyzer.FormattedValue MultiValueFormatter(Value[] value);
 }

src/Ryujinx/Utilities/PlayReport/Delegates.cs

@@ -0,0 +1,42 @@
+using System.Collections.Generic;
+
+namespace Ryujinx.Ava.Utilities.PlayReport
+{
+    /// <summary>
+    /// The delegate type that powers single value formatters.<br/>
+    /// Takes in the result value from the Play Report, and outputs:
+    /// <br/>
+    /// a formatted string,
+    /// <br/>
+    /// a signal that nothing was available to handle it,
+    /// <br/>
+    /// OR a signal to reset the value that the caller is using the <see cref="Analyzer"/> for. 
+    /// </summary>
+    public delegate FormattedValue ValueFormatter(Value value);
+
+    /// <summary>
+    /// The delegate type that powers multiple value formatters.<br/>
+    /// Takes in the result values from the Play Report, and outputs:
+    /// <br/>
+    /// a formatted string,
+    /// <br/>
+    /// a signal that nothing was available to handle it,
+    /// <br/>
+    /// OR a signal to reset the value that the caller is using the <see cref="Analyzer"/> for. 
+    /// </summary>
+    public delegate FormattedValue MultiValueFormatter(Value[] value);
+
+    /// <summary>
+    /// The delegate type that powers multiple value formatters.
+    /// The dictionary passed to this delegate is sparsely populated;
+    /// that is, not every key specified in the Play Report needs to match for this to be used.<br/>
+    /// Takes in the result values from the Play Report, and outputs:
+    /// <br/>
+    /// a formatted string,
+    /// <br/>
+    /// a signal that nothing was available to handle it,
+    /// <br/>
+    /// OR a signal to reset the value that the caller is using the <see cref="Analyzer"/> for. 
+    /// </summary>
+    public delegate FormattedValue SparseMultiValueFormatter(Dictionary<string, Value> values);
+}

src/Ryujinx/Utilities/PlayReport/PlayReports.cs

@@ -1,6 +1,4 @@
-using static Ryujinx.Ava.Utilities.PlayReport.Analyzer;
-
-namespace Ryujinx.Ava.Utilities.PlayReport
+namespace Ryujinx.Ava.Utilities.PlayReport
 {
     public static class PlayReports
     {
@@ -10,7 +8,7 @@ namespace Ryujinx.Ava.Utilities.PlayReport
                 spec => spec
                     .AddValueFormatter("IsHardMode", BreathOfTheWild_MasterMode)
                     // reset to normal status when switching between normal & master mode in title screen
-                    .AddValueFormatter("AoCVer", FormattedValue.AlwaysResets)
+                    .AddValueFormatter("AoCVer", FormattedValue.SingleAlwaysResets)
             )
             .AddSpec(
                 "0100f2c0115b6000",

src/Ryujinx/Utilities/PlayReport/Specs.cs

@@ -0,0 +1,140 @@
+using FluentAvalonia.Core;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Ryujinx.Ava.Utilities.PlayReport
+{
+    /// <summary>
+    /// A mapping of title IDs to value formatter specs.
+    ///
+    /// <remarks>Generally speaking, use the <see cref="Analyzer"/>.AddSpec(...) methods instead of creating this class yourself.</remarks>
+    /// </summary>
+    public class GameSpec
+    {
+        public required string[] TitleIds { get; init; }
+        public List<FormatterSpec> SimpleValueFormatters { get; } = [];
+        public List<MultiFormatterSpec> MultiValueFormatters { get; } = [];
+        public List<SparseMultiFormatterSpec> SparseMultiValueFormatters { get; } = [];
+
+
+        /// <summary>
+        /// Add a value formatter to the current <see cref="GameSpec"/>
+        /// matching a specific key that could exist in a Play Report for the previously specified title IDs.
+        /// </summary>
+        /// <param name="reportKey">The key name to match.</param>
+        /// <param name="valueFormatter">The function which can return a potential formatted value.</param>
+        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
+        public GameSpec AddValueFormatter(string reportKey, ValueFormatter valueFormatter)
+            => AddValueFormatter(SimpleValueFormatters.Count, reportKey, valueFormatter);
+
+        /// <summary>
+        /// Add a value formatter at a specific priority to the current <see cref="GameSpec"/>
+        /// matching a specific key that could exist in a Play Report for the previously specified title IDs.
+        /// </summary>
+        /// <param name="priority">The resolution priority of this value formatter. Higher resolves sooner.</param>
+        /// <param name="reportKey">The key name to match.</param>
+        /// <param name="valueFormatter">The function which can return a potential formatted value.</param>
+        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
+        public GameSpec AddValueFormatter(int priority, string reportKey,
+            ValueFormatter valueFormatter)
+        {
+            SimpleValueFormatters.Add(new FormatterSpec
+            {
+                Priority = priority, ReportKey = reportKey, Formatter = valueFormatter
+            });
+            return this;
+        }
+
+        /// <summary>
+        /// Add a multi-value formatter to the current <see cref="GameSpec"/>
+        /// matching a specific set of keys that could exist in a Play Report for the previously specified title IDs.
+        /// </summary>
+        /// <param name="reportKeys">The key names to match.</param>
+        /// <param name="valueFormatter">The function which can format the values.</param>
+        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
+        public GameSpec AddMultiValueFormatter(string[] reportKeys, MultiValueFormatter valueFormatter)
+            => AddMultiValueFormatter(MultiValueFormatters.Count, reportKeys, valueFormatter);
+
+        /// <summary>
+        /// Add a multi-value formatter at a specific priority to the current <see cref="GameSpec"/>
+        /// matching a specific set of keys that could exist in a Play Report for the previously specified title IDs.
+        /// </summary>
+        /// <param name="priority">The resolution priority of this value formatter. Higher resolves sooner.</param>
+        /// <param name="reportKeys">The key names to match.</param>
+        /// <param name="valueFormatter">The function which can format the values.</param>
+        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
+        public GameSpec AddMultiValueFormatter(int priority, string[] reportKeys,
+            MultiValueFormatter valueFormatter)
+        {
+            MultiValueFormatters.Add(new MultiFormatterSpec
+            {
+                Priority = priority, ReportKeys = reportKeys, Formatter = valueFormatter
+            });
+            return this;
+        }
+
+        /// <summary>
+        /// Add a multi-value formatter to the current <see cref="GameSpec"/>
+        /// matching a specific set of keys that could exist in a Play Report for the previously specified title IDs.
+        /// <br/><br/>
+        /// The 'Sparse' multi-value formatters do not require every key to be present.
+        /// If you need this requirement, use <see cref="AddMultiValueFormatter(string[], Ryujinx.Ava.Utilities.PlayReport.MultiValueFormatter)"/>.
+        /// </summary>
+        /// <param name="reportKeys">The key names to match.</param>
+        /// <param name="valueFormatter">The function which can format the values.</param>
+        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
+        public GameSpec AddSparseMultiValueFormatter(string[] reportKeys, SparseMultiValueFormatter valueFormatter)
+            => AddSparseMultiValueFormatter(SparseMultiValueFormatters.Count, reportKeys, valueFormatter);
+
+        /// <summary>
+        /// Add a multi-value formatter at a specific priority to the current <see cref="GameSpec"/>
+        /// matching a specific set of keys that could exist in a Play Report for the previously specified title IDs.
+        /// <br/><br/>
+        /// The 'Sparse' multi-value formatters do not require every key to be present.
+        /// If you need this requirement, use <see cref="AddMultiValueFormatter(int, string[], Ryujinx.Ava.Utilities.PlayReport.MultiValueFormatter)"/>.
+        /// </summary>
+        /// <param name="priority">The resolution priority of this value formatter. Higher resolves sooner.</param>
+        /// <param name="reportKeys">The key names to match.</param>
+        /// <param name="valueFormatter">The function which can format the values.</param>
+        /// <returns>The current <see cref="GameSpec"/>, for chaining convenience.</returns>
+        public GameSpec AddSparseMultiValueFormatter(int priority, string[] reportKeys,
+            SparseMultiValueFormatter valueFormatter)
+        {
+            SparseMultiValueFormatters.Add(new SparseMultiFormatterSpec
+            {
+                Priority = priority, ReportKeys = reportKeys, Formatter = valueFormatter
+            });
+            return this;
+        }
+    }
+
+    /// <summary>
+    /// A struct containing the data for a mapping of a key in a Play Report to a formatter for its potential value.
+    /// </summary>
+    public struct FormatterSpec
+    {
+        public required int Priority { get; init; }
+        public required string ReportKey { get; init; }
+        public ValueFormatter Formatter { get; init; }
+    }
+
+    /// <summary>
+    /// A struct containing the data for a mapping of an arbitrary key set in a Play Report to a formatter for their potential values.
+    /// </summary>
+    public struct MultiFormatterSpec
+    {
+        public required int Priority { get; init; }
+        public required string[] ReportKeys { get; init; }
+        public MultiValueFormatter Formatter { get; init; }
+    }
+
+    /// <summary>
+    /// A struct containing the data for a mapping of an arbitrary key set in a Play Report to a formatter for their sparsely populated potential values.
+    /// </summary>
+    public struct SparseMultiFormatterSpec
+    {
+        public required int Priority { get; init; }
+        public required string[] ReportKeys { get; init; }
+        public SparseMultiValueFormatter Formatter { get; init; }
+    }
+}

src/Ryujinx/Utilities/PlayReport/Value.cs

@@ -0,0 +1,130 @@
+using MsgPack;
+using Ryujinx.Ava.Utilities.AppLibrary;
+using System;
+
+namespace Ryujinx.Ava.Utilities.PlayReport
+{
+    /// <summary>
+    /// The input data to a <see cref="ValueFormatter"/>,
+    /// containing the currently running application's <see cref="ApplicationMetadata"/>,
+    /// and the matched <see cref="MessagePackObject"/> from the Play Report.
+    /// </summary>
+    public class Value
+    {
+        /// <summary>
+        /// The currently running application's <see cref="ApplicationMetadata"/>.
+        /// </summary>
+        public ApplicationMetadata Application { get; init; }
+
+        /// <summary>
+        /// The matched value from the Play Report.
+        /// </summary>
+        public MessagePackObject PackedValue { get; init; }
+
+        /// <summary>
+        /// Access the <see cref="PackedValue"/> as its underlying .NET type.<br/>
+        /// 
+        /// Does not seem to work well with comparing numeric types,
+        /// so use XValue properties for that.
+        /// </summary>
+        public object BoxedValue => PackedValue.ToObject();
+
+        public override string ToString()
+        {
+            object boxed = BoxedValue;
+            return boxed == null
+                ? "null"
+                : boxed.ToString();
+        }
+
+        #region AsX accessors
+
+        public bool BooleanValue => PackedValue.AsBoolean();
+        public byte ByteValue => PackedValue.AsByte();
+        public sbyte SByteValue => PackedValue.AsSByte();
+        public short ShortValue => PackedValue.AsInt16();
+        public ushort UShortValue => PackedValue.AsUInt16();
+        public int IntValue => PackedValue.AsInt32();
+        public uint UIntValue => PackedValue.AsUInt32();
+        public long LongValue => PackedValue.AsInt64();
+        public ulong ULongValue => PackedValue.AsUInt64();
+        public float FloatValue => PackedValue.AsSingle();
+        public double DoubleValue => PackedValue.AsDouble();
+        public string StringValue => PackedValue.AsString();
+        public Span<byte> BinaryValue => PackedValue.AsBinary();
+
+        #endregion
+    }
+
+    /// <summary>
+    /// A potential formatted value returned by a <see cref="ValueFormatter"/>.
+    /// </summary>
+    public readonly struct FormattedValue
+    {
+        /// <summary>
+        /// Was any handler able to match anything in the Play Report?
+        /// </summary>
+        public bool Handled { get; private init; }
+
+        /// <summary>
+        /// Did the handler request the caller of the <see cref="Analyzer"/> to reset the existing value?
+        /// </summary>
+        public bool Reset { get; private init; }
+
+        /// <summary>
+        /// The formatted value, only present if <see cref="Handled"/> is true, and <see cref="Reset"/> is false.
+        /// </summary>
+        public string FormattedString { get; private init; }
+
+        /// <summary>
+        /// The intended path of execution for having a string to return: simply return the string.
+        /// This implicit conversion will make the struct for you.<br/><br/>
+        ///
+        /// If the input is null, <see cref="Unhandled"/> is returned.
+        /// </summary>
+        /// <param name="formattedValue">The formatted string value.</param>
+        /// <returns>The automatically constructed <see cref="FormattedValue"/> struct.</returns>
+        public static implicit operator FormattedValue(string formattedValue)
+            => formattedValue is not null
+                ? new FormattedValue { Handled = true, FormattedString = formattedValue }
+                : Unhandled;
+
+        public override string ToString()
+        {
+            if (!Handled)
+                return "<Unhandled>";
+
+            if (Reset)
+                return "<Reset>";
+
+            return FormattedString;
+        }
+
+        /// <summary>
+        /// Return this to tell the caller there is no value to return.
+        /// </summary>
+        public static FormattedValue Unhandled => default;
+
+        /// <summary>
+        /// Return this to suggest the caller reset the value it's using the <see cref="Analyzer"/> for.
+        /// </summary>
+        public static FormattedValue ForceReset => new() { Handled = true, Reset = true };
+
+        /// <summary>
+        /// A delegate singleton you can use to always return <see cref="ForceReset"/> in a <see cref="ValueFormatter"/>.
+        /// </summary>
+        public static readonly ValueFormatter SingleAlwaysResets = _ => ForceReset;
+
+        /// <summary>
+        /// A delegate singleton you can use to always return <see cref="ForceReset"/> in a <see cref="MultiValueFormatter"/>.
+        /// </summary>
+        public static readonly MultiValueFormatter MultiAlwaysResets = _ => ForceReset;
+
+        /// <summary>
+        /// A delegate factory you can use to always return the specified
+        /// <paramref name="formattedValue"/> in a <see cref="ValueFormatter"/>.
+        /// </summary>
+        /// <param name="formattedValue">The string to always return for this delegate instance.</param>
+        public static ValueFormatter AlwaysReturns(string formattedValue) => _ => formattedValue;
+    }
+}