Configuration system

Basics

Here you will find the information how to take advantage of using the AtumCore configuration api

As you have probably already noticed the library has its own Config class, with more methods to use.

There are currently 2 Config Types supported: JSON, YAML, and Upcoming TOML

Create config file

To create a config file you can use the following method:

AtumAPI.getInstance().createLoadableConfig()

It is automatically added to the ConfigManager of the AtumMod instance.

Save and Reload config file

Use ConfigManager in AtumMod

The parameter is the config file name without extension

How to work with Config object

Config class is pretty similar to the ConfigurationSection class from bukkit API.

But, unlike bukkit's class, Config has more methods to use that are quite useful for development.

Also, some methods are renamed. For example the method getConfigurationSection() has been renamed to getSubsection(), bcz I didnt like the large name of the bukkit method.

Major Config Methods

 * Set an object in config
 * <p></p>
 * Set null to remove the config section
 * <p></p>
 * You can also set a Config object, so it will be a subsection
 *
 * @param path The path.
 * @param obj  The object.
 void set(@NotNull String path, @Nullable Object obj)


 * Get an object in config
 *
 * @param path The path.
 * @return The object or null if not found.
 *
 Object get(@NotNull String path)


 * Get if the config contains a specified path
 *
 * @param path The path to check.
 * @return true if contains
 *
 boolean hasPath(@NotNull String path)


 * Get config keys.
 *
 * @param deep If keys from subsections should be added to that list as well
 * @return A list of the keys.
 *
 List<String> getKeys(boolean deep)


 * Get the config type
 *
 * @return The config type
 *
 ConfigType getType()


 * Get the mod that owns this config
 *
 * @return The mod instance.
 *
 AtumMod getAtumMod()


 * Get the AtumConfig subsection
 * <p></p>
 * Works the same way as FileConfiguration#getConfigurationSection
 *
 * @param path  The path.
 * @return The config, or empty {@link Config} if not found.
 *
 Config getSubsection(@NotNull String path)


 * Get the int
 *
 * @param path The path.
 * @return The int or 0 if not found.
 *
 int getInt(@NotNull String path)


 * Get the double
 *
 * @param path The path.
 * @return The double or 0 if not found.
 *
 double getDouble(@NotNull String path)


 * Get the boolean
 *
 * @param path The path.
 * @return The boolean or false if not found.
 *
 boolean getBool(@NotNull String path)


 * Get the string
 *
 * @param path The path.
 * @return The string or empty string if not found.
 *
 String getString(@NotNull String path)


 * Get the formatted string
 * <p></p>
 * The string will be formatted
 * with colors and global placeholders
 *
 * @param path The path.
 * @return The formatted string or empty string if not found.
 *
 String getFormattedString(@NotNull String path)


 * Get the evaluated expression
 * from string
 *
 * @param path The path.
 * @return The evaluated value.
 *
 double getEvaluated(@NotNull String path)

There are much more methods that can help you in development.

For example, most of the "get" methods are overloaded with "getOrNull", "getList", "getListOrNull".

I highly suggest you to check it out :)

Usage Examples

Iterate through all the values

 List<String> names = new ArrayList<>();
 for(String key : config.getKeys(false)){
     names.add(config.getString(key));
 }

Inject placeholders in config and then format

 config.injectPlaceholders(
         new StaticPlaceholder("name",()->"TEST"),
         new StaticPlaceholder("points", ()->"12")
 );
 
 List<String> names = new ArrayList<>();
 for(String key : config.getKeys(false)){
     names.add(config.getFormattedString(key));
 }

Get value from subsection

 String helloValue = getString("subsection.helloValue");
 //or
 String helloValue = getSubsection("subsection").getString("helloValue");

Save the value to config file

 config.set("test", 1);
 
 getAtumMod().getConfigManager().saveConfig("configName");
 //or
 ((LoadableConfig)config).save(); //it will work only if you are using the parent config, not its subsection, and which is created from file

Config Categories

Besides the single config files, you can create Configuration categories.

In a nutshell it is just the folder with configs and the configuration category contains & manages them

How to use it:

getConfigManager().addConfigCategory(ConfigCategory object)

ConfigCategory is an abstract class that has couple of important methods to implement.

Example:

  getConfigManager().addConfigCategory(new ConfigCategory(
            this,
            ConfigType.JSON,
            "display",
            "display",
            true) {
        private List<String> elements = new ArrayList<>();
        @Override
        protected void clear() {
            elements.forEach(it->getDisplayManager().getElementRegistry().unregisterTemplate(it));
        }
        @Override
        protected void acceptConfig(@NotNull String id, @NotNull Config config) {
            getAtumMod().getLogger().info("Loading display element with id " + id);
            if(getDisplayManager().getElementRegistry().getElementTemplate(id) != null) {
                getAtumMod().getLogger().warn("Display element with id " + id + 
                        " already added or is a default element!");
                return;
            }

            DisplayElement element = getDisplayManager().getElementRegistry()
                    .compileCanvasTemplate(id,config);
            if (element != null) {
                getDisplayManager().getElementRegistry().registerTemplate(id, element);
                elements.add(id);
            }
        }
    });

As you can see, here we use the config object to load the display template and on clear remove all loaded elements

How to start

AtumMod class detailed