Configuration

[Rongmario]

Summary

To provide a concise but extensive configuration API for devs, and for the players to edit config with ease whether in-game or in their filesystems.

Goals

• Establish a coherent configuration API with zero-confusion. From constructing configurations programmatically, along with how it is translated into a GUI screen to how the actual configuration files outputted.
• Abstracted logic to allow developers to provide their own GUI screens to edit their own configs without having to worry about parsing configurations themselves.
• Allow configuration to be modified, viewed asynchronously.
• Utilize a file watcher to watch over the configuration directory.
• Give developers access to other mods' configurations with ease.
• Provide API to register ways of parsing configuration values into specific objects. And it should be Cleanroom's job to provide default parsers for Minecraft objects.
• Incorporate ConfigAnytime's functionality natively. Configuration API shouldn't be late-loading.
• The configuration folder should be neater, files should match mod names, or at least in a nested folder if the mod wanted multiple configuration files that offers more explicitly categorized entries.

Non Goals

• This is not to provide a convention for configuration formats (JSON/HOCON/TOML etc), that may come in a different CFP.
• We are not restricting developers to only be able to use this API for configuration, that is out of the scope and rather obtuse.

Motivation

• Forge configurations had always been a "so close yet so far" situation with great annotation processing, yet it fails in so many places.
  • No public way of adding additional types to be parsed, only String, arrays and primitives by default.
  • ConfigManager loads in too late, and only works after asm data had been gathered. ConfigAnytime was made to circumvent this.
  • Relies heavily on annotations, whilst being under-documented; the other programmatic way isn't documented whatsoever.
  • Quirks in the system: classloading issues.
• We do not want to see the configuration folder become a wild-west like in imaginary version environments running on the Fabric loader.
• Fluent configuration standards are nice.

Description

The typical configuration class looks like this for Forge mods:

@Config(modid = "modid")
public class ConfigClass {
    
    public static boolean configBooleanProperty = true;
    public static int configIntProperty = 42;
    
    public static final SubCategory SUB_CATEGORY = new SubCategory();
    
    public static class SubCategory {
        
        public boolean innerProperty = false; // Must be non-static, referenced via the member field in the outer class
        
    }
    
    // This has to be here for the configuration to be referenced early
    // The mod must depend on ConfigAnytime, which is yet another dependency for such a simple task
    // This static block also has to be explicitly placed here
    static {
        ConfigAnytime.register(ConfigClass.class);
    }
    
}

and the outputted modid.cfg (the whitespace at the bottom isn't added in on purpose):

# Configuration file

general {
    B:configBooleanProperty=true
    I:configIntProperty=42

    sub_category {
        B:innerProperty=false
    }

}

I believe the current @Config annotation does serve well, without any extraneous getters/setters, you are able to set config properties, however, it isn't very reactive and you will have to refresh the ConfigManager of any changes.

-@Config(modid = "modid")
+@Config // mod id should be inferred

First of all, the mod id should be inferred; we should try to eliminate places to state the mod id other than the mod's main class and/or manifest. The value in those constant areas should propagate properly.

-public static boolean configBooleanProperty = true;
+public static final Observable<Boolean> configBooleanProperty = Observable.of(true);

(note: syntax isn't final!)
While more verbose, the field types should be converted to something that is observable. Not only does this allow devs to react to configuration changes on an entry-to-entry basis, it also allows for file watchers to change in-memory configuration entries singularly.

For file watchers, since Java's APIs do not offer any type of callback. We will have to poll on a different thread to watch for configuration changes and react to these Observables on our own. This may be a drawback and may have to be an opted-in/opted-out service for each configuration class.

-public static class SubCategory {
-        
-        public boolean innerProperty = false; // Must be non-static, referenced via the member field in the outer class
-       
-}
+ ? Suggestions are welcome ?

Currently, inner classes seem fine, but it may depend on how complex the implementation ends up.

-ConfigAnytime.register(ConfigClass.class);

ConfigAnytime will be absorbed and replaced. It will have no place anymore where our configuration system can be loaded at any point in time. We will have a mock mod container so existing mods that depends on it do not break.

/**
 * Abstracts the types of properties away. Higher level logic must prevent invalid data types.
 */
interface ITypeAdapter
{
    /**
     * Assigns the default value to the property
     * @param property the property whose default value will be assigned
     * @param value the default value
     */
    void setDefaultValue(Property property, Object value);

    /**
     * Sets the properties value.
     * @param property the property whose value will be set
     * @param value the set value
     */
    void setValue(Property property, Object value);

    /**
     * Retrieves the properties value
     * @param prop the property whose value will be retrieved
     * @return the properties value
     */
    Object getValue(Property prop);

    Type getType();

    boolean isArrayAdapter();
}

Forge currently offers ITypeAdapter but it is package-private, and never meant for devs to touch. But we will change that, and offer something more abundant. First, it definitely will have to be generic, for any type. The "adapter" should instead cover both serializing and deserializing. The "generic" way also means arrays won't have to be treated differently.

interface TypeAdapter<T> {

    T deserialize(String key, String value); throws IllegalTypeDeserializationException
    
    String serialize(String key, T value); throws IllegalTypeSerializationException

}

More description describing more of the API in the coming days!

Dependencies

• This may depend on the mod loading revamp CFP that will be made in the coming days.

References

No response

Guidelines

• I have and will continue to adhere to the guidelines

[Ecdcaeb]

@Config

Modders could select their file types here.

Enum

(https://github.com/Ecdcaeb/Cleanroom/blob/config_filewapper/src/main/java/net/minecraftforge/common/config/Config.java#L54)

Registry

java.lang.String here. And get the Coder from a registry. Actually, enum is a static registry I throught.

FileType

Do not breaking change the existing Configuration loading system, but remove load and save, and use polymorphism to support multiple file types.

JSON

JSON is not suitable as a configuration file, and we should not consider support for JSON.

• have not comment.
• not friendly for player
• not forced formated

There are lots of file types that are better than json, such as toml and cfg.

[Rongmario]

Though with the way you have done it, only static final enum values are accepted (since its part of an annotation). We would want it to be extensible, and why not JSON?

[ZZZank]

JSON is actually a good file format for devs, since it's usually structured to be similar to how corresponding Java class is structured. Designing via JSON will be easier then designing via Java.
I once came up with an idea on the Config system, and its data structure can be represented by JSON below:

{
    "percent": {
        "$comment": "single line comment",
        "$defaults": { "$min": 0, "$max": 100, "$value": 20 },
        "$value": 20
    },
    "enable": {
        "$comment": [
            "multi-line?"
        ],
        "$defaults": { "value": true },
        "$value": false
    },
    "someSubCategory": {
        "sub":{
            "$defaults": { "$all": ["NO", "YES"], "$value": "NO" },
            "$value": "NO"
        }
    }
}

property

So for each entry in a config, sub-categories included, there should be:

• a name, e.g. precent, that can be used for indexing
• default setups represented by $defaults, and
• the actual value represented by $value.
  Java class may look like this:

interface IConfigProp<T> {
    T get(); //get value
    String getName(); //get name
    UnmodifiableList<String> getComments();
    IConfigDefaults<T> getDefaults(); //get default setup
    T_ <T_> getAs(Class<T_> type);
}

T can be category, so sub-category is supported.

comments

I recommend using List or at least String[] for comments, since representing multi-line comments(new ArrayList<>()), single line comment(Collections.singletonList()) and no comment(Collections.emptyList()) can all be easy.

defaults

$defaults here, should be another Java class that is responsible for checking if the value read from file is valid, and providing default value when there is no valid value.

interface IConfigDefaults<T> extends Predicate<T> {
    boolean test(T value);
    T getDefaultValue();
}

All "bounds" related data, like $min $max ranges for int, or $all for enum, should be hold by IConfigDefaults.

[Rongmario]

I personally am against JSON because of the poor readability format with the stringent syntax, a minor typo can be hard to diagnose especially with Gson's error messages when parsing.

The interfaces looks good and aren't verbose.

As I've written in the OP, the goal isn't to propose a configuration language/format/denotation (JSON or what not). That can come in a separate proposal (I know that most people in the discord have expressed likeability and interest towards TOML and HOCON).

[ZZZank]

I'm using JSON here just because it's handy for illuatrating my idea on the data structure of config internals, actual config should indeed be format-independent. And glad to hear that The interfaces looks good :)

[Rongmario]

Good stuff ^^

[Ecdcaeb]

I want to be able to trace the owner of a Configuration, like:

public class ModConfiguration extends Configuration {
    public final String modId;
    public final Class<?> clazz;

    public ModConfiguration(String modidIn, Class<?> clazzIn, File file){
        super(fileWrapper);
        modId = modidIn;
        clazz = clazzIn;
    }
}

When creating a class-based config for an FMLMod：

- cfg = new Configuration(file);
+ cfg = new ModConfiguration(modid, cls, file);

This is just a simple example, and other methods can also be used to record. However, the two existing Maps cannot be traced back.

    private static Map<String, Configuration> CONFIGS = Maps.newHashMap();
    private static Map<String, Set<Class<?>>> MOD_CONFIG_CLASSES = Maps.newHashMap();

Creating an additional Map can also solve the problem, but I think creating and using subclasses is more in line with human logic.

[Ecdcaeb]

ConfigAnytime aims to enable configurations to be registered at any time. How can this be achieved when applied to decoders? Here is a perverted example: our decoder itself also relies on configuration files! ConfigAnytime requires that it can be used at any time, even if fml mods are not in the classpath. We may need a plugin or service that is earlier than Coremod to accomplish this, which can satisfy the use of coremod and mods, but still cannot satisfy the perverted example above. What I want to ask is: Can Anytime in ConfigAnytime have an upper limit?

the upper limit is the static block of LoadPlugin, we may use Service to complete the registration before this.

[kappa-maintainer]

The path info needed by ConfigManager was set in FMLTweaker, butForge doesn't even begin coremod discovery when FMLTweaker was run.
Example: Fugue sync config at the static block of LoadPlugin, which is the earliest point any coremod could reach.
Please read source before commenting.

[Ecdcaeb]

This is a design confirmation.

[Ecdcaeb]

Currently, the class-based configuration method is inconvenient to migrate. If I want to modify its format, I still need to keep the old fields for compatibility. This leads to many problems:

1. It doesn't look good
2. If the player does not actively modify it, the old configuration fields will always exist
3. Config version cannot be used in this situation. In another API it works fine.

Therefore, we need: ConfigFixUpper