Repository navigation
Add Game Settings API contracts to Plugin Exports #7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
00f4f56
feat(settings): add declarative settings model
Cryotechnic 226333f
feat(settings): expose v0.1.6 settings exports
Cryotechnic ea48566
test(settings): cover settings contract serialization
Cryotechnic cff6f3a
docs(settings): document plugin settings pages
Cryotechnic 35cebfa
Keep PrintGameLog callback alive
Cryotechnic 63fad45
chore(deps): Deps
Cryotechnic b66c43e
Guard page JSON marshal on empty handle
Cryotechnic 14293ba
Use marshaller `Free` for preset config COM `ptr`
Cryotechnic ee29957
Merge branch 'main' into feat/gsp
Cryotechnic 1ae9d11
Fix leaked allocation of UTF-8 marshal conversion return value
Cryotechnic cd5a96a
Update docs
Cryotechnic File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| using Hi3Helper.Plugin.Core.UI.Settings; | ||
| using System; | ||
|
|
||
| namespace PluginTest; | ||
|
|
||
| internal static partial class Test | ||
| { | ||
| internal static void TestGameSettingsContract() | ||
| { | ||
| GameSettingsPage source = new([ | ||
| new GameSettingsSection("General", [ | ||
| GameSettingEntry.Toggle("enabled", "Enabled", true), | ||
| GameSettingEntry.Text("name", "Name", "Collapse"), | ||
| GameSettingEntry.Number("count", "Count", 3, 0, 10), | ||
| GameSettingEntry.Slider("volume", "Volume", 75, 0, 100), | ||
| GameSettingEntry.Choice("language", "Language", "en", [ | ||
| new GameSettingChoice("en", "English") | ||
| ]) | ||
| ]) | ||
| ]) { Title = "Settings" }; | ||
|
|
||
| string json = GameSettingsPageSerializer.Serialize(source); | ||
| GameSettingsPage result = GameSettingsPageSerializer.Deserialize(json) | ||
| ?? throw new InvalidOperationException("Deserialization returned null"); | ||
|
|
||
| if (result.Title != source.Title || result.Sections.Count != 1 || result.Sections[0].Entries.Count != 5) | ||
| { | ||
| throw new InvalidOperationException("The game settings contract did not round-trip"); | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| using Hi3Helper.Plugin.Core.Management.PresetConfig; | ||
| using Hi3Helper.Plugin.Core.UI.Settings; | ||
| using Hi3Helper.Plugin.Core.Utility; | ||
| using Microsoft.Extensions.Logging; | ||
| using System; | ||
| using System.Runtime.InteropServices; | ||
| using System.Runtime.InteropServices.Marshalling; | ||
|
|
||
| namespace Hi3Helper.Plugin.Core; | ||
|
|
||
| public partial class SharedStaticV1Ext | ||
| { | ||
| internal unsafe delegate HResult GetGameSettingsPageDelegate(nint presetConfig, | ||
| out PluginDisposableMemoryMarshal pageJson); | ||
| internal unsafe delegate HResult SetGameSettingValueDelegate(nint presetConfig, | ||
| char* key, int keyLength, | ||
| char* value, int valueLength); | ||
| internal delegate HResult ApplyGameSettingsDelegate(nint presetConfig); | ||
| } | ||
|
|
||
| public partial class SharedStaticV1Ext<T> | ||
| { | ||
| private static unsafe void InitExtension_Update6Exports() | ||
| { | ||
| TryRegisterApiExport<GetGameSettingsPageDelegate>("GetGameSettingsPage", GetGameSettingsPage); | ||
| TryRegisterApiExport<SetGameSettingValueDelegate>("SetGameSettingValue", SetGameSettingValue); | ||
| TryRegisterApiExport<ApplyGameSettingsDelegate>("ApplyGameSettings", ApplyGameSettings); | ||
| } | ||
|
|
||
| private static unsafe HResult GetGameSettingsPage(nint presetConfigP, | ||
| out PluginDisposableMemoryMarshal pageJson) | ||
| { | ||
| pageJson = PluginDisposableMemoryMarshal.Empty; | ||
| try | ||
| { | ||
| IPluginPresetConfig presetConfig = GetPresetConfig(presetConfigP); | ||
| GameSettingsPage? page = ThisExtensionExport.GetGameSettingsPageCore(presetConfig); | ||
| if (page == null) | ||
| { | ||
| return HResult.False; | ||
| } | ||
|
|
||
| pageJson = GameSettingsPageSerializer.Serialize(page); | ||
| return HResult.Ok; | ||
| } | ||
| catch (Exception ex) | ||
| { | ||
| InstanceLogger.LogError(ex, "An error occurred while retrieving the plugin game settings page"); | ||
| return Marshal.GetHRForException(ex); | ||
| } | ||
| } | ||
|
|
||
| private static unsafe HResult SetGameSettingValue(nint presetConfigP, | ||
| char* key, int keyLength, | ||
| char* value, int valueLength) | ||
| { | ||
| try | ||
| { | ||
| IPluginPresetConfig presetConfig = GetPresetConfig(presetConfigP); | ||
| string keyString = new(key, 0, keyLength); | ||
| string valueString = new(value, 0, valueLength); | ||
| ThisExtensionExport.SetGameSettingValueCore(presetConfig, keyString, valueString); | ||
| return HResult.Ok; | ||
| } | ||
| catch (Exception ex) | ||
| { | ||
| InstanceLogger.LogError(ex, "An error occurred while updating plugin game setting {Key}", | ||
| key == null ? null : new string(key, 0, keyLength)); | ||
| return Marshal.GetHRForException(ex); | ||
| } | ||
| } | ||
|
|
||
| private static HResult ApplyGameSettings(nint presetConfigP) | ||
| { | ||
| try | ||
| { | ||
| ThisExtensionExport.ApplyGameSettingsCore(GetPresetConfig(presetConfigP)); | ||
| return HResult.Ok; | ||
| } | ||
| catch (Exception ex) | ||
| { | ||
| InstanceLogger.LogError(ex, "An error occurred while applying plugin game settings"); | ||
| return Marshal.GetHRForException(ex); | ||
| } | ||
| } | ||
|
|
||
| private static unsafe IPluginPresetConfig GetPresetConfig(nint presetConfigP) | ||
| { | ||
| if (presetConfigP == nint.Zero) | ||
| { | ||
| throw new ArgumentNullException(nameof(presetConfigP)); | ||
| } | ||
|
|
||
| #if MANUALCOM | ||
| return ComWrappers.ComInterfaceDispatch.GetInstance<IPluginPresetConfig>( | ||
| (ComWrappers.ComInterfaceDispatch*)presetConfigP); | ||
| #else | ||
| return ComInterfaceMarshaller<IPluginPresetConfig>.ConvertToManaged((void*)presetConfigP) | ||
| ?? throw new InvalidCastException("Cannot convert the preset config pointer to IPluginPresetConfig"); | ||
| #endif | ||
| } | ||
|
|
||
| /// <summary> | ||
| /// Returns the declarative settings page for a game preset, or <c>null</c> when the preset has no settings page. | ||
| /// </summary> | ||
| protected virtual GameSettingsPage? GetGameSettingsPageCore(IPluginPresetConfig presetConfig) => null; | ||
|
|
||
| /// <summary> | ||
| /// Receives a value edited by the user. Values use invariant strings; conversion and validation belong to the plugin. | ||
| /// </summary> | ||
| protected virtual void SetGameSettingValueCore(IPluginPresetConfig presetConfig, string key, string value) { } | ||
|
|
||
| /// <summary> | ||
| /// Persists the edited settings for the specified game preset. | ||
| /// </summary> | ||
| protected virtual void ApplyGameSettingsCore(IPluginPresetConfig presetConfig) { } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| namespace Hi3Helper.Plugin.Core.UI.Settings; | ||
|
|
||
| /// <summary> | ||
| /// Defines one selectable value for a <see cref="GameSettingKind.Choice"/> setting. | ||
| /// </summary> | ||
| public sealed class GameSettingChoice(string value, string title) | ||
| { | ||
| public string Value { get; init; } = value; | ||
| public string Title { get; init; } = title; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| using System; | ||
| using System.Collections.Generic; | ||
| using System.Globalization; | ||
|
|
||
| namespace Hi3Helper.Plugin.Core.UI.Settings; | ||
|
|
||
| /// <summary> | ||
| /// Defines one editable setting in a plugin-provided game settings page. | ||
| /// </summary> | ||
| public sealed class GameSettingEntry | ||
| { | ||
| public required string Key { get; init; } | ||
| public required string Title { get; init; } | ||
| public string? Description { get; init; } | ||
| public required GameSettingKind Kind { get; init; } | ||
| public required string Value { get; init; } | ||
| public string? Placeholder { get; init; } | ||
| public double Minimum { get; init; } | ||
| public double Maximum { get; init; } = 100; | ||
| public double Step { get; init; } = 1; | ||
| public IReadOnlyList<GameSettingChoice>? Choices { get; init; } | ||
|
|
||
| public static GameSettingEntry Toggle(string key, string title, bool value, string? description = null) => | ||
| new() | ||
| { | ||
| Key = key, | ||
| Title = title, | ||
| Description = description, | ||
| Kind = GameSettingKind.Toggle, | ||
| Value = value ? bool.TrueString : bool.FalseString | ||
| }; | ||
|
|
||
| public static GameSettingEntry Text(string key, string title, string? value = null, string? description = null, | ||
| string? placeholder = null) => | ||
| new() | ||
| { | ||
| Key = key, | ||
| Title = title, | ||
| Description = description, | ||
| Kind = GameSettingKind.Text, | ||
| Value = value ?? string.Empty, | ||
| Placeholder = placeholder | ||
| }; | ||
|
|
||
| public static GameSettingEntry Number(string key, string title, double value, double minimum = double.MinValue, | ||
| double maximum = double.MaxValue, double step = 1, | ||
| string? description = null) => | ||
| Numeric(key, title, value, minimum, maximum, step, description, GameSettingKind.Number); | ||
|
|
||
| public static GameSettingEntry Slider(string key, string title, double value, double minimum, double maximum, | ||
| double step = 1, string? description = null) => | ||
| Numeric(key, title, value, minimum, maximum, step, description, GameSettingKind.Slider); | ||
|
|
||
| public static GameSettingEntry Choice(string key, string title, string value, | ||
| IReadOnlyList<GameSettingChoice> choices, | ||
| string? description = null) => | ||
| new() | ||
| { | ||
| Key = key, | ||
| Title = title, | ||
| Description = description, | ||
| Kind = GameSettingKind.Choice, | ||
| Value = value, | ||
| Choices = choices | ||
| }; | ||
|
|
||
| private static GameSettingEntry Numeric(string key, string title, double value, double minimum, double maximum, | ||
| double step, string? description, GameSettingKind kind) | ||
| { | ||
| ArgumentOutOfRangeException.ThrowIfGreaterThan(minimum, maximum); | ||
| ArgumentOutOfRangeException.ThrowIfNegativeOrZero(step); | ||
|
|
||
| return new GameSettingEntry | ||
| { | ||
| Key = key, | ||
| Title = title, | ||
| Description = description, | ||
| Kind = kind, | ||
| Value = value.ToString(CultureInfo.InvariantCulture), | ||
| Minimum = minimum, | ||
| Maximum = maximum, | ||
| Step = step | ||
| }; | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| namespace Hi3Helper.Plugin.Core.UI.Settings; | ||
|
|
||
| /// <summary> | ||
| /// Identifies the launcher control used to edit a game setting. | ||
| /// </summary> | ||
| public enum GameSettingKind | ||
| { | ||
| Toggle, | ||
| Text, | ||
| Number, | ||
| Slider, | ||
| Choice | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| using System.Collections.Generic; | ||
|
|
||
| namespace Hi3Helper.Plugin.Core.UI.Settings; | ||
|
|
||
| /// <summary> | ||
| /// Declaratively describes a game settings page rendered by the launcher. | ||
| /// </summary> | ||
| public sealed class GameSettingsPage(IReadOnlyList<GameSettingsSection> sections) | ||
| { | ||
| public string? Title { get; init; } | ||
| public IReadOnlyList<GameSettingsSection> Sections { get; init; } = sections; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| using System.Text.Json; | ||
| using System.Text.Json.Serialization; | ||
|
|
||
| namespace Hi3Helper.Plugin.Core.UI.Settings; | ||
|
|
||
| /// <summary> | ||
| /// Serializes the declarative settings contract passed across the plugin ABI. | ||
| /// </summary> | ||
| public static class GameSettingsPageSerializer | ||
| { | ||
| public static string Serialize(GameSettingsPage page) => | ||
| JsonSerializer.Serialize(page, GameSettingsPageJsonContext.Default.GameSettingsPage); | ||
|
|
||
| public static GameSettingsPage? Deserialize(string json) => | ||
| JsonSerializer.Deserialize(json, GameSettingsPageJsonContext.Default.GameSettingsPage); | ||
| } | ||
|
|
||
| [JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] | ||
| [JsonSerializable(typeof(GameSettingsPage))] | ||
| internal sealed partial class GameSettingsPageJsonContext : JsonSerializerContext; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| using System.Collections.Generic; | ||
|
|
||
| namespace Hi3Helper.Plugin.Core.UI.Settings; | ||
|
|
||
| /// <summary> | ||
| /// Groups related entries on a plugin-provided game settings page. | ||
| /// </summary> | ||
| public sealed class GameSettingsSection(string title, IReadOnlyList<GameSettingEntry> entries) | ||
| { | ||
| public string Title { get; init; } = title; | ||
| public string? Description { get; init; } | ||
| public IReadOnlyList<GameSettingEntry> Entries { get; init; } = entries; | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.