From d6149879e95c6ce95b98e6bff896df9697b6b155 Mon Sep 17 00:00:00 2001 From: kyngs Date: Tue, 25 Jun 2024 00:04:55 +0200 Subject: [PATCH] Expand the documentation --- docs_asp/API/examples.md | 7 ---- docs_asp/api/importing_worlds.md | 43 ++++++++++++++++++++ docs_asp/api/index.md | 6 +++ docs_asp/api/loaders.md | 56 ++++++++++++++++++++++++++ docs_asp/api/loading_worlds.md | 46 +++++++++++++++++++++ docs_asp/api/properties.md | 29 ++++++++++++++ docs_asp/api/using.md | 69 ++++++++++++++++++++++++++++++++ docs_asp/migrating.md | 20 +++++++++ docs_asp/swp/index.md | 8 +++- docs_asp/swp/installation.md | 2 +- docusaurus.config.js | 5 +++ 11 files changed, 282 insertions(+), 9 deletions(-) delete mode 100644 docs_asp/API/examples.md create mode 100644 docs_asp/api/importing_worlds.md create mode 100644 docs_asp/api/index.md create mode 100644 docs_asp/api/loaders.md create mode 100644 docs_asp/api/loading_worlds.md create mode 100644 docs_asp/api/properties.md create mode 100644 docs_asp/api/using.md create mode 100644 docs_asp/migrating.md diff --git a/docs_asp/API/examples.md b/docs_asp/API/examples.md deleted file mode 100644 index 45c73b4..0000000 --- a/docs_asp/API/examples.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Examples - -Hello World! \ No newline at end of file diff --git a/docs_asp/api/importing_worlds.md b/docs_asp/api/importing_worlds.md new file mode 100644 index 0000000..de872ee --- /dev/null +++ b/docs_asp/api/importing_worlds.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 6 +--- + +# Importing Worlds + +The ASP API provides a way to import Minecraft worlds (in the anvil format) into slime worlds.\ +This is useful if you have a world that you want to use with the ASP API, but it is not a slime world yet.\ +Similar to loading worlds, this process is split into multiple stages: +- Importing the world from the anvil format to the slime format (can be done asynchronously) +- Saving the world into the loader (must be done asynchronously) +- Loading the world into the server (must be done synchronously) + +## Reading the World +Firstly, we need to read the world from the anvil format into memory and deserialize it.\ +To read an anvil world, you need to use the `readVanillaWorld` method in the `AdvancedSlimePaperAPI` class.\ +**Remember: this is an I/O operation and should be done asynchronously.** + +```java +/* + * new File(".") - the directory where the world is located + * "world" - the name of the world to read + * loader - the loader where the world will be stored when saved, or null if it is read-only + */ +SlimeWorld world = asp.readVanillaWorld(new File("."), "world", loader); +// Now we have a deserialized -in-memory- representation of the world +``` + +## Saving the World +After we have read the world from the anvil format, we can now save it into the loader (assuming we supplied one in the previous step).\ +To save a world, you need to use the `saveWorld` method in the `AdvancedSlimePaperAPI` class.\ +**Remember: this is an I/O operation and should be done asynchronously.** + +```java +/* + * world - the deserialized world to save, obtained from the previous step + */ +asp.saveWorld(world); +``` + +## Loading the World +After we have saved the world into the loader, we can now load it into the server.\ +This process is the same as in the [Loading Worlds](loading_worlds#loading-the-world) page. \ No newline at end of file diff --git a/docs_asp/api/index.md b/docs_asp/api/index.md new file mode 100644 index 0000000..d1d73da --- /dev/null +++ b/docs_asp/api/index.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 90 +--- +# API + +Advanced Slime Paper provides an API that allows you to manage slime worlds. diff --git a/docs_asp/api/loaders.md b/docs_asp/api/loaders.md new file mode 100644 index 0000000..07f5f18 --- /dev/null +++ b/docs_asp/api/loaders.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 2 +--- + +# Loaders +Unlike the old SWM API, **the new API does not manage the loaders for you**. You have to create and manage them yourself. +This allows you to have more control over the loaders and how they work. +You can either create your own loader by implementing the `SlimeLoader` interface or use the reference ones provided by us. +This page will focus on the latter option. + +## Obtaining the reference loaders +You need to shade the loaders into your plugin. You can do this by adding the following Maven or Gradle dependencies: + +### Maven +```xml + + + com.infernalsuite.aswm + loaders + 3.0.0 + + +``` + +### Gradle +```groovy +dependencies { + implementation 'com.infernalsuite.aswm:loaders:3.0.0' +} +``` + +Don't forget that the reference loaders are not included with the server; **you have to shade them into your plugin**. + +## Using the reference loaders + +I personally recommend instantiating the loader in your plugin's `onEnable` method and storing it in a field. +This way, you can access the loader from anywhere in your plugin. +For example: + +```java +public class MyPlugin extends JavaPlugin { + private SlimeLoader loader; + private final AdvancedSlimePaperAPI asp = AdvancedSlimePaperAPI.instance(); + + @Override + public void onEnable() { + loader = new FileLoader("slime_worlds"); + } + + public void doSomething() { + SlimeWorld world = asp.readWorld(loader, "world", false, new SlimePropertyMap()); + + // Do stuff with the world + } +} +``` \ No newline at end of file diff --git a/docs_asp/api/loading_worlds.md b/docs_asp/api/loading_worlds.md new file mode 100644 index 0000000..a96124c --- /dev/null +++ b/docs_asp/api/loading_worlds.md @@ -0,0 +1,46 @@ +--- +sidebar_position: 5 +--- +# Loading Worlds + +After we have obtained an instance of a `SlimeLoader` in the previous section, we can now use it to load worlds.\ +Unlike the old SWM API, this process is split into two stages: +- Reading the world from the loader (can be done asynchronously) +- Loading the world into the server (must be done synchronously) + +## Reading the World +Firstly we need to read the world from the `SlimeLoader` into memory and deserialize it.\ +This can be done by calling the `readWorld` method in the `AdvancedSlimePaperAPI` class.\ +**Remember: this is an I/O operation and should be done asynchronously.** + +```java +/* + * loader - the loader to read the world from + * "world" - the name of the world to read + * false - whether this world will be read-only + * new SlimePropertyMap() - the properties to apply to the world + */ +SlimeWorld world = asp.readWorld(loader, "world", false, new SlimePropertyMap()); +// Now we have a deserialized -in-memory- representation of the world +``` + +*What's the `SlimePropertyMap` for? Check out the [Properties](properties) page to learn more.* + +## Loading the World +After we have read the world from the loader, we can now load it into the server.\ +This can be done by calling the `loadWorld` method in the `AdvancedSlimePaperAPI` class.\ +**Remember: we are directly interacting with the server meaning this must be done synchronously.** + +```java +/* + * world - the deserialized world to load, obtained from the previous step + * true - whether to call the bukkit org.bukkit.event.world.WorldLoadEvent + */ +SlimeWorld mirror = asp.loadWorld(world, true); +// Now the world is loaded into the server and can be interacted with +``` + +*What's the `mirror`? It's a unique instance of the loaded world.* + +Fantastic! You have now successfully loaded a world into the server.\ +You can try to teleport to it, interact with it, or do whatever you want with it. \ No newline at end of file diff --git a/docs_asp/api/properties.md b/docs_asp/api/properties.md new file mode 100644 index 0000000..06f13fe --- /dev/null +++ b/docs_asp/api/properties.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 4 +--- + +# Properties +The properties are a way to customize the behavior of your world when loaded. +To use them, you need to create an instance of `SlimePropertyMap` and add the properties you want to apply to the world.\ +See the example below: + +```java +// create a new and empty property map +SlimePropertyMap properties = new SlimePropertyMap(); + +properties.setValue(SlimeProperties.DIFFICULTY, "normal"); +properties.setValue(SlimeProperties.SPAWN_X, 123); +properties.setValue(SlimeProperties.SPAWN_Y, 112); +properties.setValue(SlimeProperties.SPAWN_Z, 170); +properties.setValue(SlimeProperties.ALLOW_ANIMALS, false); +properties.setValue(SlimeProperties.ALLOW_MONSTERS, false); +properties.setValue(SlimeProperties.DRAGON_BATTLE, false); +properties.setValue(SlimeProperties.PVP, false); +properties.setValue(SlimeProperties.ENVIRONMENT, "normal"); +properties.setValue(SlimeProperties.WORLD_TYPE, "DEFAULT"); +properties.setValue(SlimeProperties.DEFAULT_BIOME, "minecraft:plains"); +// add as many as you would like +``` + +After you have created the property map, don't forget to pass it to the `readWorld` method when loading the world.\ +See the [Loading Worlds](loading_worlds) page for more information on how to read and load worlds. diff --git a/docs_asp/api/using.md b/docs_asp/api/using.md new file mode 100644 index 0000000..5514346 --- /dev/null +++ b/docs_asp/api/using.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +--- + +# Using the API +This page quickly explains how to obtain the API instance and start using it in your project. + +## Add the API artifact + +Firstly, you need to add the API artifact to your project. You can do this by adding the following Maven or Gradle dependencies: + +### Maven +```xml + + + + is-releases + https://repo.infernalsuite.com/repository/maven-releases/ + + + + + + + is-snapshots + https://repo.infernalsuite.com/repository/maven-snapshots/ + + +``` + +```xml + + + com.infernalsuite.aswm + api + 3.0.0 + provided + + +``` + +### Gradle +```groovy +repositories { + maven { url = 'https://repo.infernalsuite.com/repository/maven-snapshots/' } +} + +dependencies { + compileOnly 'com.infernalsuite.aswm:api:3.0.0' +} +``` + +**If you run into any Flow-NBT errors when building your project, add the additional repository: `https://repo.rapture.pw/repository/maven-releases/`** + +## Getting the API instance +Now that you've added the API artifact to your project, you can get the API instance by calling `AdvancedSlimePaperAPI.instance()`. + +```java +AdvancedSlimePaperAPI api = AdvancedSlimePaperAPI.instance(); + +// Do stuff +``` + +## Javadocs +You can find the Javadocs for the API [here](https://docs.infernalsuite.com/). +Most of the methods are documented, or the method names are self-explanatory. + +## Examples +See the other articles, or check the source code of the [SlimeWorldPlugin](https://github.com/InfernalSuite/AdvancedSlimePaper/tree/main/plugin) which uses the API. diff --git a/docs_asp/migrating.md b/docs_asp/migrating.md new file mode 100644 index 0000000..2a3583c --- /dev/null +++ b/docs_asp/migrating.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 99 +--- + +# Migrating from SWM +Since version 1.21.0, the plugin (formerly SlimeWorldManager) has been decoupled from the server (ASP) and is now known as the Slime World Plugin (SWP). + +This means, that now the plugin is no longer required to use the API, as it is provided by the server itself.\ +**If you want to keep the commands and features that the plugin provided, you can install the [Slime World Plugin](swp/installation) on your server.** + +## Migrating the API +The API has undergone rework and the main API class has been renamed from `SlimePlugin` to `AdvancedSlimePaperAPI`. + +### What does this mean for me? + +If you were using the SWM API before, you will probably have to change most of the parts of your code that interact with the API. +I suggest you **take a look at the [Using the API](api/using.md) page** to see how you can use the new API.\ +Pay close attention to the javadocs in the `AdvancedSlimePaperAPI` class, as it can help you to understand the differences between the old and the new API. + +**If you have any questions, feel free to ask in the [Discord](https://discord.infernalsuite.com/).** diff --git a/docs_asp/swp/index.md b/docs_asp/swp/index.md index 4143293..40f3c14 100644 --- a/docs_asp/swp/index.md +++ b/docs_asp/swp/index.md @@ -1 +1,7 @@ -# Slime World Plugin \ No newline at end of file +--- +sidebar_position: 91 +--- +# Slime World Plugin + +The Slime World Plugin (SWP) is a plugin that allows you to manage slime worlds in your server. \ +It is a reference implementation of a world management plugin utilizing the [ASP API](../api). \ No newline at end of file diff --git a/docs_asp/swp/installation.md b/docs_asp/swp/installation.md index 018d25a..bd2240c 100644 --- a/docs_asp/swp/installation.md +++ b/docs_asp/swp/installation.md @@ -3,6 +3,6 @@ sidebar_position: 1 --- # Installation -Simply download the latest version of the plugin and place it in your server's `plugins` folder. +Simply download the latest version of the plugin from our Discord and place it in your server's `plugins` folder. diff --git a/docusaurus.config.js b/docusaurus.config.js index 1fb05cc..8965e29 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -155,12 +155,17 @@ const config = { label: 'MC Market', href: 'https://www.mc-market.org/members/353325/#resources', }, + { + label: 'Javadocs', + href: 'https://docs.infernalsuite.com/', + } ], }, ], copyright: `Copyright © ${new Date().getFullYear()} Infernal Suite. Built with Docusaurus ♥.`, }, prism: { + additionalLanguages: ['java', 'groovy'], theme: prismThemes.github, darkTheme: prismThemes.dracula, },