Merge 6d78e71fc7 into fafb99c702

Even if it does, worst case scenario the compat list that pops up has no results.

Directory.Packages.props

@@ -3,6 +3,7 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
   </PropertyGroup>
   <ItemGroup>
+    <PackageVersion Include="Alimer.Bindings.SDL" Version="3.7.1" />
     <PackageVersion Include="Avalonia" Version="11.0.13" />
     <PackageVersion Include="Avalonia.Controls.DataGrid" Version="11.0.13" />
     <PackageVersion Include="Avalonia.Desktop" Version="11.0.13" />

Ryujinx.sln

@@ -75,6 +75,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ryujinx.Horizon", "src\Ryuj
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ryujinx.Horizon.Kernel.Generators", "src\Ryujinx.Horizon.Kernel.Generators\Ryujinx.Horizon.Kernel.Generators.csproj", "{7F55A45D-4E1D-4A36-ADD3-87F29A285AA2}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Ryujinx.Input.SDL3", "src\Ryujinx.Input.SDL3\Ryujinx.Input.SDL3.csproj", "{3BF24278-547D-42C2-9D43-182B978F54DD}"
+EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ryujinx.HLE.Generators", "src\Ryujinx.HLE.Generators\Ryujinx.HLE.Generators.csproj", "{B575BCDE-2FD8-4A5D-8756-31CDD7FE81F0}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Ryujinx.Graphics.Metal", "src\Ryujinx.Graphics.Metal\Ryujinx.Graphics.Metal.csproj", "{C08931FA-1191-417A-864F-3882D93E683B}"
@@ -259,6 +261,10 @@ Global
 		{81EA598C-DBA1-40B0-8DA4-4796B78F2037}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{81EA598C-DBA1-40B0-8DA4-4796B78F2037}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{81EA598C-DBA1-40B0-8DA4-4796B78F2037}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3BF24278-547D-42C2-9D43-182B978F54DD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3BF24278-547D-42C2-9D43-182B978F54DD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3BF24278-547D-42C2-9D43-182B978F54DD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3BF24278-547D-42C2-9D43-182B978F54DD}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

src/Ryujinx.Common/Configuration/Hid/Controller/Motion/JsonMotionConfigControllerConverter.cs

@@ -56,6 +56,7 @@ namespace Ryujinx.Common.Configuration.Hid.Controller.Motion
             return motionBackendType switch
             {
                 MotionInputBackendType.GamepadDriver => JsonSerializer.Deserialize(ref reader, _serializerContext.StandardMotionConfigController),
+                MotionInputBackendType.Handheld => JsonSerializer.Deserialize(ref reader, _serializerContext.StandardMotionConfigController),
                 MotionInputBackendType.CemuHook => JsonSerializer.Deserialize(ref reader, _serializerContext.CemuHookMotionConfigController),
                 _ => throw new InvalidOperationException($"Unknown backend type {motionBackendType}"),
             };
@@ -66,6 +67,7 @@ namespace Ryujinx.Common.Configuration.Hid.Controller.Motion
             switch (value.MotionBackend)
             {
                 case MotionInputBackendType.GamepadDriver:
+                case MotionInputBackendType.Handheld:
                     JsonSerializer.Serialize(writer, value as StandardMotionConfigController, _serializerContext.StandardMotionConfigController);
                     break;
                 case MotionInputBackendType.CemuHook:

src/Ryujinx.Common/Configuration/Hid/Controller/Motion/MotionInputBackendType.cs

@@ -9,5 +9,6 @@ namespace Ryujinx.Common.Configuration.Hid.Controller.Motion
         Invalid,
         GamepadDriver,
         CemuHook,
+        Handheld,
     }
 }

src/Ryujinx.Input.SDL3/Ryujinx.Input.SDL3.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Ryujinx.Input\Ryujinx.Input.csproj" />
+    <PackageReference Include="Alimer.Bindings.SDL" />
+  </ItemGroup>
+
+</Project>

src/Ryujinx.Input.SDL3/SDL3MotionDriver.cs

@@ -0,0 +1,85 @@
+using SDL3;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Numerics;
+using static SDL3.SDL3;
+
+namespace Ryujinx.Input.SDL3
+{
+    public unsafe class SDL3MotionDriver : IHandheld, IDisposable
+    {
+        private readonly Dictionary<SDL_SensorType, SDL_Sensor> sensors;
+        private bool _disposed;
+
+        public SDL3MotionDriver()
+        {
+            int result = SDL_Init(SDL_InitFlags.Sensor);
+            if (result < 0)
+            {
+                throw new InvalidOperationException($"SDL sensor initialization failed: {SDL_GetError()}");
+            }
+            sensors = SDL_GetSensors().ToArray().ToDictionary(SDL_GetSensorTypeForID, SDL_OpenSensor);
+        }
+
+        ~SDL3MotionDriver()
+        {
+            Dispose(false);
+        }
+
+        public void Dispose()
+        {
+            Dispose(true);
+            GC.SuppressFinalize(this);
+        }
+
+        protected virtual void Dispose(bool disposing)
+        {
+            if (_disposed)
+            {
+                return;
+            }
+
+            if (disposing && sensors != null)
+            {
+                foreach (var sensor in sensors.Values)
+                {
+                    if (sensor != IntPtr.Zero)
+                    {
+                        SDL_CloseSensor(sensor);
+                    }
+                }
+            }
+
+            _disposed = true;
+        }
+
+        public Vector3 GetMotionData(MotionInputId inputType)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+
+            return inputType switch
+            {
+                MotionInputId.Gyroscope => GetSensorVector(SDL_SensorType.Gyro) * 180 / MathF.PI,
+                MotionInputId.Accelerometer => GetSensorVector(SDL_SensorType.Accel) / SDL_STANDARD_GRAVITY,
+                _ => Vector3.Zero
+            };
+        }
+
+        private Vector3 GetSensorVector(SDL_SensorType sensorType)
+        {
+            if (!sensors.TryGetValue(sensorType, out SDL_Sensor sensor))
+            {
+                return Vector3.Zero;
+            }
+
+            var data = stackalloc float[3];
+            if (SDL_GetSensorData(sensor, data, 3) < 0)
+            {
+                return Vector3.Zero;
+            }
+
+            return new Vector3(data[0], data[1], data[2]);
+        }
+    }
+}

src/Ryujinx.Input/HLE/InputManager.cs

@@ -2,12 +2,13 @@ using System;
 
 namespace Ryujinx.Input.HLE
 {
-    public class InputManager(IGamepadDriver keyboardDriver, IGamepadDriver gamepadDriver)
+    public class InputManager(IGamepadDriver keyboardDriver, IGamepadDriver gamepadDriver, IHandheld handheld)
         : IDisposable
     {
         public IGamepadDriver KeyboardDriver { get; } = keyboardDriver;
         public IGamepadDriver GamepadDriver { get; } = gamepadDriver;
         public IGamepadDriver MouseDriver { get; private set; }
+        public IHandheld Handheld { get; } = handheld;
 
         public void SetMouseDriver(IGamepadDriver mouseDriver)
         {
@@ -18,7 +19,7 @@ namespace Ryujinx.Input.HLE
 
         public NpadManager CreateNpadManager()
         {
-            return new NpadManager(KeyboardDriver, GamepadDriver, MouseDriver);
+            return new NpadManager(KeyboardDriver, GamepadDriver, MouseDriver, Handheld);
         }
 
         public TouchScreenManager CreateTouchScreenManager()
@@ -38,6 +39,7 @@ namespace Ryujinx.Input.HLE
                 KeyboardDriver?.Dispose();
                 GamepadDriver?.Dispose();
                 MouseDriver?.Dispose();
+                Handheld?.Dispose();
             }
         }
 

src/Ryujinx.Input/HLE/NpadController.cs

@@ -218,12 +218,14 @@ namespace Ryujinx.Input.HLE
         public string Id { get; private set; }
 
         private readonly CemuHookClient _cemuHookClient;
+        private readonly IHandheld _handheld;
 
-        public NpadController(CemuHookClient cemuHookClient)
+        public NpadController(CemuHookClient cemuHookClient, IHandheld handheld)
         {
             State = default;
             Id = null;
             _cemuHookClient = cemuHookClient;
+            _handheld = handheld;
         }
 
         public bool UpdateDriverConfiguration(IGamepadDriver gamepadDriver, InputConfig config)
@@ -287,6 +289,18 @@ namespace Ryujinx.Input.HLE
 
                 if (_config is StandardControllerInputConfig controllerConfig && controllerConfig.Motion.EnableMotion)
                 {
+                    if (controllerConfig.Motion.MotionBackend == MotionInputBackendType.Handheld)
+                    {
+                        Vector3 accelerometer = _handheld.GetMotionData(MotionInputId.Accelerometer);
+                        Vector3 gyroscope = _handheld.GetMotionData(MotionInputId.Gyroscope);
+
+                        accelerometer = new Vector3(accelerometer.X, -accelerometer.Z, accelerometer.Y);
+                        gyroscope = new Vector3(gyroscope.X, -gyroscope.Z, gyroscope.Y);
+
+                        _leftMotionInput.Update(accelerometer, gyroscope, (ulong)PerformanceCounter.ElapsedNanoseconds / 1000, controllerConfig.Motion.Sensitivity, (float)controllerConfig.Motion.GyroDeadzone);
+                        _rightMotionInput = _leftMotionInput;
+                    }
+
                     if (controllerConfig.Motion.MotionBackend == MotionInputBackendType.GamepadDriver)
                     {
                         if (gamepad.Features.HasFlag(GamepadFeaturesFlag.Motion))

src/Ryujinx.Input/HLE/NpadManager.cs

@@ -31,6 +31,7 @@ namespace Ryujinx.Input.HLE
         private readonly IGamepadDriver _keyboardDriver;
         private readonly IGamepadDriver _gamepadDriver;
         private readonly IGamepadDriver _mouseDriver;
+        private readonly IHandheld _handheld;
         private bool _isDisposed;
 
         private List<InputConfig> _inputConfig;
@@ -38,7 +39,7 @@ namespace Ryujinx.Input.HLE
         private bool _enableMouse;
         private Switch _device;
 
-        public NpadManager(IGamepadDriver keyboardDriver, IGamepadDriver gamepadDriver, IGamepadDriver mouseDriver)
+        public NpadManager(IGamepadDriver keyboardDriver, IGamepadDriver gamepadDriver, IGamepadDriver mouseDriver, IHandheld handheld)
         {
             _controllers = new NpadController[MaxControllers];
             _cemuHookClient = new CemuHookClient(this);
@@ -47,6 +48,7 @@ namespace Ryujinx.Input.HLE
             _gamepadDriver = gamepadDriver;
             _mouseDriver = mouseDriver;
             _inputConfig = [];
+            _handheld = handheld;
 
             _gamepadDriver.OnGamepadConnected += HandleOnGamepadConnected;
             _gamepadDriver.OnGamepadDisconnected += HandleOnGamepadDisconnected;
@@ -139,7 +141,7 @@ namespace Ryujinx.Input.HLE
                     }
                     else
                     {
-                        controller = new(_cemuHookClient);
+                        controller = new(_cemuHookClient, _handheld);
                     }
 
                     bool isValid = DriverConfigurationUpdate(ref controller, inputConfigEntry);

src/Ryujinx.Input/IHandheld.cs

@@ -0,0 +1,10 @@
+using System;
+using System.Numerics;
+
+namespace Ryujinx.Input
+{
+    public interface IHandheld : IDisposable
+    {
+        Vector3 GetMotionData(MotionInputId gyroscope);
+    }
+}

src/Ryujinx/Assets/locales.json

@@ -2522,6 +2522,56 @@
         "zh_TW": "在 macOS 的應用程式資料夾中建立捷徑，啟動選取的應用程式"
       }
     },
+    {
+      "ID": "GameListContextMenuShowCompatEntry",
+      "Translations": {
+        "ar_SA": "",
+        "de_DE": "",
+        "el_GR": "",
+        "en_US": "Show Compatibility Entry",
+        "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": "GameListContextMenuShowCompatEntryToolTip",
+      "Translations": {
+        "ar_SA": "",
+        "de_DE": "",
+        "el_GR": "",
+        "en_US": "Show the selected game in the Compatibility List you can normally access via the Help menu.",
+        "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": "GameListContextMenuOpenModsDirectory",
       "Translations": {
@@ -7522,6 +7572,31 @@
         "zh_TW": "使用與 CemuHook 相容的體感"
       }
     },
+    {
+      "ID": "ControllerSettingsMotionUseHandheldCompatibleMotion",
+      "Translations": {
+        "ar_SA": "استخدام الحركة المتوافقة مع Hendheld",
+        "de_DE": "Hendheld kompatible Bewegungssteuerung",
+        "el_GR": "Κίνηση συμβατή με Hendheld",
+        "en_US": "Use Hendheld compatible motion",
+        "es_ES": "Usar movimiento compatible con Hendheld",
+        "fr_FR": "Utiliser un capteur de mouvements Hendheld",
+        "he_IL": "השתמש בתנועת Hendheld תואמת ",
+        "it_IT": "Usa sensore compatibile con Hendheld",
+        "ja_JP": "Hendheld 互換モーションを使用",
+        "ko_KR": "Hendheld 호환 모션 사용",
+        "no_NO": "Bruk Hendheld kompatibel bevegelse",
+        "pl_PL": "Użyj ruchu zgodnego z Hendheld",
+        "pt_BR": "Usar sensor compatível com Hendheld",
+        "ru_RU": "Включить совместимость с Hendheld",
+        "sv_SE": "Använd Hendheld-kompatibel rörelse",
+        "th_TH": "ใช้การเคลื่อนไหวที่เข้ากันได้กับ Hendheld",
+        "tr_TR": "Hendheld uyumlu hareket kullan",
+        "uk_UA": "Використовувати рух, сумісний з Hendheld",
+        "zh_CN": "使用 Hendheld 兼容的体感协议",
+        "zh_TW": "使用與 Hendheld 相容的體感"
+      }
+    },
     {
       "ID": "ControllerSettingsMotionControllerSlot",
       "Translations": {
@@ -23198,4 +23273,4 @@
       }
     }
   ]
-}
+}

src/Ryujinx/DiscordIntegrationModule.cs

@@ -117,11 +117,6 @@ namespace Ryujinx.Ava
             _currentApp = appMeta;
         }
 
-        private static void UpdatePlayingState()
-        {
-            _discordClient?.SetPresence(_discordPresencePlaying);
-        }
-
         private static void SwitchToMainState()
         {
             _discordClient?.SetPresence(_discordPresenceMain);
@@ -135,21 +130,20 @@ namespace Ryujinx.Ava
             if (!TitleIDs.CurrentApplication.Value.HasValue) return;
             if (_discordPresencePlaying is null) return;
 
-            PlayReportFormattedValue value = PlayReport.Analyzer.Run(TitleIDs.CurrentApplication.Value, _currentApp, playReport);
+            PlayReportAnalyzer.FormattedValue formattedValue =
+                PlayReport.Analyzer.Format(TitleIDs.CurrentApplication.Value, _currentApp, playReport);
 
-            if (!value.Handled) return;
+            if (!formattedValue.Handled) return;
 
-            if (value.Reset)
+            _discordPresencePlaying.Details = formattedValue.Reset 
-            {
+                ? $"Playing {_currentApp.Title}" 
-                _discordPresencePlaying.Details = $"Playing {_currentApp.Title}";
+                : formattedValue.FormattedString;
-                Logger.Info?.Print(LogClass.UI, "Reset Discord RPC based on a supported play report value formatter.");
+
-            }
+            if (_discordClient.CurrentPresence.Details.Equals(_discordPresencePlaying.Details))
-            else
+                return; //don't trigger an update if the set presence Details are identical to current
-            {
+
-                _discordPresencePlaying.Details = value.FormattedString;
+            _discordClient.SetPresence(_discordPresencePlaying);
-                Logger.Info?.Print(LogClass.UI, "Updated Discord RPC based on a supported play report.");
+            Logger.Info?.Print(LogClass.UI, "Updated Discord RPC based on a supported play report.");
-            }
-            UpdatePlayingState();
         }
 
         private static string TruncateToByteLength(string input)

src/Ryujinx/Headless/HeadlessRyujinx.cs

@@ -23,6 +23,7 @@ using Ryujinx.HLE.HOS.Services.Account.Acc;
 using Ryujinx.Input;
 using Ryujinx.Input.HLE;
 using Ryujinx.Input.SDL2;
+using Ryujinx.Input.SDL3;
 using Ryujinx.SDL2.Common;
 using System;
 using System.Collections.Generic;
@@ -182,7 +183,7 @@ namespace Ryujinx.Headless
             _accountManager = new AccountManager(_libHacHorizonManager.RyujinxClient, option.UserProfile);
             _userChannelPersistence = new UserChannelPersistence();
 
-            _inputManager = new InputManager(new SDL2KeyboardDriver(), new SDL2GamepadDriver());
+            _inputManager = new InputManager(new SDL2KeyboardDriver(), new SDL2GamepadDriver(), new SDL3MotionDriver());
 
             GraphicsConfig.EnableShaderCache = !option.DisableShaderCache;
 

src/Ryujinx/Ryujinx.csproj

@@ -76,6 +76,7 @@
     <ProjectReference Include="..\Ryujinx.Graphics.Metal\Ryujinx.Graphics.Metal.csproj" />
     <ProjectReference Include="..\Ryujinx.Input\Ryujinx.Input.csproj" />
     <ProjectReference Include="..\Ryujinx.Input.SDL2\Ryujinx.Input.SDL2.csproj" />
+    <ProjectReference Include="..\Ryujinx.Input.SDL3\Ryujinx.Input.SDL3.csproj" />
     <ProjectReference Include="..\Ryujinx.Audio.Backends.OpenAL\Ryujinx.Audio.Backends.OpenAL.csproj" />
     <ProjectReference Include="..\Ryujinx.Audio.Backends.SoundIo\Ryujinx.Audio.Backends.SoundIo.csproj" />
     <ProjectReference Include="..\Ryujinx.Common\Ryujinx.Common.csproj" />

src/Ryujinx/UI/Controls/ApplicationContextMenu.axaml

@@ -19,6 +19,12 @@
         Header="{ext:Locale GameListContextMenuCreateShortcut}"
         Icon="{ext:Icon fa-solid fa-bookmark}"
         ToolTip.Tip="{OnPlatform Default={ext:Locale GameListContextMenuCreateShortcutToolTip}, macOS={ext:Locale GameListContextMenuCreateShortcutToolTipMacOS}}" />
+    <MenuItem
+        IsVisible="{Binding HasCompatibilityEntry}"
+        Click="OpenApplicationCompatibility_Click"
+        Header="{ext:Locale GameListContextMenuShowCompatEntry}"
+        Icon="{ext:Icon mdi-gamepad}"
+        ToolTip.Tip="{ext:Locale GameListContextMenuShowCompatEntryToolTip}"/>
     <Separator />
     <MenuItem
         Click="OpenUserSaveDirectory_Click"
@@ -74,7 +80,6 @@
 		Header="{ext:Locale GameListContextMenuTrimXCI}"
         IsEnabled="{Binding TrimXCIEnabled}"
 		ToolTip.Tip="{ext:Locale GameListContextMenuTrimXCIToolTip}" />
-    <Separator />
     <MenuItem Header="{ext:Locale GameListContextMenuCacheManagement}" Icon="{ext:Icon mdi-cached}">
         <MenuItem
             Click="PurgePtcCache_Click"

src/Ryujinx/UI/Controls/ApplicationContextMenu.axaml.cs

@@ -12,6 +12,7 @@ using Ryujinx.Ava.UI.ViewModels;
 using Ryujinx.Ava.UI.Windows;
 using Ryujinx.Ava.Utilities;
 using Ryujinx.Ava.Utilities.AppLibrary;
+using Ryujinx.Ava.Utilities.Compat;
 using Ryujinx.Common.Configuration;
 using Ryujinx.Common.Helper;
 using Ryujinx.HLE.HOS;
@@ -385,6 +386,12 @@ namespace Ryujinx.Ava.UI.Controls
                     viewModel.SelectedApplication.Icon
                 );
         }
+        
+        public async void OpenApplicationCompatibility_Click(object sender, RoutedEventArgs args)
+        {
+            if (sender is MenuItem { DataContext: MainWindowViewModel { SelectedApplication: not null } viewModel })
+                await CompatibilityList.Show(viewModel.SelectedApplication.IdString);
+        }
 
         public async void RunApplication_Click(object sender, RoutedEventArgs args)
         {

src/Ryujinx/UI/Controls/ApplicationListView.axaml

@@ -86,13 +86,29 @@
                                             Text="{Binding Version}"
                                             TextAlignment="Start"
                                             TextWrapping="Wrap" />
-                                        <TextBlock
+                                        <Button 
+                                            Click="PlayabilityStatus_OnClick" 
+                                            HorizontalContentAlignment="Left"
+                                            VerticalAlignment="Center"
                                             IsVisible="{Binding HasPlayabilityInfo}"
-                                            HorizontalAlignment="Stretch"
+                                            Background="{DynamicResource AppListBackgroundColor}"
-                                            Text="{Binding LocalizedStatus}"
+                                            Margin="-1, 0, 0, 0"
-                                            Foreground="{Binding PlayabilityStatus, Converter={x:Static helpers:PlayabilityStatusConverter.Shared}}"
+                                            Padding="0" >
-                                            TextAlignment="Start"
+                                            <TextBlock
-                                            TextWrapping="Wrap" />
+                                                Margin="1.5"
+                                                Tag="{Binding IdString}"
+                                                Text="{Binding LocalizedStatus}"
+                                                Foreground="{Binding PlayabilityStatus, Converter={x:Static helpers:PlayabilityStatusConverter.Shared}}"
+                                                TextAlignment="Start"
+                                                TextWrapping="Wrap" />
+                                            <Button.Styles>
+                                                <Style Selector="Button">
+                                                    <Setter Property="MinWidth"
+                                                            Value="0" /> 
+                                <!-- avoids very wide buttons from the overall project avalonia style -->
+                                                </Style>
+                                            </Button.Styles>
+                                        </Button>
                                     </StackPanel>
                                 </Border>
                                 <StackPanel

src/Ryujinx/UI/Controls/ApplicationListView.axaml.cs

@@ -5,7 +5,9 @@ using Avalonia.Interactivity;
 using Ryujinx.Ava.UI.Helpers;
 using Ryujinx.Ava.UI.ViewModels;
 using Ryujinx.Ava.Utilities.AppLibrary;
+using Ryujinx.Ava.Utilities.Compat;
 using System;
+using System.Globalization;
 using System.Linq;
 
 namespace Ryujinx.Ava.UI.Controls
@@ -28,6 +30,17 @@ namespace Ryujinx.Ava.UI.Controls
             if (sender is ListBox { SelectedItem: ApplicationData selected })
                 RaiseEvent(new ApplicationOpenedEventArgs(selected, ApplicationOpenedEvent));
         }
+        
+        private async void PlayabilityStatus_OnClick(object sender, RoutedEventArgs e)
+        {
+            if (DataContext is not MainWindowViewModel mwvm)
+                return;
+            
+            if (sender is not Button { Content: TextBlock playabilityLabel })
+                return;
+
+            await CompatibilityList.Show((string)playabilityLabel.Tag);
+        }
 
         private async void IdString_OnClick(object sender, RoutedEventArgs e)
         {

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

@@ -10,6 +10,7 @@ namespace Ryujinx.Ava.UI.Models.Input
     public partial class GamepadInputConfig : BaseModel
     {
         public bool EnableCemuHookMotion { get; set; }
+        public bool EnableHandheldMotion { get; set; }
         public string DsuServerHost { get; set; }
         public int DsuServerPort { get; set; }
         public int Slot { get; set; }
@@ -162,7 +163,7 @@ namespace Ryujinx.Ava.UI.Models.Input
                     EnableMotion = controllerInput.Motion.EnableMotion;
                     GyroDeadzone = controllerInput.Motion.GyroDeadzone;
                     Sensitivity = controllerInput.Motion.Sensitivity;
-
+                    EnableHandheldMotion = controllerInput.Motion.MotionBackend == MotionInputBackendType.Handheld;
                     if (controllerInput.Motion is CemuHookMotionConfigController cemuHook)
                     {
                         EnableCemuHookMotion = true;
@@ -285,7 +286,7 @@ namespace Ryujinx.Ava.UI.Models.Input
                 config.Motion = new StandardMotionConfigController
                 {
                     EnableMotion = EnableMotion,
-                    MotionBackend = MotionInputBackendType.GamepadDriver,
+                    MotionBackend = EnableHandheldMotion ? MotionInputBackendType.Handheld : MotionInputBackendType.GamepadDriver,
                     GyroDeadzone = GyroDeadzone,
                     Sensitivity = Sensitivity,
                 };

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

@@ -18,6 +18,34 @@ namespace Ryujinx.Ava.UI.ViewModels.Input
 
         [ObservableProperty] private double _gyroDeadzone;
 
-        [ObservableProperty] private bool _enableCemuHookMotion;
+        private bool _enableCemuHookMotion;
+        public bool EnableCemuHookMotion
+        {
+            get => _enableCemuHookMotion;
+            set
+            {
+                if (value)
+                {
+                    EnableHandheldMotion = false;
+                }
+                _enableCemuHookMotion = value;
+                OnPropertyChanged();
+            }
+        }
+
+        private bool _enableHandheldMotion;
+        public bool EnableHandheldMotion
+        {
+            get => _enableHandheldMotion;
+            set
+            {
+                if (value)
+                {
+                    EnableCemuHookMotion = false;
+                }
+                _enableHandheldMotion = value;
+                OnPropertyChanged();
+            }
+        }
     }
 }

src/Ryujinx/UI/ViewModels/MainWindowViewModel.cs

@@ -349,6 +349,17 @@ namespace Ryujinx.Ava.UI.ViewModels
             }
         }
 
+        public bool HasCompatibilityEntry
+        {
+            get
+            {
+                DynamicData.Kernel.Optional<ApplicationData> appData =
+                    ApplicationLibrary.Applications.Lookup(SelectedApplication.Id);
+
+                return appData.HasValue && appData.Value.HasPlayabilityInfo;
+            }
+        }
+
         public bool OpenUserSaveDirectoryEnabled => SelectedApplication.HasControlHolder && SelectedApplication.ControlHolder.Value.UserAccountSaveDataSize > 0;
 
         public bool OpenDeviceSaveDirectoryEnabled => SelectedApplication.HasControlHolder && SelectedApplication.ControlHolder.Value.DeviceSaveDataSize > 0;

src/Ryujinx/UI/Views/Input/MotionInputView.axaml

@@ -61,6 +61,17 @@
                     Margin="5, 0"
                     Text="{Binding GyroDeadzone, StringFormat=\{0:0.00\}}" />
             </StackPanel>
+            <Separator
+                Height="1"
+                Margin="0,5" />
+            <CheckBox
+                Margin="5"
+                IsChecked="{Binding EnableHandheldMotion}">
+                <TextBlock
+                    Margin="0,3,0,0"
+                    VerticalAlignment="Center"
+                    Text="{ext:Locale ControllerSettingsMotionUseHandheldCompatibleMotion}" />
+            </CheckBox>
             <Separator
                 Height="1"
                 Margin="0,5" />

src/Ryujinx/UI/Views/Input/MotionInputView.axaml.cs

@@ -30,6 +30,7 @@ namespace Ryujinx.Ava.UI.Views.Input
                 Sensitivity = config.Sensitivity,
                 GyroDeadzone = config.GyroDeadzone,
                 EnableCemuHookMotion = config.EnableCemuHookMotion,
+                EnableHandheldMotion = config.EnableHandheldMotion,
             };
 
             InitializeComponent();
@@ -58,6 +59,7 @@ namespace Ryujinx.Ava.UI.Views.Input
                 config.DsuServerHost = content._viewModel.DsuServerHost;
                 config.DsuServerPort = content._viewModel.DsuServerPort;
                 config.EnableCemuHookMotion = content._viewModel.EnableCemuHookMotion;
+                config.EnableHandheldMotion = content._viewModel.EnableHandheldMotion;
                 config.MirrorInput = content._viewModel.MirrorInput;
             };
 

src/Ryujinx/UI/Views/Main/MainMenuBarView.axaml.cs

@@ -50,7 +50,7 @@ namespace Ryujinx.Ava.UI.Views.Main
             UninstallFileTypesMenuItem.Command = Commands.Create(UninstallFileTypes);
             XciTrimmerMenuItem.Command = Commands.Create(XCITrimmerWindow.Show);
             AboutWindowMenuItem.Command = Commands.Create(AboutWindow.Show);
-            CompatibilityListMenuItem.Command = Commands.Create(CompatibilityList.Show);
+            CompatibilityListMenuItem.Command = Commands.Create(() => CompatibilityList.Show());
             
             UpdateMenuItem.Command = Commands.Create(async () =>
             {

src/Ryujinx/UI/Windows/MainWindow.axaml.cs

@@ -29,6 +29,7 @@ using Ryujinx.HLE.HOS;
 using Ryujinx.HLE.HOS.Services.Account.Acc;
 using Ryujinx.Input.HLE;
 using Ryujinx.Input.SDL2;
+using Ryujinx.Input.SDL3;
 using System;
 using System.Collections.Generic;
 using System.Linq;
@@ -107,7 +108,7 @@ namespace Ryujinx.Ava.UI.Windows
 
             if (Program.PreviewerDetached)
             {
-                InputManager = new InputManager(new AvaloniaKeyboardDriver(this), new SDL2GamepadDriver());
+                InputManager = new InputManager(new AvaloniaKeyboardDriver(this), new SDL2GamepadDriver(), new SDL3MotionDriver());
 
                 _ = this.GetObservable(IsActiveProperty).Subscribe(it => ViewModel.IsActive = it);
                 this.ScalingChanged += OnScalingChanged;

src/Ryujinx/Utilities/AppLibrary/ApplicationLibrary.cs

@@ -135,6 +135,14 @@ namespace Ryujinx.Ava.Utilities.AppLibrary
             return id.ToString("X16");
         }
 
+        public bool FindApplication(ulong id, out ApplicationData foundData)
+        {
+            DynamicData.Kernel.Optional<ApplicationData> appData = Applications.Lookup(id);
+            foundData = appData.HasValue ? appData.Value : null;
+
+            return appData.HasValue;
+        }
+
         /// <exception cref="LibHac.Common.Keys.MissingKeyException">The configured key set is missing a key.</exception>
         /// <exception cref="InvalidDataException">The NCA header could not be decrypted.</exception>
         /// <exception cref="NotSupportedException">The NCA version is not supported.</exception>

src/Ryujinx/Utilities/Compat/CompatibilityCsv.cs

@@ -113,20 +113,17 @@ namespace Ryujinx.Ava.Utilities.Compat
             .Select(FormatLabelName)
             .JoinToString(", ");
 
-        public override string ToString()
+        public override string ToString() =>
-        {
+            new StringBuilder("CompatibilityEntry: {")
-            StringBuilder sb = new("CompatibilityEntry: {");
+                .Append($"{nameof(GameName)}=\"{GameName}\", ")
-            sb.Append($"{nameof(GameName)}=\"{GameName}\", ");
+                .Append($"{nameof(TitleId)}={TitleId}, ")
-            sb.Append($"{nameof(TitleId)}={TitleId}, ");
+                .Append($"{nameof(Labels)}={
-            sb.Append($"{nameof(Labels)}={
+                    Labels.FormatCollection(it => $"\"{it}\"", separator: ", ", prefix: "[", suffix: "]")
-                Labels.FormatCollection(it => $"\"{it}\"", separator: ", ", prefix: "[", suffix: "]")
+                }, ")
-            }, ");
+                .Append($"{nameof(Status)}=\"{Status}\", ")
-            sb.Append($"{nameof(Status)}=\"{Status}\", ");
+                .Append($"{nameof(LastUpdated)}=\"{LastUpdated}\"")
-            sb.Append($"{nameof(LastUpdated)}=\"{LastUpdated}\"");
+                .Append('}')
-            sb.Append('}');
+                .ToString();
-
-            return sb.ToString();
-        }
 
         public static string FormatLabelName(string labelName) => labelName.ToLower() switch
         {

src/Ryujinx/Utilities/Compat/CompatibilityList.axaml

@@ -34,7 +34,7 @@
                 Text="{ext:Locale CompatibilityListWarning}" />
         </Grid>
         <Grid Grid.Row="1" ColumnDefinitions="*,Auto,Auto">
-            <TextBox Grid.Column="0" HorizontalAlignment="Stretch" Watermark="{ext:Locale CompatibilityListSearchBoxWatermark}" TextChanged="TextBox_OnTextChanged" />
+            <TextBox Name="SearchBox" Grid.Column="0" HorizontalAlignment="Stretch" Watermark="{ext:Locale CompatibilityListSearchBoxWatermark}" TextChanged="TextBox_OnTextChanged" />
             <CheckBox Grid.Column="1" Margin="7, 0, 0, 0" IsChecked="{Binding OnlyShowOwnedGames}" />
             <TextBlock Grid.Column="2" Margin="-10, 0, 0, 0" Text="{ext:Locale CompatibilityListOnlyShowOwnedGames}" />
         </Grid>

src/Ryujinx/Utilities/Compat/CompatibilityList.axaml.cs

@@ -9,7 +9,7 @@ namespace Ryujinx.Ava.Utilities.Compat
 {
     public partial class CompatibilityList : UserControl
     {
-        public static async Task Show()
+        public static async Task Show(string titleId = null)
         {
             ContentDialog contentDialog = new()
             {
@@ -18,7 +18,10 @@ namespace Ryujinx.Ava.Utilities.Compat
                 CloseButtonText = LocaleManager.Instance[LocaleKeys.SettingsButtonClose],
                 Content = new CompatibilityList
                 {
-                    DataContext = new CompatibilityViewModel(RyujinxApp.MainWindow.ViewModel.ApplicationLibrary)
+                    DataContext = new CompatibilityViewModel(RyujinxApp.MainWindow.ViewModel.ApplicationLibrary), 
+                    SearchBox = {
+                        Text = titleId ?? ""
+                    }
                 }
             };
 

src/Ryujinx/Utilities/PlayReport.cs

@@ -1,10 +1,4 @@
-using Gommon;
+using PlayReportFormattedValue = Ryujinx.Ava.Utilities.PlayReportAnalyzer.FormattedValue;
-using MsgPack;
-using Ryujinx.Ava.Utilities.AppLibrary;
-using Ryujinx.Common.Helper;
-using System;
-using System.Collections.Generic;
-using System.Linq;
 
 namespace Ryujinx.Ava.Utilities
 {
@@ -13,7 +7,10 @@ namespace Ryujinx.Ava.Utilities
         public static PlayReportAnalyzer Analyzer { get; } = new PlayReportAnalyzer()
             .AddSpec(
                 "01007ef00011e000",
-                spec => spec.AddValueFormatter("IsHardMode", BreathOfTheWild_MasterMode)
+                spec => spec
+                    .AddValueFormatter("IsHardMode", BreathOfTheWild_MasterMode)
+                    // reset to normal status when switching between normal & master mode in title screen
+                    .AddValueFormatter("AoCVer", PlayReportFormattedValue.AlwaysResets)
             )
             .AddSpec(
                 "0100f2c0115b6000",
@@ -24,41 +21,41 @@ namespace Ryujinx.Ava.Utilities
                     spec.AddValueFormatter("is_kids_mode", SuperMarioOdyssey_AssistMode)
             )
             .AddSpec(
-                "010075000ECBE000",
+                "010075000ecbe000",
                 spec =>
                     spec.AddValueFormatter("is_kids_mode", SuperMarioOdysseyChina_AssistMode)
             )
             .AddSpec(
-                "010028600EBDA000",
+                "010028600ebda000",
                 spec => spec.AddValueFormatter("mode", SuperMario3DWorldOrBowsersFury)
             )
             .AddSpec( // Global & China IDs
-                ["0100152000022000", "010075100E8EC000"],
+                ["0100152000022000", "010075100e8ec000"],
                 spec => spec.AddValueFormatter("To", MarioKart8Deluxe_Mode)
             );
 
-        private static PlayReportFormattedValue BreathOfTheWild_MasterMode(ref PlayReportValue value)
+        private static PlayReportFormattedValue BreathOfTheWild_MasterMode(PlayReportValue value)
             => value.BoxedValue is 1 ? "Playing Master Mode" : PlayReportFormattedValue.ForceReset;
 
-        private static PlayReportFormattedValue TearsOfTheKingdom_CurrentField(ref PlayReportValue value) =>
+        private static PlayReportFormattedValue TearsOfTheKingdom_CurrentField(PlayReportValue value) =>
-            value.PackedValue.AsDouble() switch
+            value.DoubleValue switch
             {
                 > 800d => "Exploring the Sky Islands",
                 < -201d => "Exploring the Depths",
                 _ => "Roaming Hyrule"
             };
 
-        private static PlayReportFormattedValue SuperMarioOdyssey_AssistMode(ref PlayReportValue value)
+        private static PlayReportFormattedValue SuperMarioOdyssey_AssistMode(PlayReportValue value)
             => value.BoxedValue is 1 ? "Playing in Assist Mode" : "Playing in Regular Mode";
 
-        private static PlayReportFormattedValue SuperMarioOdysseyChina_AssistMode(ref PlayReportValue value)
+        private static PlayReportFormattedValue SuperMarioOdysseyChina_AssistMode(PlayReportValue value)
             => value.BoxedValue is 1 ? "Playing in 帮助模式" : "Playing in 普通模式";
 
-        private static PlayReportFormattedValue SuperMario3DWorldOrBowsersFury(ref PlayReportValue value)
+        private static PlayReportFormattedValue SuperMario3DWorldOrBowsersFury(PlayReportValue value)
             => value.BoxedValue is 0 ? "Playing Super Mario 3D World" : "Playing Bowser's Fury";
         
-        private static PlayReportFormattedValue MarioKart8Deluxe_Mode(ref PlayReportValue value) 
+        private static PlayReportFormattedValue MarioKart8Deluxe_Mode(PlayReportValue value) 
-            => value.BoxedValue switch
+            => value.StringValue switch
             {
                 // Single Player
                 "Single" => "Single Player",

src/Ryujinx/Utilities/PlayReportAnalyzer.cs

@@ -3,127 +3,280 @@ using MsgPack;
 using Ryujinx.Ava.Utilities.AppLibrary;
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.Linq;
 
 namespace Ryujinx.Ava.Utilities
 {
+    /// <summary>
+    /// The entrypoint for the Play Report analysis system.
+    /// </summary>
     public class PlayReportAnalyzer
     {
         private readonly List<PlayReportGameSpec> _specs = [];
 
+        /// <summary>
+        /// Add an analysis spec matching a specific game by title ID, with the provided spec configuration.
+        /// </summary>
+        /// <param name="titleId">The ID of the game to listen to Play Reports in.</param>
+        /// <param name="transform">The configuration function for the analysis spec.</param>
+        /// <returns>The current <see cref="PlayReportAnalyzer"/>, for chaining convenience.</returns>
         public PlayReportAnalyzer AddSpec(string titleId, Func<PlayReportGameSpec, PlayReportGameSpec> transform)
         {
+            Guard.Ensure(ulong.TryParse(titleId, NumberStyles.HexNumber, null, out _),
+                $"Cannot use a non-hexadecimal string as the Title ID for a {nameof(PlayReportGameSpec)}.");
+
             _specs.Add(transform(new PlayReportGameSpec { TitleIds = [titleId] }));
             return this;
         }
-        
+
+        /// <summary>
+        /// Add an analysis spec matching a specific game by title ID, with the provided spec configuration.
+        /// </summary>
+        /// <param name="titleId">The ID of the game to listen to Play Reports in.</param>
+        /// <param name="transform">The configuration function for the analysis spec.</param>
+        /// <returns>The current <see cref="PlayReportAnalyzer"/>, for chaining convenience.</returns>
         public PlayReportAnalyzer AddSpec(string titleId, Action<PlayReportGameSpec> transform)
         {
+            Guard.Ensure(ulong.TryParse(titleId, NumberStyles.HexNumber, null, out _),
+                $"Cannot use a non-hexadecimal string as the Title ID for a {nameof(PlayReportGameSpec)}.");
+
             _specs.Add(new PlayReportGameSpec { TitleIds = [titleId] }.Apply(transform));
             return this;
         }
-        
+
-        public PlayReportAnalyzer AddSpec(IEnumerable<string> titleIds, Func<PlayReportGameSpec, PlayReportGameSpec> transform)
+        /// <summary>
+        /// Add an analysis spec matching a specific set of games by title IDs, with the provided spec configuration.
+        /// </summary>
+        /// <param name="titleIds">The IDs of the games to listen to Play Reports in.</param>
+        /// <param name="transform">The configuration function for the analysis spec.</param>
+        /// <returns>The current <see cref="PlayReportAnalyzer"/>, for chaining convenience.</returns>
+        public PlayReportAnalyzer AddSpec(IEnumerable<string> titleIds,
+            Func<PlayReportGameSpec, PlayReportGameSpec> transform)
         {
-            _specs.Add(transform(new PlayReportGameSpec { TitleIds = [..titleIds] }));
+            string[] tids = titleIds.ToArray();
+            Guard.Ensure(tids.All(x => ulong.TryParse(x, NumberStyles.HexNumber, null, out _)),
+                $"Cannot use a non-hexadecimal string as the Title ID for a {nameof(PlayReportGameSpec)}.");
+
+            _specs.Add(transform(new PlayReportGameSpec { TitleIds = [..tids] }));
             return this;
         }
-        
+
+        /// <summary>
+        /// Add an analysis spec matching a specific set of games by title IDs, with the provided spec configuration.
+        /// </summary>
+        /// <param name="titleIds">The IDs of the games to listen to Play Reports in.</param>
+        /// <param name="transform">The configuration function for the analysis spec.</param>
+        /// <returns>The current <see cref="PlayReportAnalyzer"/>, for chaining convenience.</returns>
         public PlayReportAnalyzer AddSpec(IEnumerable<string> titleIds, Action<PlayReportGameSpec> transform)
         {
-            _specs.Add(new PlayReportGameSpec { TitleIds = [..titleIds] }.Apply(transform));
+            string[] tids = titleIds.ToArray();
+            Guard.Ensure(tids.All(x => ulong.TryParse(x, NumberStyles.HexNumber, null, out _)),
+                $"Cannot use a non-hexadecimal string as the Title ID for a {nameof(PlayReportGameSpec)}.");
+
+            _specs.Add(new PlayReportGameSpec { TitleIds = [..tids] }.Apply(transform));
             return this;
         }
 
-        public PlayReportFormattedValue Run(string runningGameId, ApplicationMetadata appMeta, MessagePackObject playReport)
+        
+        /// <summary>
+        /// Runs the configured <see cref="PlayReportGameSpec.FormatterSpec"/> for the specified game title ID.
+        /// </summary>
+        /// <param name="runningGameId">The game currently running.</param>
+        /// <param name="appMeta">The Application metadata information, including localized game name and play time information.</param>
+        /// <param name="playReport">The Play Report received from HLE.</param>
+        /// <returns>A struct representing a possible formatted value.</returns>
+        public FormattedValue Format(
+            string runningGameId,
+            ApplicationMetadata appMeta,
+            MessagePackObject playReport
+        )
         {
-            if (!playReport.IsDictionary) 
+            if (!playReport.IsDictionary)
-                return PlayReportFormattedValue.Unhandled;
+                return FormattedValue.Unhandled;
 
             if (!_specs.TryGetFirst(s => runningGameId.EqualsAnyIgnoreCase(s.TitleIds), out PlayReportGameSpec spec))
-                return PlayReportFormattedValue.Unhandled;
+                return FormattedValue.Unhandled;
 
-            foreach (PlayReportValueFormatterSpec formatSpec in spec.Analyses.OrderBy(x => x.Priority))
+            foreach (PlayReportGameSpec.FormatterSpec formatSpec in spec.SimpleValueFormatters.OrderBy(x => x.Priority))
             {
                 if (!playReport.AsDictionary().TryGetValue(formatSpec.ReportKey, out MessagePackObject valuePackObject))
                     continue;
 
-                PlayReportValue value = new()
+                return formatSpec.ValueFormatter(new PlayReportValue
                 {
-                    Application = appMeta, 
+                    Application = appMeta, PackedValue = valuePackObject
-                    PackedValue = valuePackObject
+                });
-                };
-
-                return formatSpec.ValueFormatter(ref value);
             }
-            
+
-            return PlayReportFormattedValue.Unhandled;
+            return FormattedValue.Unhandled;
+        }
+
+        /// <summary>
+        /// A potential formatted value returned by a <see cref="PlayReportValueFormatter"/>.
+        /// </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="PlayReportAnalyzer"/> 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="PlayReportAnalyzer"/> 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="PlayReportValueFormatter"/>.
+            /// </summary>
+            public static readonly PlayReportValueFormatter AlwaysResets = _ => ForceReset;
+
+            /// <summary>
+            /// A delegate factory you can use to always return the specified
+            /// <paramref name="formattedValue"/> in a <see cref="PlayReportValueFormatter"/>.
+            /// </summary>
+            /// <param name="formattedValue">The string to always return for this delegate instance.</param>
+            public static PlayReportValueFormatter AlwaysReturns(string formattedValue) => _ => formattedValue;
         }
-        
     }
 
+    /// <summary>
+    /// A mapping of title IDs to value formatter specs.
+    ///
+    /// <remarks>Generally speaking, use the <see cref="PlayReportAnalyzer"/>.AddSpec(...) methods instead of creating this class yourself.</remarks>
+    /// </summary>
     public class PlayReportGameSpec
     {
         public required string[] TitleIds { get; init; }
-        public List<PlayReportValueFormatterSpec> Analyses { get; } = [];
+        public List<FormatterSpec> SimpleValueFormatters { get; } = [];
 
+        /// <summary>
+        /// Add a value formatter to the current <see cref="PlayReportGameSpec"/>
+        /// 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="PlayReportGameSpec"/>, for chaining convenience.</returns>
         public PlayReportGameSpec AddValueFormatter(string reportKey, PlayReportValueFormatter valueFormatter)
         {
-            Analyses.Add(new PlayReportValueFormatterSpec
+            SimpleValueFormatters.Add(new FormatterSpec
             {
-                Priority = Analyses.Count,
+                Priority = SimpleValueFormatters.Count, ReportKey = reportKey, ValueFormatter = valueFormatter
-                ReportKey = reportKey, 
-                ValueFormatter = valueFormatter
             });
             return this;
         }
-        
+
-        public PlayReportGameSpec AddValueFormatter(int priority, string reportKey, PlayReportValueFormatter valueFormatter)
+        /// <summary>
+        /// Add a value formatter at a specific priority to the current <see cref="PlayReportGameSpec"/>
+        /// 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="PlayReportGameSpec"/>, for chaining convenience.</returns>
+        public PlayReportGameSpec AddValueFormatter(int priority, string reportKey,
+            PlayReportValueFormatter valueFormatter)
         {
-            Analyses.Add(new PlayReportValueFormatterSpec
+            SimpleValueFormatters.Add(new FormatterSpec
             {
-                Priority = priority,
+                Priority = priority, ReportKey = reportKey, ValueFormatter = valueFormatter
-                ReportKey = reportKey, 
-                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 PlayReportValueFormatter ValueFormatter { get; init; }
+        }
     }
 
-    public readonly struct PlayReportValue
+    /// <summary>
+    /// The input data to a <see cref="PlayReportValueFormatter"/>,
+    /// containing the currently running application's <see cref="ApplicationMetadata"/>,
+    /// and the matched <see cref="MessagePackObject"/> from the Play Report.
+    /// </summary>
+    public class PlayReportValue
     {
+        /// <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 <see cref="PackedValue"/> and the AsX (where X is a numerical type name i.e. Int32) methods 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
     }
 
-    public struct PlayReportFormattedValue
+    /// <summary>
-    {
+    /// The delegate type that powers the entire analysis system (as it currently is).<br/>
-        public bool Handled { get; private init; }
+    /// Takes in the result value from the Play Report, and outputs:
-        
+    /// <br/>
-        public bool Reset { get; private init; }
+    /// a formatted string,
-        
+    /// <br/>
-        public string FormattedString { get; private init; }
+    /// a signal that nothing was available to handle it,
-
+    /// <br/>
-        public static implicit operator PlayReportFormattedValue(string formattedValue)
+    /// OR a signal to reset the value that the caller is using the <see cref="PlayReportAnalyzer"/> for. 
-            => new() { Handled = true, FormattedString = formattedValue };
+    /// </summary>
-
+    public delegate PlayReportAnalyzer.FormattedValue PlayReportValueFormatter(PlayReportValue value);
-        public static PlayReportFormattedValue Unhandled => default;
-        public static PlayReportFormattedValue ForceReset => new() { Handled = true, Reset = true };
-
-        public static PlayReportValueFormatter AlwaysResets = AlwaysResetsImpl;
-        
-        private static PlayReportFormattedValue AlwaysResetsImpl(ref PlayReportValue _) => ForceReset;
-    }
-
-    public struct PlayReportValueFormatterSpec
-    {
-        public required int Priority { get; init; }
-        public required string ReportKey { get; init; }
-        public PlayReportValueFormatter ValueFormatter { get; init; }
-    }
-
-    public delegate PlayReportFormattedValue PlayReportValueFormatter(ref PlayReportValue value);
 }