Basic Setup
As ConfigurationMaster is a utility rather than a functional plugin, developers must know how to utilise it within their plugins.
Before you do use the utility, it's recommended that you have some sort of background knowledge with Java and using the Bukkit API. This is assumed when you start using the utility.
Contents:
ConfigurationMaster can be used as a dependency in two different ways: as a separate plugin or a shaded dependency.
Requiring the plugin separately will mean that users will have to install the plugin in addition to yours. However, you are not required to carry out any extra steps to make your plugin work with ConfigurationMaster; in addition, as the plugin updates, you will have to keep up to date on updates as well. On the other hand, whilst shading a dependency can be messy, it does mean that users do not have to do any extra work and can install your plugin all in one piece - and you are able to keep up with CM updates at your own pace, although it is recommended to keep up to date in order to access new features and avoid bugs that may appear.
For managing your dependencies, you are recommended to use a framework such as Maven or Gradle. As of currently, this wiki will cover Maven, but when ready, it will also cover Gradle. If others want to suggest and explain other frameworks as well, they are free to open an issue requesting it.
Maven Setup
As of currently, ConfigurationMaster uses Jitpack to host its jar file. To access it, add in the repository and dependency:
<repositories>
<repository>
<id>cm-repo</id>
<url>https://ci.pluginwiki.us/plugin/repository/everything/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.thatsmusic99</groupId>
<artifactId>ConfigurationMaster</artifactId>
<version>v1.0.1</version>
<scope>provided</scope>
</dependency>
</dependencies>If you are planning on shading the utility into your plugin, you need to remove the provided scope (since it tells Maven that the library will be present upon running and does not need shading).
After this, you need to add the Maven shade plugin to your pom.xml file. This is easily done by inserting the following towards the top of your pom.xml, above dependencies and repositories:
<build>
<plugins>
<plugin>
<!-- The Maven shade plugin itself. -->
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<artifactSet>
<!-- Include ConfigurationMaster in the shaded jar. -->
<includes>
<include>com.github.Thatsmusic99:ConfigurationMaster</include>
</includes>
</artifactSet>
<!-- This is optional - this renames the original package of CM to your own. -->
<relocations>
<relocation>
<pattern>io.github.thatsmusic99.configurationmaster</pattern>
<shadedPattern>com.pluginauthor.myplugin.configurationmaster</shadedPattern>
</relocation>
</relocations>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>Now, ConfigurationMaster should be saved to your jar when Maven is refreshed.
When you finally have the dependency set up, you're free to start using the API.
To create a config file using CM, you can either extend it...
public class MyConfigFile extends CMFile {
}... or call it in the middle of whatever function you're calling.
CMFile myConfigFile = new CMFile();When initialising CMFile, you need two arguments: your plugin and the name of the config.
If you're declaring the config inside your main class, that makes life easier, as you can just do this, where the config is going to be named "config.yml":
public class MyPlugin extends JavaPlugin {
@Override
public void onEnable() {
CMFile myConfigFile = new CMFile(this, "config");
}
}However, if you're either extending the class or declaring the config elsewhere, you have to get the plugin instance.
If you're unfamiliar with instances, you can easily set one up to get your plugin's main class smoothly and easily:
public class MyPlugin extends JavaPlugin {
// Creates a private static place to store the instance.
private static MyPlugin instance;
@Override
public void onEnable() {
// Make the instance the one currently running onEnable.
instance = this;
}
public static MyPlugin getInstance() {
// Then return it.
return instance;
}
}From there, you can use it through either of the following examples, depending on what you're doing:
CMFile myConfigFile = new CMFile(MyPlugin.getInstance(), "config");public class MyConfigFile extends CMFile {
public MyConfigFile() {
super(MyPlugin.getInstance(), "config");
}
}Because CMFile is abstract, it will initialise a method called loadDefaults:
CMFile myConfigFile = new CMFile(this, "config") {
@Override
public void loadDefaults() {
}
};This is where the utility prefers you declare your default values. To try and keep the system as familiar as possible, you can add default values using the addDefault method, which also follows Bukkit's config system:
CMFile myConfigFile = new CMFile(this, "config") {
@Override
public void loadDefaults() {
addDefault("foo", "bar");
}
};However, if you want to add comments, then there are two ways this can be done; either by using an alternative addDefault method or the addComment method:
CMFile myConfigFile = new CMFile(this, "config") {
@Override
public void loadDefaults() {
// Using addComment
addComment("Hello, world!");
addDefault("foo", "bar");
// Using addDefault
addDefault("test", "test1", "Testing 1, testing 2!");
}
};If you want, you can also add a section to the config, using the addSection method:
CMFile myConfigFile = new CMFile(this, "config") {
@Override
public void loadDefaults() {
// Add a section
addSection("Important Stuff");
// Using addComment
addComment("Hello, world!");
addDefault("foo", "bar");
// Using addDefault
addDefault("test", "test1", "Testing 1, testing 2!");
}
};CM adds comments and options in the order they were added. So in the resulting config, you will have the section "Important Stuff" first, followed by the comment "Hello, world!", the option foo with the value "bar" and the option test with the value "test1" and the comment "Testing 1, testing 2!":
###################
# Important Stuff #
###################
# Hello, world!
foo: bar
# Testing 1, testing 2!
test: test1Now that you have your default options set up, you're free to either load the configuration or tweak some of the header options, which will be described in a separate page. In this situation, we'll just load the config.
myConfigFile.load();And that is the basics of ConfigurationMaster! This leaves you with the code:
CMFile myConfigFile = new CMFile(this, "config") {
@Override
public void loadDefaults() {
// Add a section
addSection("Important Stuff");
// Using addComment
addComment("Hello, world!");
addDefault("foo", "bar");
// Using addDefault
addDefault("test", "test1", "Testing 1, testing 2!");
}
};
myConfigFile.load();or
public class MyConfigFile extends CMFile {
public MyConfigFile() {
super(MyPlugin.getInstance(), "config");
load();
}
@Override
public void loadDefaults() {
// Add a section
addSection("Important Stuff");
// Using addComment
addComment("Hello, world!");
addDefault("foo", "bar");
// Using addDefault
addDefault("test", "test1", "Testing 1, testing 2!");
}
}To later reload the config, just use the reload method:
myConfigFile.reload();CM has no inbuilt methods for fetching values as it handles the layout of the configuration.
Thus, you would fetch config values simply using the #getConfig method and using the Bukkit API, as per usual.
String bar = myConfigFile.getConfig().getString("foo");