From 434a1417f83c233a7d4c67f558a8c249d06a40d4 Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Thu, 26 May 2022 21:55:11 -0500 Subject: [PATCH 01/10] Create 0000-common-configuration-api.md Overview of definitions. --- .../0000-common-configuration-api.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 specification/0000-common-configuration-api.md diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md new file mode 100644 index 00000000..f5f5d142 --- /dev/null +++ b/specification/0000-common-configuration-api.md @@ -0,0 +1,84 @@ +# A Common Configuration API for QSL + +## Summary + +Specify and implement an API for constructing mod configuration objects ("Settings") which can be used to generate config screens. +Define a common API for all mods that have configuration that can be modified in-game. + + +## Motivation + +Why should we do this? What are the benefits? + +Mod configuration is a common problem that mods must solve. Defining an API within QSL that Quilt mods should use unifies the GUI representation +of configuration among mods and allows mods to avoid reinventing the wheel. Exposing a common API to query config metadata allows config screens +to be generated rather than relying on mods to manually construct screens using general-purpose GUI libraries. + + +## Explanation + +Explain this change in detail. This section will be different depending on what +sort of change it is. + +For technical changes, such as changes to APIs, first give an overview of how +this proposed change would work. Explain how it would be used, with code +examples. Then, give a more in depth explanation of how it would be implemented +and how it would interact with other parts of the project and other Quilt +projects. + +### Definitions +- **Setting**: A single value and its associated metadata. +- **Section**: A logical grouping of Settings. A Setting may be a member of multiple Sections. +- **Validation Group**: A logical grouping of Settings used for validation. A Setting may be a member of only one Validation Group. +- **Formatter**: A function that maps a value to Minecraft `Text` suitable for display. +- **Setting Validator**: A function that is invoked to accept or reject the value of a single Setting. +- **Group Validator**: A function that is invoked to accept or reject the set of values in a single Section. +- **Environment Policy**: A value that defines how a Setting interacts with the client and/or server. + +A new QSL module, `quilt_config`, contains the implementation of this API. + +### API Detail + +// todo + +## Out of Scope + +Key binding configuration is not done in this API. However, the existence of this API should not preclude a separate API for key bindings. + + +## Drawbacks + +Why should we not do this? + +Mod developers may want to more tightly control their runtime config representation for querying or display purposes. + + +## Rationale and Alternatives + +- Why is this the best possible design? +- What other designs are possible and why should we choose this one instead? +- What other designs have benefits over this one? Why should we choose an + alternative instead? +- What is the impact of not doing this? + +This RFC describes a common API between mods that define configuration and mods that consume configuration. +This approach gives the most control to mods that wish to consume multiple mods' configuration, e.g. to construct a config screen, +while avoiding including too many "batteries" that not all mods may use. + +## Prior Art + +If this has been done before by some other project, explain it here. This could +be positive or negative. Discuss what worked well for them and what didn't. + +There may not always be prior art, and that's fine. + +- ModConfig, a global config screen that extracts configuration metadata from mods that use Cloth UI. +- Fiber, a library that defines a rich config tree. + + +## Unresolved Questions + +- What should be resolved before this RFC gets merged? +- What should be resolved while implementing this RFC? +- What unresolved questions do you consider out of scope for this RFC, that + could be addressed in the future? From b07c97153cb0cfde149a9e0fc49ae31121ab9d75 Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Thu, 26 May 2022 22:47:30 -0500 Subject: [PATCH 02/10] Update 0000-common-configuration-api.md Expand on the specific metadata settings contain. --- .../0000-common-configuration-api.md | 40 +++++++++++++------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index f5f5d142..703d1391 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -17,28 +17,44 @@ to be generated rather than relying on mods to manually construct screens using ## Explanation -Explain this change in detail. This section will be different depending on what -sort of change it is. - -For technical changes, such as changes to APIs, first give an overview of how -this proposed change would work. Explain how it would be used, with code -examples. Then, give a more in depth explanation of how it would be implemented -and how it would interact with other parts of the project and other Quilt -projects. - ### Definitions - **Setting**: A single value and its associated metadata. -- **Section**: A logical grouping of Settings. A Setting may be a member of multiple Sections. +- **Category**: A logical grouping of Settings. A Setting may be a member of multiple Categories. - **Validation Group**: A logical grouping of Settings used for validation. A Setting may be a member of only one Validation Group. - **Formatter**: A function that maps a value to Minecraft `Text` suitable for display. - **Setting Validator**: A function that is invoked to accept or reject the value of a single Setting. -- **Group Validator**: A function that is invoked to accept or reject the set of values in a single Section. +- **Group Validator**: A function that is invoked to accept or reject the set of values in a single Validation Group. - **Environment Policy**: A value that defines how a Setting interacts with the client and/or server. -A new QSL module, `quilt_config`, contains the implementation of this API. +A new QSL module, `quilt_config`, contains the implementation of this API. The API is built on top of the Loader config API, specialized +with metadata for Minecraft mods. ### API Detail +A Setting has the following metadata. +- Data type (integer, string, enum, etc.) +- Label +- Tooltip +- Widget type (cycle, check box, select, text box, etc.) +- Sections +- Validation Group +- Setting Validators (range, length, regex, etc.) +- Environment Policy + +```java +public enum EnvironmentPolicy { + CLIENT_ONLY, + SERVER_ONLY, + CLIENT_SYNCED, + SERVER_SYNCED +} +``` + +- `CLIENT_ONLY` Settings are specific to a player and are always editable. +- `CLIENT_SYNCED` Settings are specific to a player and may be overridden by the server. +- `SERVER_ONLY` Settings are specific to a level and are not sent to the client from a dedicated server. +- `SERVER_SYNCED` Settings are specific to a level and are sent to the client from a dedicated server. + // todo ## Out of Scope From 17323f7c803b09ec3e9b713a84fe3140d8ba30bf Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Fri, 27 May 2022 21:06:02 -0500 Subject: [PATCH 03/10] Add widget type and label detail. --- .../0000-common-configuration-api.md | 68 +++++++++++++++---- 1 file changed, 56 insertions(+), 12 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 703d1391..7cdea945 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -2,17 +2,15 @@ ## Summary -Specify and implement an API for constructing mod configuration objects ("Settings") which can be used to generate config screens. -Define a common API for all mods that have configuration that can be modified in-game. +Specify and implement an API for assigning metadata to configuration objects ("Settings") which can be used to generate config screens. +Define a common metadata API for all mods that have configuration that can be modified in-game. ## Motivation -Why should we do this? What are the benefits? - -Mod configuration is a common problem that mods must solve. Defining an API within QSL that Quilt mods should use unifies the GUI representation -of configuration among mods and allows mods to avoid reinventing the wheel. Exposing a common API to query config metadata allows config screens -to be generated rather than relying on mods to manually construct screens using general-purpose GUI libraries. +Mod configuration is a common problem that mods must solve. Defining an API within QSL that Quilt mods should use to define configuration metadata +unifies the GUI representation of configuration among mods and allows mods to avoid reinventing the wheel. Exposing a common API to query config metadata +allows config screens to be generated rather than relying on mods to manually construct screens using general-purpose GUI libraries. ## Explanation @@ -26,21 +24,65 @@ to be generated rather than relying on mods to manually construct screens using - **Group Validator**: A function that is invoked to accept or reject the set of values in a single Validation Group. - **Environment Policy**: A value that defines how a Setting interacts with the client and/or server. -A new QSL module, `quilt_config`, contains the implementation of this API. The API is built on top of the Loader config API, specialized +A new QSL module, `quilt_config_metadata`, contains the implementation of this API. The API is built on top of the Loader config API, specialized with metadata for Minecraft mods. -### API Detail +### Settings API Detail A Setting has the following metadata. -- Data type (integer, string, enum, etc.) +- Widget Type (cycle, check box, select, text box, etc.) - Label - Tooltip -- Widget type (cycle, check box, select, text box, etc.) - Sections - Validation Group -- Setting Validators (range, length, regex, etc.) - Environment Policy +#### Widget Type + +```java +public enum WidgetType { + TOGGLE, + CYCLE, + SELECT, + FREE_TEXT, + SLIDER, + NUMERIC, + UNORDERED_COLLECTION + ORDERED_COLLECTION; +} + +MetadataType WIDGET_TYPE; +``` + +A Setting's Widget Type describes the type of widget that best represents the Setting. +- `TOGGLE` widgets are binary, typically displayed as check boxes or buttons. +- `CYCLE` widgets are small ordered lists of options, typically displayed as cycle buttons or radio buttons. +- `SELECT` widgets are large unordered lists of options, typically displayed as a drop-down or searchable menu. +- `FREE_TEXT` widgets are strings of text, typically displayed as a text box. +- `SLIDER` widgets are imprecise numeric values, typically displayed as a slider. +- `NUMERIC` widgets are precise numeric values, typically displayed as a text box. +- `UNORDERED_COLLECTION` widgets are made up of a collection of values with no defined ordering, all with the same Widget Type. +- `ORDERED_COLLECTION` widgets are made up of a sequence of values with a defined ordering, all with the same Widget Type. + +The most appropriate Widget Type for a given Setting depends on the Setting's underlying data type and on any constraints a Setting's +value must obey. + +If a Setting's Widget Type is `UNORDERED_COLLECTION` or `ORDERED_COLLECTION`, additional data is stored `WIDGET_ELEMENT_TYPE`. + +```java +MetadataType WIDGET_ELEMENT_TYPE; +``` + +#### Label + +```java +MetadataType LABEL; +``` + +A Setting's Label is the simple display name of a Setting. + +#### Environment Policy + ```java public enum EnvironmentPolicy { CLIENT_ONLY, @@ -48,6 +90,8 @@ public enum EnvironmentPolicy { CLIENT_SYNCED, SERVER_SYNCED } + +MetadataType ENVIRONMENT_POLICY; ``` - `CLIENT_ONLY` Settings are specific to a player and are always editable. From c09478846016698c676496c940d9fcf6032f202a Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Fri, 27 May 2022 21:33:18 -0500 Subject: [PATCH 04/10] Add tooltip detail. --- specification/0000-common-configuration-api.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 7cdea945..7f92f048 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -30,10 +30,10 @@ with metadata for Minecraft mods. ### Settings API Detail A Setting has the following metadata. -- Widget Type (cycle, check box, select, text box, etc.) +- Widget Type - Label - Tooltip -- Sections +- Categories - Validation Group - Environment Policy @@ -81,6 +81,19 @@ MetadataType LABEL; A Setting's Label is the simple display name of a Setting. +#### Tooltip + +```java +@FunctionalInterface +public interface TooltipSupplier { + Text getTooltip(T value); +} + +MetadataType, ?> TOOLTIP; +``` + +A Setting's tooltip is a brief description of the current state of the Setting, dependent on the Setting's value. + #### Environment Policy ```java From f2d1d35845c4131ccde575b19ef5ec8806edfc0f Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Sat, 28 May 2022 14:19:47 -0500 Subject: [PATCH 05/10] Add most of the other metadata types. --- .../0000-common-configuration-api.md | 73 +++++++++++++------ 1 file changed, 52 insertions(+), 21 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 7f92f048..790888e7 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -31,10 +31,11 @@ with metadata for Minecraft mods. A Setting has the following metadata. - Widget Type +- Value Calculator - Label - Tooltip - Categories -- Validation Group +- Group Validator - Environment Policy #### Widget Type @@ -73,6 +74,15 @@ If a Setting's Widget Type is `UNORDERED_COLLECTION` or `ORDERED_COLLECTION`, ad MetadataType WIDGET_ELEMENT_TYPE; ``` +#### Value Calculator + +A Value Calculator handles user input on a given widget type in order to produce a value for a Setting. + +// all -> turn raw input into a value (maybe Setting Validators should do this?) +// cycle -> get next/previous value +// slider -> get next/previous value + calculate value from percentage (and visa-versa) +// collections -> add/insert/remove/move an element + #### Label ```java @@ -94,6 +104,36 @@ MetadataType, ?> TOOLTIP; A Setting's tooltip is a brief description of the current state of the Setting, dependent on the Setting's value. +#### Categories + +```java +MetadataType, ?> CATEGORIES; +``` + +A Category is a logical grouping of Settings; for example, video, audio, accessibility, or gameplay. A Setting may be a member of any number +of Categories. Categories are intended to be used to partition Settings into broad groupings for display purposes. + +#### Setting Validator + +Settings will use the existing `Constaint` interface to define Setting Validators. + +#### Group Validator + +```java +@FunctionalInterface +public interface GroupValidator { + void validate(ValidationDiagnostics diagnositics); + boolean equals(Object o); +} + +MetadataType GROUP_VALIDATOR; +``` + +A Group Validator is used to validate properties that pretain to the relationship among multiple Settings. For example, two Settings that +represent the minimum and maximum value of a range may have a Group Validator that ensures the maximum is always greater than or equal to +the minimum. It is intended that Group Validators that perform the same validation compare equal so that consumers of this API do not +run validation logic multiple times. + #### Environment Policy ```java @@ -110,21 +150,13 @@ MetadataType ENVIRONMENT_POLICY; - `CLIENT_ONLY` Settings are specific to a player and are always editable. - `CLIENT_SYNCED` Settings are specific to a player and may be overridden by the server. - `SERVER_ONLY` Settings are specific to a level and are not sent to the client from a dedicated server. -- `SERVER_SYNCED` Settings are specific to a level and are sent to the client from a dedicated server. - -// todo - -## Out of Scope - -Key binding configuration is not done in this API. However, the existence of this API should not preclude a separate API for key bindings. - +- `SERVER_SYNCED` Settings are specific to a level and are sent to the client from a dedicated server ## Drawbacks Why should we not do this? -Mod developers may want to more tightly control their runtime config representation for querying or display purposes. - +This API depends on (and is therefore limited by) Quilt Loader's configuration API. ## Rationale and Alternatives @@ -140,18 +172,17 @@ while avoiding including too many "batteries" that not all mods may use. ## Prior Art -If this has been done before by some other project, explain it here. This could -be positive or negative. Discuss what worked well for them and what didn't. - -There may not always be prior art, and that's fine. - -- ModConfig, a global config screen that extracts configuration metadata from mods that use Cloth UI. -- Fiber, a library that defines a rich config tree. +- [ModConfig](https://github.com/kvverti/mod-config), a global config screen that extracts configuration metadata from mods that use Cloth UI. +- [Fiber](https://github.com/FabLabsMC/fiber), a library that defines a rich config tree. ## Unresolved Questions - What should be resolved before this RFC gets merged? -- What should be resolved while implementing this RFC? -- What unresolved questions do you consider out of scope for this RFC, that - could be addressed in the future? + +### Implementation +- Which common formatter/validator/widget type instances should this API provide? E.g. enum, registry entry, `Identifier`, etc. +- How strict should the API be on the well-formedness of metadata? + +### Out of Scope +- Key binding configuration is considered out of scope for this API because Minecraft handle key bindings differently from other game options. From cde29013a9f7a33556b103b3565c2498c7bfd78e Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Tue, 31 May 2022 23:06:49 -0500 Subject: [PATCH 06/10] Add some value parsers. --- .../0000-common-configuration-api.md | 56 ++++++++++++++++--- 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 790888e7..3554f18a 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -2,14 +2,15 @@ ## Summary -Specify and implement an API for assigning metadata to configuration objects ("Settings") which can be used to generate config screens. -Define a common metadata API for all mods that have configuration that can be modified in-game. +Define a common metadata API for all mods that have configuration that can be modified in-game. These metadata should be sufficient to automatically +generate user-friendly configuration screens for mods. In order to achieve this, this RFC defines metadata necessary to display configuration to the +user and to convert user input into configuration values. ## Motivation -Mod configuration is a common problem that mods must solve. Defining an API within QSL that Quilt mods should use to define configuration metadata -unifies the GUI representation of configuration among mods and allows mods to avoid reinventing the wheel. Exposing a common API to query config metadata +Mod configuration is a common problem that mods must solve. Defining an API within QSL that Quilt mods use to define configuration metadata +unifies the configuration UI model among mods and allows mods to avoid reinventing the wheel. Exposing a common API to query config metadata allows config screens to be generated rather than relying on mods to manually construct screens using general-purpose GUI libraries. @@ -19,6 +20,7 @@ allows config screens to be generated rather than relying on mods to manually co - **Setting**: A single value and its associated metadata. - **Category**: A logical grouping of Settings. A Setting may be a member of multiple Categories. - **Validation Group**: A logical grouping of Settings used for validation. A Setting may be a member of only one Validation Group. +- **Value Parser**: A function that converts user input to the underlying data type of the Setting. - **Formatter**: A function that maps a value to Minecraft `Text` suitable for display. - **Setting Validator**: A function that is invoked to accept or reject the value of a single Setting. - **Group Validator**: A function that is invoked to accept or reject the set of values in a single Validation Group. @@ -74,9 +76,43 @@ If a Setting's Widget Type is `UNORDERED_COLLECTION` or `ORDERED_COLLECTION`, ad MetadataType WIDGET_ELEMENT_TYPE; ``` -#### Value Calculator +#### Value Parser -A Value Calculator handles user input on a given widget type in order to produce a value for a Setting. +```java +@FunctionalInterface +public interface ToggleValueParser { + Optional parse(boolean input, ValidationDiagnostics diagnostics); +} + +@FunctionalInterface +public interface CycleValueParser { + Optional parse(CycleDirection direction, boolean includeHiddenOptions, ValidationDiagnostics diagnostics); + enum CycleDirection { FORWARD, BACKWARD } +} + +@FunctionalInterface +public interface SelectValueParser { + List parse(String search, ValidationDiagnostics diagnostics); +} + +@FunctionalInterface +public interface FreeTextValueParser { + Optional parse(String input, ValidationDiagnostics diagnostics); +} + +@FunctionalInterface +public interface SliderValueParser { + Optional parse(double fraction, ValidationDiagnostics diagnostics); +} + +@FunctionalInterface +public interface NumericValueParser { + Optional parse(Number input, ValidationDiagnostics diagnostics); +} +``` + +A Value Calculator handles user input on a given widget type in order to produce a value for a Setting. Depending on the UI widget, user input +may include text, key presses, and button presses. // all -> turn raw input into a value (maybe Setting Validators should do this?) // cycle -> get next/previous value @@ -113,9 +149,11 @@ MetadataType, ?> CATEGORIES; A Category is a logical grouping of Settings; for example, video, audio, accessibility, or gameplay. A Setting may be a member of any number of Categories. Categories are intended to be used to partition Settings into broad groupings for display purposes. +This RFC defines a standard Category `c:accessibility`, to be used for Settings that are used to make a mod more accessible. + #### Setting Validator -Settings will use the existing `Constaint` interface to define Setting Validators. +Settings will use the existing `Constaint` interface in Quilt Loader's configuration API to define Setting Validators. #### Group Validator @@ -149,6 +187,7 @@ MetadataType ENVIRONMENT_POLICY; - `CLIENT_ONLY` Settings are specific to a player and are always editable. - `CLIENT_SYNCED` Settings are specific to a player and may be overridden by the server. + - If a `CLIENT_SYNCED` Setting is a member of the Category `c:accessibility`, then the API shall issue a warning. - `SERVER_ONLY` Settings are specific to a level and are not sent to the client from a dedicated server. - `SERVER_SYNCED` Settings are specific to a level and are sent to the client from a dedicated server @@ -181,8 +220,9 @@ while avoiding including too many "batteries" that not all mods may use. - What should be resolved before this RFC gets merged? ### Implementation -- Which common formatter/validator/widget type instances should this API provide? E.g. enum, registry entry, `Identifier`, etc. +- Which other common formatter/validator/widget type instances should this API provide? E.g. enum, registry entry, `Identifier`, etc. - How strict should the API be on the well-formedness of metadata? ### Out of Scope - Key binding configuration is considered out of scope for this API because Minecraft handle key bindings differently from other game options. +- Creating a standard consumer of this API, e.g. a config screen generator may be specified in another RFC. From 9b5e655e5f013a65214aa79d141d24f4f67ceaac Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Fri, 3 Jun 2022 21:55:53 -0500 Subject: [PATCH 07/10] Add value converter --- .../0000-common-configuration-api.md | 67 ++++++++++--------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 3554f18a..2975e92c 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -20,7 +20,7 @@ allows config screens to be generated rather than relying on mods to manually co - **Setting**: A single value and its associated metadata. - **Category**: A logical grouping of Settings. A Setting may be a member of multiple Categories. - **Validation Group**: A logical grouping of Settings used for validation. A Setting may be a member of only one Validation Group. -- **Value Parser**: A function that converts user input to the underlying data type of the Setting. +- **Value Converter**: An object that handles conversion between the value and UI state. - **Formatter**: A function that maps a value to Minecraft `Text` suitable for display. - **Setting Validator**: A function that is invoked to accept or reject the value of a single Setting. - **Group Validator**: A function that is invoked to accept or reject the set of values in a single Validation Group. @@ -34,6 +34,7 @@ with metadata for Minecraft mods. A Setting has the following metadata. - Widget Type - Value Calculator +- Formatter - Label - Tooltip - Categories @@ -76,48 +77,45 @@ If a Setting's Widget Type is `UNORDERED_COLLECTION` or `ORDERED_COLLECTION`, ad MetadataType WIDGET_ELEMENT_TYPE; ``` -#### Value Parser +#### Value Converter ```java -@FunctionalInterface -public interface ToggleValueParser { - Optional parse(boolean input, ValidationDiagnostics diagnostics); +public interface ToggleValueConverter { + Optional widgetStateToValue(boolean widgetState, ValidationDiagnostics diagnostics); + boolean valueToWidgetState(T value); } -@FunctionalInterface -public interface CycleValueParser { - Optional parse(CycleDirection direction, boolean includeHiddenOptions, ValidationDiagnostics diagnostics); - enum CycleDirection { FORWARD, BACKWARD } -} +MetadataType, ?> TOGGLE_VALUE_CONVERTER; -@FunctionalInterface -public interface SelectValueParser { - List parse(String search, ValidationDiagnostics diagnostics); +public interface CycleValueConverter { + Optional widgetStateToValue(int widgetState, ValidationDiagnostics diagnostics); + int valueToWidgetState(T value); + int valueCount(); + int hiddenValueCount(); } -@FunctionalInterface -public interface FreeTextValueParser { - Optional parse(String input, ValidationDiagnostics diagnostics); -} +MetadataType, ?> CYCLE_VALUE_CONVERTER; -@FunctionalInterface -public interface SliderValueParser { - Optional parse(double fraction, ValidationDiagnostics diagnostics); -} +// etc... +``` + +A Value Converter handles conversion between the stored value in a Setting and the canonical widget state. It also defines properties necessary for the widget to +properly handle user input. For example, toggle widgets' state is a boolean value (checked or unchecked), while the stored values in the Setting may be any two +values of any type. +### Formatter + +```java @FunctionalInterface -public interface NumericValueParser { - Optional parse(Number input, ValidationDiagnostics diagnostics); +public interface Formatter { + Text format(T value); } -``` -A Value Calculator handles user input on a given widget type in order to produce a value for a Setting. Depending on the UI widget, user input -may include text, key presses, and button presses. +MetadataType FORMATTER; +``` -// all -> turn raw input into a value (maybe Setting Validators should do this?) -// cycle -> get next/previous value -// slider -> get next/previous value + calculate value from percentage (and visa-versa) -// collections -> add/insert/remove/move an element +A Formatter is a function that converts a Setting's stored value into Text for displaying to players. This text is not meant to be mapped back to +the value that produced it. #### Label @@ -193,10 +191,12 @@ MetadataType ENVIRONMENT_POLICY; ## Drawbacks -Why should we not do this? - This API depends on (and is therefore limited by) Quilt Loader's configuration API. +This API also uses Minecraft types. Therefore, mod configuration that uses this API cannot be constructed or queried before game initialization (for example, +in mixin plugins or CHASM transformers). However, this type of configuration can't be changed during gameplay, so displaying it to users has limited +benefits. + ## Rationale and Alternatives - Why is this the best possible design? @@ -217,7 +217,8 @@ while avoiding including too many "batteries" that not all mods may use. ## Unresolved Questions -- What should be resolved before this RFC gets merged? +- How precisely should Value Converters define widget state? +- Should Setting Validators be separate from Loader's `Constraint` type? ### Implementation - Which other common formatter/validator/widget type instances should this API provide? E.g. enum, registry entry, `Identifier`, etc. From 9d5243176b4f9b537688a76ab97d386184df44ec Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Fri, 3 Jun 2022 22:00:19 -0500 Subject: [PATCH 08/10] rename to configuration metadata api --- specification/0000-common-configuration-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 2975e92c..8b57cc13 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -1,4 +1,4 @@ -# A Common Configuration API for QSL +# Configuration Metadata API ## Summary From 899e57cced499da3766bc4623b94dd9385fb5550 Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Fri, 3 Jun 2022 22:13:41 -0500 Subject: [PATCH 09/10] Update rationale and alternatives --- specification/0000-common-configuration-api.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specification/0000-common-configuration-api.md b/specification/0000-common-configuration-api.md index 8b57cc13..af8694d3 100644 --- a/specification/0000-common-configuration-api.md +++ b/specification/0000-common-configuration-api.md @@ -199,16 +199,17 @@ benefits. ## Rationale and Alternatives -- Why is this the best possible design? -- What other designs are possible and why should we choose this one instead? -- What other designs have benefits over this one? Why should we choose an - alternative instead? -- What is the impact of not doing this? - This RFC describes a common API between mods that define configuration and mods that consume configuration. This approach gives the most control to mods that wish to consume multiple mods' configuration, e.g. to construct a config screen, while avoiding including too many "batteries" that not all mods may use. +### Alternatives + +Define an API for constructing config UI elements that is completely separate from the underlying config. This would give mods more freedom to choose +specific UI representations. + +Do nothing. In the absence of a config API, mods will likely tend toward using fully featured GUI libraries for displaying configuration. + ## Prior Art - [ModConfig](https://github.com/kvverti/mod-config), a global config screen that extracts configuration metadata from mods that use Cloth UI. From 7d004fa72b52c6b27c845148311f3dc755606e7c Mon Sep 17 00:00:00 2001 From: Thalia Nero Date: Fri, 3 Jun 2022 22:15:38 -0500 Subject: [PATCH 10/10] Rename 0000-common-configuration-api.md to 0057-configuration-metadata-api.md --- ...on-configuration-api.md => 0057-configuration-metadata-api.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specification/{0000-common-configuration-api.md => 0057-configuration-metadata-api.md} (100%) diff --git a/specification/0000-common-configuration-api.md b/specification/0057-configuration-metadata-api.md similarity index 100% rename from specification/0000-common-configuration-api.md rename to specification/0057-configuration-metadata-api.md