Oh, welcome! So you decided to enter the wonderful journey of working with the Marcely's Bedwars API?
Don't worry, it'll be as easy as working with Bukkit's/Spigot's API as it was built up to be easily understood, yet flexible and descriptive at the same time.
To get started, simply import the API as you're used to:
¶ Importing the MBedwars API
¶ Maven
Insert these snippets into your pom.xml:
<repositories>
<repository>
<id>marcely-repo</id>
<url>https://repo.marcely.de/repository/maven-public/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>de.marcely.bedwars</groupId>
<artifactId>API</artifactId>
<version>5.4.13</version>
<scope>provided</scope>
</dependency>
</dependencies>
¶ Gradle
repositories {
maven {
url = 'https://repo.marcely.de/repository/maven-public/'
}
}
dependencies {
compileOnly 'de.marcely.bedwars:API:5.4.13'
}
¶ As an External Jar
How-Tos:
Using Intellij
Using EclipseYou can find all existing jars right here.
Simply select the version of your choice and download the files you need, most likely de/marcely/bedwars/API/{version}/API-{version}.jar.
¶ First Steps
Creating an add-on for MBedwars is not as difficult as you might think! It is just as easy as creating a normal spigot plugin.
¶ 1. Adding MBedwars as a dependency
It is important to make sure that you add MBedwars as a dependancy in you Addons.
This will insure that your plugin will get loaded after MBedwars, as otherwise you'll face into errors when accessing the API.
Simply add the MBedwars depend in your plugin.yml. Thats it!
Example:
name: MyFirstMBedwarsAddon
version: 1.0
main: com.me.myfirstmbedwarsaddon.AddonPlugin
depend: [MBedwars]
¶ 2. Ensuring that the user is using the supported MBedwars version
Handling different public versions of a software with a evolving API can be annoying to handle for a developer.
That's why you might want to add the following snippet to your onEnable method of your plugin. This will ensure that the user who is using your plugin is using the correctly supported MBedwars plugin.
final int supportedAPIVersion = 112; // find the correct number in the tab "Table of API Versions"
final String supportedVersionName = "5.4.13"; // update this accordingly to the number, otherwise the error will be wrong
try {
Class apiClass = Class.forName("de.marcely.bedwars.api.BedwarsAPI");
int apiVersion = (int) apiClass.getMethod("getAPIVersion").invoke(null);
if (apiVersion < supportedAPIVersion)
throw new IllegalStateException();
} catch(Exception e) {
getLogger().warning("Sorry, your installed version of MBedwars is not supported. Please install at least v" + supportedVersionName);
Bukkit.getPluginManager().disablePlugin(this);
return;
}
- 5.4.13: 112
- 5.4.12: 111
- 5.4.11: 110
- 5.4.9: 109
- 5.4.8: 108
- 5.4.7: 107
- 5.4.6.1: 106
- 5.4.6: 105
- 5.4.5: 104
- 5.4.4: 103
- 5.4.3.2.1: 102
- 5.4.2: 101
- 5.4: 100
- 5.3.3: 25
- 5.3 - 5.3.2: 24
- 5.2.7: 23
- 5.2.6: 22
- 5.2.5: 21
- 5.2.4: 20
- 5.2.3: 19
- 5.2.2: 18
- 5.2 & 5.2.1: 17
- 5.1.1: 16
- 5.1: 15
- 5.0.14: 14
- 5.0.13: 13
- 5.0.12: 12
- 5.0.10 & 5.0.11: 11
- 5.0.9: 10
- 5.0.8: 9
- 5.0.7: 8
- 5.0.6: 7
- 5.0.5: 6
- 5.0.4: 5
- 5.0.3: 4
- 5.0.2: 3
- 5.0.1: 2
- 5.0: 1
- Legacy Betas before v5: 0
¶ 3. Waiting until MBedwars has loaded
The following part is optional, but it's recommended that you at least read through it and understand what it does as it can possibly save quite a few hours of you trying solve a non-existing bug.
Arenas etc. get loaded async, hence you might not be able to access them during your onEnable sequence, even if you might expect that.
There's a neat feature which allows you to simply start right away when the plugin is ready.
Simply wrap your code with which you're accessing MBedwars stuff the following way (Snippet only works in Java 8+):
BedwarsAPI.onReady(() -> {
Bukkit.broadcast(GameAPI.getArenas().size() + " arenas have been loaded during the start");
// more code...
});
BedwarsAPI.onReady promises to run your passed callback, but there's no exact time when that happens. It might immediately happen directly after you're executing it, it might also happen a few seconds after. The callback is always getting called on the main thread.
¶ 4. Game time
That's basically it. You're now free to do whatever you want with the API. But there are some things you should keep in mind when working with it:
The API is generally not thread safe, but it won't prevent you from trying invoking methods while not being on the main thread in the most parts. Keep the risk in mind when doing that and make sure to test it properly before bringing it into production.
You might want to read the javadocs as there are async events and some callbacks that get called async, but these cases always get described in the javadocs.
It is not perfect, but it tries its' best to help you as far as possible.
This includes auto-removing registerable components (like listeners, special items, etc.) when your plugin unloads and notifying you when it detectes that you're doing something wrong.
If you think that you've found a bug then don't be afraid to talk with us about it: Contact Us
Your first place of your lookup should be the BedwarsAPI class, as it roots to almost every accessible component of the API.
Here are some further pages that you likely will find useful when working with it: