UneiConfiguration banner

Description

UneiConfiguration is a plugin made by the UNEI developer team.

It allows other developers to easily read, create and manage configurations.

It supports a large variety of formats such as YAML, JSON, NBT, SQL, CSV, Java Properties (.properties and .lang files), or even "raw binary".

It aims at making it easier for developers to use other formats than YAML, since some of them are often more appropriate and more efficient to store different types of data.

UneiConfiguration also makes it incredibly simple to retrieve information from files such as .dat informations in Minecraft worlds, and even modify them.

Commands? Permissions?

In fact, UneiConfiguration is an API, or Application Programming Interface.

If you are not familiar with programming, this means that the plugin itself "doesn't do anything".

More precisely, it doesn't add any command or behavior to the game, thus doesn't have any permission.

Though, other developers are able to download this plugin and use it as an API in their own plugins.

If you install any plugin that uses UneiConfiguration, you will have to install this too on your server for the plugin to work properly.

How to use the plugin

UneiConfiguration is built in two different ways for each version:

As a Bukkit plugin (UneiConfiguration-x.x.x.jar)

To use UneiConfiguration as a plugin, simply install it on your server and add it as dependency in your plugin.yml as well as in your IDE.

You will then be able to use the API as showed below.

We also suggest that you check if UneiConfiguration is installed and, if it isn't, fallback to Bukkit's default YAML configuration system.

If you do this, make sure to add UneiConfiguration in soft-depend rather than depend in your plugin.yml file.

Also note that this version is also the one to use if you are on BungeeCord, Forge...

Standalone (UneiConfiguration-with-dependencies-x.x.x.jar)

If you use UneiConfiguration in an application outside of Minecraft, we use custom-coded classes to parse and serialize data in each of the format supported.

This is also necessary for really old versions of Bukkit, since the APIs we use ourselves are not always available.

That way, you don't have to bother loading any other class for UneiConfiguration to work, you just have to use the regular API like you would do on a regular, updated Bukkit server, and it will work exactly the same!

Using maven

To use UneiConfiguration in your plugin we recomend to use maven to add it as a dependency to your project.

To do that, you will first have to add our maven repository, which is hosted on GitHub Pages, to your pom.xml. Simply place the following code inside the <repositories> tag (next to the spigot-repo, bungeecord-repo and any other if you have one already, or if you don't, create a <repositories> tag):

<repository>
  <id>unei-repo</id>
  <url>https://unei.github.io/maven/</url>
</repository>

You will now have access to our projects, but you will not have access to UneiConfiguration's API yet, so you will have to add the following code in the <dependencies> tag, often under the <repositories> tag. If you want to use a specific version, you should replace the version number "LATEST" with the one you want to use:

<dependency>
  <groupId>me.unei</groupId>
  <artifactId>uneiconfiguration-api</artifactId>
  <version>LATEST</version>
  <!-- <classifier>jar-with-dependencies</classifier> -->
  <scope>provided</scope>
  <!-- <optional>true</optional> -->
</dependency>

You can change two things other than the version:

• Do you want the version with or without all the dependencies packaged?

If you know which version you are going to use, it is good practice to use this one in your dependencies. But if you don't know, you can simply use the normal version, without dependencies, by default, and you can always change if you have any problem later on.

To use the version with dependencies, uncomment (by removing "") the <classifier> tag in the code given above.

• Do you have a backup plan for configurations?

If you do, for example if you use Bukkit's configuration system in case UneiConfiguration is not available, then you should set the UneiConfiguration as optional. To do that, you will first have to move UneiConfiguration to soft-depend rather than depend in your plugin.yml.

Then, if your project can work without UneiConfiguration (even if some features will be disabled), uncomment (by removing "") the <optional> tag in the code given above.

Using the JAR file in your IDE

If you prefer not to use maven, you can simply add the JAR file to your IDE (Eclipse, IntelliJ, Atom...).

Since it is really different in each IDE, we will not make a detailed work through, but you can lookup a tutorial for yours specifically.

The JAR you will have to use in your IDE is the one you would have downloaded if you used it on a server, this means you can click the Download button on this page to get the latest version (without-dependencies).

If your IDE lets you add the javadocs too, you can download them on our GitHub Pages website: https://unei.github.io/

Even if, usually, the JavaDoc should also be included in the main JAR file so that you don't have to add another one separately.

Supported versions

If you use Bukkit for Minecraft 1.8 or later, you can safely use the regular version of the plugin, entitled UneiConfiguration-x.x.x.jar it will be faster to load and smaller as it does not contain duplicate code that would have to be loaded uselessly since these versions of Minecraft already provide them.

If you use Bukkit for Minecraft 1.7 or before (or even if your project doesn't require Bukkit), you will have to use the version with all our dependencies packaged in the JAR, entitled UneiConfiguration-with-dependencies-x.x.x.jar, since some of them are not included in Bukkit by default in these version. It can sometimes be 5 times heavier than the regular version, so it will be longer to download and slightly slower to load on the server, unfortunately.

Note that UneiConfiguration has been tested and will work on all versions from Bukkit 0.0.0 upto Bukkit 1.13.2, and works fine without any error. Yes, that's from the first build of Bukkit, ever, to the latest build, as of writing this at least.

We also have designed it not to break in future releases, but it could happen, so encounter any error, please wait a few days after a Bukkit update and check this page to see if there are any fixes, or report it in the "Issues" tab above.

UneiConfiguration also works fine on Spigot, PaperSpigot and most of the derivates.

We are working on making it compatible on Forge and other modded servers, as well as BungeeCord.

Even though it is not yet optimized for these platforms, you can still use it without any major issue.

Developer API

Here are a few examples of how to use our API in your plugin for each of the supported formats (it will work the same in a regular Java application if you adapt the arguments to work with your setup).

YAML Configuration Example

IYAMLConfiguration yamlConfig = Configurations.newYAMLConfig(plugin.getDataFolder(), "fileName");
IConfiguration yamlSubConfig = yamlConfig.getSubSection("sub_section_name");
yamlSubConfig.setString("key", "value");
yamlSubConfig.setInteger("more_sub_section.keyInt", 42);
yamlConfig.save();

yamlConfig.reload();
String value = yamlConfig.getString("sub_section_name.key");

NBT Configuration Example

INBTConfiguration nbtConfig = Configurations.newNBTConfig(plugin.getDataFolder(), "fileName");
IConfiguration nbtSubConfig = nbtConfig.getSubSection("sub_section_name");
nbtSubConfig.setString("key", "value");
nbtSubConfig.setInteger("more_sub_section.keyInt", 42);
nbtConfig.save();

nbtConfig.reload();
String value = nbtConfig.getString("sub_section_name.key");

JSON Configuration Example

IJSONConfiguration jsonConfig = Configurations.newJSONConfig(plugin.getDataFolder(), "fileName");
IConfiguration jsonSubConfig = jsonConfig.getSubSection("sub_section_name");
jsonSubConfig.setString("key", "value");
jsonSubConfig.setInteger("more_sub_section.keyInt", 42);
jsonConfig.save();

jsonConfig.reload();
String value = jsonConfig.getString("sub_section_name.key");

SQLite Configuration Example

ISQLiteConfiguration sqliteConfig = Configurations.newSQLiteConfig(plugin.getDataFolder(), "fileName");
IConfiguration sqliteSubConfig = sqliteConfig.getSubSection("sub_section_name");
sqliteSubConfig.setString("key", "value");
sqliteSubConfig.setInteger("more_sub_section.keyInt", 42);
sqliteConfig.save();

sqliteConfig.reload();
String value = sqliteConfig.getString("sub_section_name.key");

Flat SQLite Configuration Example

IFlatSQLiteConfiguration sqliteConfig = FlatConfigurations.newFlatSQLiteConfig(plugin.getDataFolder(), "fileName");
sqliteConfig.setString("key", "value");
sqliteConfig.setInteger("not_a_section.keyInt", 42);
sqliteConfig.save();

sqliteConfig.reload();
String value = sqliteConfig.getString("key");

Raw Binary Configuration Example

IConfiguration binaryConfig = Configurations.newBinaryConfig(plugin.getDataFolder(), "fileName");
IConfiguration binarySubConfig = binaryConfig.getSubSection("sub_section_name");
binarySubConfig.setString("key", "value");
binarySubConfig.setInteger("more_sub_section.keyInt", 42);
binaryConfig.save();

binaryConfig.reload();
String value = binaryConfig.getString("sub_section_name.key");

CSV Configuration Example

IFlatCSVConfiguration csvConfig = FlatConfigurations.newCSVConfig(plugin.getDataFolder(), "fileName");
csvConfig.setString("key", "value");
csvConfig.setInteger("not_a_section.keyInt", 42);
csvConfig.save();

csvConfig.reload();
String value = csvConfig.getString("key");

Java Properties Configuration Example

IFlatPropertiesConfiguration propConfig = FlatConfigurations.newPropertiesConfig(plugin.getDataFolder(), "fileName");
propConfig.setString("key", "value");
propConfig.setInteger("not_a_section.keyInt", 42);
propConfig.save();

propConfig.reload();
String value = propConfig.getString("key");

MySQL Configuration Example

IMySQLConfiguration sqliteConfig = Configurations.newMySQLConfig("127.0.0.1", 3306, "tableName", "username", "password");
IConfiguration mysqlSubConfig = mysqlConfig.getSubSection("sub_section_name");
mysqlSubConfig.setString("key", "value");
mysqlSubConfig.setInteger("more_sub_section.keyInt", 42);
mysqlConfig.save();

mysqlConfig.reload();
String value = mysqlConfig.getString("sub_section_name.key");

Flat MySQL Configuration Example

IFlatMySQLConfiguration mysqlConfig = FlatConfigurations.newFlatMySQLConfig("127.0.0.1", 3306, "tableName", "username", "password");
mysqlConfig.setString("key", "value");
mysqlConfig.setInteger("not_a_section.keyInt", 42);
mysqlConfig.save();

mysqlConfig.reload();
String value = mysqlConfig.getString("key");

Supported formats

• YAML (Bukkit's default configuration format)

• NBT (Mojang's .dat files)

• JSON (JavaScript Object Notation)

• SQLite (A file-based database)

• Flat SQLite (SQLite without sub-configurations)

• Raw Binary (Objects serialized as binary)

• CSV (Comma Separated Values)

• Java Properties (.properties and .lang files)

• MySQL (A regular remote database)

• Flat MySQL (MySQL without sub-configurations)

If you would like to see any other formats, please suggest them in the comments! We would be glad to help you support these.