diff --git a/docs/bedrock/_category_.json b/docs/bedrock/_category_.json new file mode 100644 index 0000000..1b96f8c --- /dev/null +++ b/docs/bedrock/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Bedrock", + "position": 2 +} \ No newline at end of file diff --git a/docs/bedrock/e-config.md b/docs/bedrock/e-config.md new file mode 100644 index 0000000..bca0b64 --- /dev/null +++ b/docs/bedrock/e-config.md @@ -0,0 +1,39 @@ +--- +title: EConfig +sidebar_position: 2 +--- + +## Features + +- Simple Bukkit FileConfiguration creation and maintaining. +- File versioning, to prevent data loss. +- Backup creation in case of an erroneous config file. + +## How to use + +### Config setup + +To make use of the config wrapper, the class containing the targeted data fields has to extend the +[StorageDataContainer](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/EConfig.java) class. +The config itself requires 2 arguments in order to work: + +- `File` - Defines which file should be used to create the FileConfiguration. +- `int` - The current config version. If a loaded version is outdated, all missing values will be added. + +```java +public class ExampleConfig extends EConfig { + + public static final int CONFIG_VERSION = 1; + + public ExampleConfig() { + super(new File("path/file.yml"), CONFIG_VERSION); + } + + @Override + public void load() { + // This method has to be implemented & should contain every class value. + } +} +``` + +Replace `path` with the actual path to the file you want to use and `file` with the name of the file. \ No newline at end of file diff --git a/docs/bedrock/intro.md b/docs/bedrock/intro.md new file mode 100644 index 0000000..717ed52 --- /dev/null +++ b/docs/bedrock/intro.md @@ -0,0 +1,109 @@ +--- +title: Introduction +sidebar_position: 1 +--- + +# Bedrock + +[![Codacy Badge](https://api.codacy.com/project/badge/Grade/158b774a4d4b4a7a9368af58f96d5dd9)](https://app.codacy.com/gh/DRE2N/Bedrock?utm_source=github.com&utm_medium=referral&utm_content=DRE2N/Bedrock&utm_campaign=Badge_Grade_Settings) + +Core library for Bukkit plugins of DRE2N, containing commands, configurations, user caching and more. + +## Features + +- A simple command system with TabCompletion, Subcommands, command requirements and permission support. + +- A FileConfiguration class loader for easy config access and management. + +- An advanced FileConfiguration class loader used via annotations and wrapper classes. + +- An easy way to load multiple language files and its messages. Messages might contain placeholders, + which will be replaced with provided arguments (if given) on access. + +- The MessageUtil class offers adventure's [MiniMessage](https://github.com/KyoriPowered/adventure) support, + message centering and other helpful message utilities. + +- A JavaPlugin extension class to manage plugin configs, version control, language files, permission/economy + provider and plugin updater. + +- Simple and RAM efficient User caching with basic User interface class to override, providing onJoin and + onQuit methods. + +- A bunch of other utility classes and methods to simplify the development process. + +## Compatibility + +This library supports paper version 1.18.2 and higher. Non-paper versions do build but lack some features, +mostly related to adventure's MiniMessage. + +## DRECommons + +This library is an updated paper-only version of [DRECommons](https://github.com/DRE2N/DRECommons). + +## Building + +### Maven + +```xml + + + + de.erethon:bedrock + + + + + de.erethon.bedrock + de.erethon.example.bedrock + + + + + + + erethon-repo + https://erethon.de/repo/ + + + + + + + de.erethon + bedrock + 1.2.5 + compile + + +``` + +### Gradle (Kotlin) + +Building with Gradle requires the [Gradle Shadow](https://github.com/johnrengelman/shadow) plugin. + +```kotlin +// Add the Gradle Shadow plugin +plugins { + id("com.github.johnrengelman.shadow") version "7.1.2" +} + +// Add Erethon repository +repositories { + maven { + url = uri("https://erethon.de/repo/") + } +} + +// Add Bedrock dependency +dependencies { + implementation("de.erethon:bedrock:1.2.5") +} + +// Relocate Bedrock inside shadowJar task +shadowJar { + dependencies { + include(dependency("de.erethon:bedrock:1.2.5")) + } + relocate("de.erethon.bedrock", "de.erethon.example.bedrock") +} +``` \ No newline at end of file diff --git a/docs/bedrock/storage-data-container.md b/docs/bedrock/storage-data-container.md new file mode 100644 index 0000000..8f75dc6 --- /dev/null +++ b/docs/bedrock/storage-data-container.md @@ -0,0 +1,316 @@ +--- +title: StorageDataContainer +sidebar_position: 3 +--- + +## Features + +- Serialization based on class types, to store data inside Bukkits FileConfiguration. +- Automatic data management, configured by declaring annotations above the desired fields. +- Reduction of unneeded explicit code. + +## Container setup + +To make use of the storage system, the class containing the targeted data fields has to extend the +[StorageDataContainer](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageDataContainer.java) class. +The container itself requires 2 arguments in order to work: + +- `File` - A file to store the data at +- `int` - The current config version + +**See the [Config Wrapper](/bedrock/e-config) class for more details** + +```java +public class ExampleStorageDataContainer extends StorageDataContainer { + + public static final int CONFIG_VERSION = 1; + + public ExampleStorageDataContainer() { + super(new File("path/file.yml"), CONFIG_VERSION); + } +} +``` + +Replace `path` with the actual path to the file you want to use and `file` with the name of the file. + +### Adding data fields + +You can add a data field by simply adding the [StorageData](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageData.java) +annotation above the desired class field. + +```java +@StorageData +private String string = "This is a String"; +``` + +The annotation without specifications is already enough to let the StorageDataContainer do its work. +But in order to achieve the desired loading, storing & saving behaviour, additional arguments are necessary. + +### Adding additional containers + +You can also add additional container classes, inside a container. Additional containers are not required to extend the +[StorageDataContainer](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageDataContainer.java) +class, as they're managed by the original container as well. Hence, those containers offer more freedom to use. + +```java +@AdditionalContainer +private YourAdditionalContainerClass additionalContainer = new YourAdditionalContainerClass(); +``` + +:::note + +Adding data fields inside an additional container works exactly the same as inside actual containers. + +::: + +## Data field options + +### Custom path + +While no explicit path is set, the field name itself will be used in order to store the field's value. +If the field is named `string`, the configuration path would also be `string`. +So the config would look like this: + +```yaml +string: "This is a String" +``` + +To change this, a custom path has to be specified inside the annotation's args. + +Example: + +```java +@StorageData(path = "customPathToString") +private String string = "This is a String"; +``` + +Will lead to: + +```yaml +customPathToString: "This is a String" +``` + +### Initialization + +There are two different options for initialization available: + +- `true (default)` - The pre-existing value will be saved inside the config, if the config doesn't contain a value at given path already. +- `false` - Nothing happens on initialization. + +### Logging + +This option sets the logging behaviour. + +- `true` - Initializing, loading and saving the object will be logged. +- `false (default)` - Nothing will be logged. + +Example: + +```java +@StorageData(log = true) +``` + +### Debugging + +This option sets the debugging behaviour. +Debug messages contain a lot more information about the value itself and each step of initializing, loading & saving process, than logging does. + +- `true` - Initializing, loading and saving the object will be debugged step-by-step. +- `false (default)` - Nothing will be debugged. + +Example: + +```java +@StorageData(debug = true) +``` + +### Nullability + +This option sets the behaviour for handling null values on load. + +- `LOAD (default)` - Null values will be loaded and saved. +- `IGNORE` - Null values won't be loaded or saved. +- `FORBID` - Null values won't be loaded or saved and an error message will be sent. + +Example: + +```java +@StorageData(nullability = Nullability.FORBID) +``` + +Related to this option, a custom message for forbidden null values can be specified as well. + +Using: + +```java +@StorageData(forbiddenNullMessage = "Custom error message here") +``` + +### Saving + +There are three different options for saving available, whenever the container starts the saving process: + +- `ALWAYS` - The data will always be saved. +- `CHANGES (default)` - The data will only be saved, if it was changed. +- `NONE` - The data won't be saved at all. + +Example: + +```java +@StorageData(save = StorageDataSave.ALWAYS) +``` + +### Key types + +This option sets the class type of each key occurring inside an object's class parameters. +This is required while using a Map, as well as the `valueTypes` option. + +Example: + +```java +@StorageData(keyTypes = String.class) +private Map stringIntegerMap = new HashMap<>(); +``` + +:::note + +In this example, other **necessary** options are not displayed. For correct usage of Maps, see **[this](#maps)**. + +::: + +### Value types + +This option sets the class type of each value occurring inside an object's class parameters. +This is required while using a Collection or Map. + +Example: + +```java +@StorageData(valueTypes = Integer.class) +private List integerList = new ArrayList<>(); +``` + +### Override field types + +When using a Collection or Map, the field type is often stated as an interface (e.g. `List`). +To create a new List, you need to use an implementation of such. So in order to use a List here, +the correct implementation type has to be defined as well. + +Example: + +```java +@StorageData(type = ArrayListc.class, valueTypes = Integer.class) +private List integerList = new ArrayList<>(); +``` + +## Additional container options + +### Custom sub-path + +An additional container might have set a sub-path, which gets prepended before each path inside it. +By default, the sub-path is empty. + +Path scheme for the data field: `{SUBPATH}{PATH}` + +Example: + +```java +@AdditionalContainer(subPath="additional.") +private YourAdditionalContainerClass additionalContainer = new YourAdditionalContainerClass(); +``` + +Inside the additional container: + +```java +@StorageData(path="customPathToString") +private String string = "A String"; +``` + +Path of the String: `additional.customPathToString` + + +There is also a special behaviour for paths inside an additional container. When set to `#`, only the `subPath` will be used, +without adding its field name etc. + +Example: + +```java +@AdditionalContainer(subPath = "additionalContainer") +private YourAdditionalContainerClass additionalContainer = new YourAdditionalContainerClass(); +``` + +Inside the additional container: + +```java +@StorageData(path = "#") +private String string = "This is a String"; +``` + +Path of the String: `additionalContainer` + +:::note + +Paths containing `#` won't work, outside an additional container. + +::: + +## Using complex data types + +### Collections + +Here are some examples of how to use the system with Collections. + +```java +// Stating the implementation type in the annotation args. +@StorageData(type = ArrayList.class, valueTypes = String.class) +private List stringList = new ArrayList<>(); + +// Stating the implementation type in the field itself. +@StorageData(valueTypes = String.class) +private ArrayList stringList = new ArrayList<>(); +``` + +Collections containing another Collection: + +```java +@StorageData(valueTypes = {List.class, String.class}) +private ArrayList> stringListList = new ArrayList<>(); +``` + +:::note + +Inner Collections will always be ArrayLists, when deserialized. There is currently no way of changing this behaviour, but there might be in the future. + +::: + +### Maps + +Here are some examples of how to use the system with Maps. + +```java +// Stating the implementation type in the annotation args. +@StorageData(type = HashMap.class, keyTypes = String.class, valueTypes = Integer.class) +private Map stringIntegerMap = new HashMap<>(); + +// Stating the implementation type in the field itself. +@StorageData(keyTypes = String.class, valueTypes = Integer.class) +private HashMap stringIntegerMap = new HashMap<>(); +``` + +Maps containing another Map: + +```java +@StorageData(keyTypes = {String.class, Integer.class}, valueTypes = {Map.class, Boolean.class}) +private HashMap stringIntegerBooleanMap = new HashMap<>(); +``` + +:::note + +Inner Maps will always be HashMaps, when deserialized. There is currently no way of changing this behaviour, but there might be in the future. + +::: + +### Custom data types + +Using custom data types requires the registration of a [StorageDataTranslator](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageDataTranslator.java). +For the specific class type. See [next](/bedrock/storage-data-translators) page. \ No newline at end of file diff --git a/docs/bedrock/storage-data-translators.md b/docs/bedrock/storage-data-translators.md new file mode 100644 index 0000000..f22071b --- /dev/null +++ b/docs/bedrock/storage-data-translators.md @@ -0,0 +1,113 @@ +--- +title: StorageDataTranslators +sidebar_position: 4 +--- + +All data types you want to use, require a registered implementation of the +[StorageDataTranslator](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageDataTranslator.java) class, +for the matching class type. The [StorageDataTranslators](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageDataTranslators.java) +class out of the box already has a variety of translators registered to it. + +## Default translators + +### Java natives + +- `Boolean` (java.lang.Boolean) +- `Collection` (java.util.Collection) +- `Double` (java.lang.Double) +- `Enum` (java.lang.Enum) +- `Integer` (java.lang.Integer) +- `Long` (java.lang.Long) +- `Map` (java.util.Map) +- `Object` (java.lang.Object) +- `Serializable` (java.io.Serializable) +- `Short` (java.lang.Short) +- `String` (java.lang.String) +- `UUID` (java.util.UUID) + +### External classes + +- `Location` (org.bukkit.Location) +- `StringIgnoreCase` (de.erethon.bedrock.misc.StringIgnoreCase) + +**See a more detailed list [here](https://github.com/DRE2N/Bedrock/blob/master/src/main/java/de/erethon/bedrock/config/storage/StorageDataTranslators.java).** + +## Registering custom translators + +Let's start by creating a custom data class, containing 3 different values. + +```java +public class CustomData { + + /* some values */ + private final String string; + private final int integer; + private final boolean aBoolean; + + /* simple constructor*/ + public CustomData(String string, int integer, boolean aBoolean) { + this.string = string; + this.integer = integer; + this.aBoolean = aBoolean; + } + + /* getter */ + + public String getString() { + return string; + } + + public int getInteger() { + return integer; + } + + public boolean getBoolean() { + return aBoolean; + } +} +``` + +Registering a matching translator would look like: + +```java +StorageDataTranslators.registerDataTranslator(new StorageDataTranslator<>(CustomData.class, o -> { + CustomData data = (CustomData) o; + Map serialized = new HashMap<>(3); // Size of 3, because there are 3 values. + serialized.put("string", data.getString()); + serialized.put("integer", data.getInteger()); + serialized.put("aBoolean", data.getABoolean()); + return serialized; // Return the serialized map. +}, o -> { + ConfigurationSection section = (ConfigurationSection) o; // Maps are loaded as ConfigurationSections. + String string = section.getString("string"); + int integer = section.getInt("integer"); + boolean aBoolean = section.getBoolean("aBoolean"); + return new CustomData(string, integer, aBoolean); // Return the deserialized value. +})); +``` + +:::note + +There are many ways to serialize and deserialize values. This is just a basic example of how it could look like. + +::: + +### Error handling for deserialization + +Errors thrown while deserializing values will we sent into the console. Values which deserialization failed, +will be treated as null values and will be therefore handled by the defined [nullability behaviour](/bedrock/storage-data-container#nullability). + +## Override default translators + +To override a default translator, just register a data translator for the same class type. +This can be done via the same method as registering a new translator. + +Example: + +```java +StorageDataTranslators.registerDataTranslator( + new StorageDataTranslator<>(Integer.class, o -> o, o -> o instanceof Integer ? (int) o : -1) +); +``` + +This would load integers normally, but set the default value of non-integers to `-1`. diff --git a/docs/itemsxl/_category_.json b/docs/itemsxl/_category_.json deleted file mode 100644 index 390dc23..0000000 --- a/docs/itemsxl/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "ItemsXL", - "position": 5 -} \ No newline at end of file diff --git a/docs/itemsxl/intro.md b/docs/itemsxl/intro.md deleted file mode 100644 index c3c98ba..0000000 --- a/docs/itemsxl/intro.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Introduction -sidebar_position: 1 ---- - -TODO \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index e0215bb..6c7392c 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -2,7 +2,7 @@ // Note: type annotations allow type checking and IDEs autocompletion const lightCodeTheme = require('prism-react-renderer/themes/github'); -const darkCodeTheme = require('prism-react-renderer/themes/dracula'); +const darkCodeTheme = require('prism-react-renderer/themes/vsDark'); /** @type {import('@docusaurus/types').Config} */ const config = { @@ -12,7 +12,7 @@ const config = { baseUrl: '/docs/', onBrokenLinks: 'warn', onBrokenMarkdownLinks: 'warn', - favicon: 'img/favicon.ico', + favicon: 'img/favicon.png', organizationName: 'DRE2N', // Usually your GitHub org/user name. projectName: 'erethon-docs', // Usually your repo name. @@ -43,11 +43,16 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ + colorMode: { + defaultMode: 'dark', + disableSwitch: false, + respectPrefersColorScheme: true, + }, navbar: { title: 'Erethon', logo: { alt: 'Erethon Site Logo', - src: 'img/logo.svg', + src: 'img/logo.png', }, items: [ { @@ -76,15 +81,9 @@ const config = { }, { type: 'doc', - docId: 'aergia/intro', + docId: 'bedrock/intro', position: 'left', - label: 'Aergia', - }, - { - type: 'doc', - docId: 'itemsxl/intro', - position: 'left', - label: 'ItemsXL', + label: 'Bedrock', }, ], }, @@ -94,10 +93,6 @@ const config = { { title: 'Docs', items: [ - { - label: 'Welcome', - to: '/docs/welcome', - }, { label: 'DungeonsXL', to: '/docs/dungeonsxl/intro', @@ -111,12 +106,8 @@ const config = { to: '/docs/aether/intro', }, { - label: 'Aergia', - to: '/docs/aergia/intro', - }, - { - label: 'ItemsXL', - to: '/docs/itemsxl/intro', + label: 'Bedrock', + to: '/docs/bedrock/intro', }, ], }, @@ -127,6 +118,14 @@ const config = { label: 'Discord', href: 'https://dc.erethon.de', }, + { + label: 'Youtube', + href: 'https://www.youtube.com/@erethon', + }, + { + label: 'Instagram', + href: 'https://www.instagram.com/erethonmc', + }, ], }, { @@ -134,7 +133,7 @@ const config = { items: [ { label: 'Dev Blogs', - to: 'https://erethon.de/category/dev/', + to: 'https://erethon.de/blogs', }, { label: 'GitHub', @@ -146,8 +145,13 @@ const config = { copyright: `Copyright © ${new Date().getFullYear()} Erethon`, }, prism: { - theme: require('prism-react-renderer/themes/dracula'), - additionalLanguages: ['yaml'], + theme: lightCodeTheme, + darkTheme: darkCodeTheme, + additionalLanguages: [ + 'kotlin', + 'java', + 'yaml', + ], }, }), }; diff --git a/sidebars.js b/sidebars.js index 251c0c4..f9fa613 100644 --- a/sidebars.js +++ b/sidebars.js @@ -54,14 +54,14 @@ const sidebars = { ], }, ], - itemsxl: [ + bedrock: [ { type: 'category', - label: 'ItemsXL', + label: 'Bedrock', items: [ { type: 'autogenerated', - dirName: 'itemsxl', + dirName: 'bedrock', }, ], }, diff --git a/static/img/favicon.ico b/static/img/favicon.ico deleted file mode 100644 index c01d54b..0000000 Binary files a/static/img/favicon.ico and /dev/null differ diff --git a/static/img/favicon.png b/static/img/favicon.png new file mode 100644 index 0000000..ff37382 Binary files /dev/null and b/static/img/favicon.png differ diff --git a/static/img/logo.png b/static/img/logo.png new file mode 100644 index 0000000..13795fb Binary files /dev/null and b/static/img/logo.png differ diff --git a/static/img/logo.svg b/static/img/logo.svg deleted file mode 100644 index 9db6d0d..0000000 --- a/static/img/logo.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/static/img/tutorial/docsVersionDropdown.png b/static/img/tutorial/docsVersionDropdown.png deleted file mode 100644 index ff1cbe6..0000000 Binary files a/static/img/tutorial/docsVersionDropdown.png and /dev/null differ diff --git a/static/img/tutorial/localeDropdown.png b/static/img/tutorial/localeDropdown.png deleted file mode 100644 index d7163f9..0000000 Binary files a/static/img/tutorial/localeDropdown.png and /dev/null differ