webadmin/ultimatedocs
1
0
Fork 0
Code
master
ultimatedocs/docs/API.md

531 lines
21 KiB
Markdown
Raw Permalink Normal View History

update
2024-04-18 11:30:21 +02:00
---
lastUpdated: true
aside: true
sidebar: true
sidebarDepth: 3
title: API Informatie
description: API informatie over de ultimate kingdom plugin
meta_keywords: 'kingdom plugin, ultimate, minecraft plugin, spigot plugin, gameplay, API'
meta_url: 'https://ultimatekingdom.nl'
---
# API
[[toc]]
## Gradle
### repositories
```ts
repositories {
maven { url "https://repo.recorehosting.com/repository/maven-snapshots/" } // snapshots
maven { url "https://repo.recorehosting.com/repository/development/" } // beta & release candidate
```
### dependencies
#### Kingdom plugin
```ts
compileOnly 'me.map:ultimatekingdom:1.45.4.1-SNAPSHOT' //development voor deze versie is gestopt
compileOnly 'me.map:ultimatekingdom:2.12.0.0-RC1'
```
#### Exchange
```ts
compileOnly 'me.map.exchange:API:2.12.0.0-RC1'
compileOnly 'me.map.exchange:bungeecord:2.12.0.0-RC1'
compileOnly 'me.map.exchange:velocity:2.12.0.0-RC1'
```
## Toegang tot API
De plugin is via een `static class` bereikbaar.
```ts
UltimateKingdom. .....
UltimateKingdom.Kingdoms() .....
UltimateKingdom.getKingdomServer()
```
#### voorbeeld 1
```ts
public class myClass {
public void doSomething() {
Kingdom k1 = UltimateKingdom.Kingdoms().getKingdom("kingdomname"); //haal een kingdom op
Kingdom k = Kingdom.get("anotherkingdomname"); // mag ook
k1.setSlogan("&athis &fwill &cbe &6the &8new &aslogan" ,(result,kingdom) -> {
if (result.isOk()) { //result is ok...
Bukkit.getLogger().info("Changed kingdom slogan to " + kingdom.getSlogan());
} else {
Bukkit.getLogger().severe("Something has happend" + result.toString());
}
});
}
}
```
#### voorbeeld 2 KingdomPlayer
```ts
public void doSomething() {
UUID uuid = UUID.randomUUID(); //voorbeeld
KingdomPlayer playerOne = UltimateKingdom.Players().getPlayer(uuid);
KingdomPlayer playerTwo = KingdomPlayer.get(uuid); //tomayto, tomahto tomato
playerOne.setmod(false,(result,player) -> {
if (result.isOk()) {
Bukkit.getLogger().info("player:" + player.getName() + " mod " + player.isMod()); //
} else {
Bukkit.getLogger().severe(result.toString());
}
});
}
```
#### voorbeeld 3 uitzondering
Uitzondering op setRank
```ts
public void doSomething() {
UUID uuid = UUID.randomUUID(); //voorbeeld
KingdomPlayer playerOne = UltimateKingdom.Players().getPlayer(uuid);
KingdomPlayer playerTwo = KingdomPlayer.get(uuid); //tomayto, tomahto tomato
Rank rank = Rank.get("Koning");
playerOne.setRank(rank,(result,player,kingdom) -> { //[!code hl] //setrank geeft 3 objecten terug (result,player,kingdom)
if (result.isOk()) {
Bukkit.getLogger().info("player new rank :" + player.getRank().getName() + " kingdom " + kingdom.getName()); //
} else {
Bukkit.getLogger().severe(result.toString());
}
});
}
```
## Gebruikte bibliotheken
De kingdom plugin gebruikt de onderstaande bibliotheken
* [Kyori Adventure](https://github.com/KyoriPowered/adventure)
* [WorldGuardWrapper](https://github.com/CodeMC/WorldGuardWrapper)
* [xseries](https://github.com/CryptoMorin/XSeries)
* [Okaeri Placeholders](https://github.com/OkaeriPoland/okaeri-placeholders)
* [okaeri-tasker](https://github.com/OkaeriPoland/okaeri-tasker) [^1]
* [Scoreboard-library](https://github.com/MegavexNetwork/scoreboard-library)
* [Universal Scheduler ](https://github.com/DreamVoid/UniversalScheduler)
* [Simple-Yaml ](https://github.com/Carleslc/Simple-YAML)
[^1]: Er zit een aangepaste variant in de plugin, voor ondersteuning van de Universal scheduler. (UniversalTasker)
### Hooks
De onderstaande hooks/bibliotheren zijn beschikbaar.
| bibliotheken/hooks | via |
| --------------------------- | ------------------------------------------------------------------- |
| Scoreboard-library | UltimateKingdom.getKingdomServer().ScoreboardLibrary() |
| Kyori Adventure | UltimateKingdom.getKingdomServer().Adventurehook() |
| Okaeri Placeholders | UltimateKingdom.getKingdomServer().Messages().getPlaceHolders() |
| EssentialX | UltimateKingdom.getKingdomServer().EssentialsHook() |
| Universal Scheduler | UltimateKingdom.getKingdomServer().UniversalScheduler() |
| Okaeri-tasker | UltimateKingdom.getKingdomServer().Tasker() |
| Teleport queue | UltimateKingdom.getKingdomServer().QueuedTeleports() |
| Runnable queue | UltimateKingdom.getKingdomServer().QueuedRunnables() |
## Commands
We gebruiken een aangepaste brigadier van mojang.
Hieronder staat een voorbeeld van een commando die de display naam van de kingdom aanpast.
```ts
public class MyCommand extends AbstractCommand {
public list() {
super("mycommand");
setDescription("Geef hier een omschrijving"); //deze omschrijving is zichtbaar in /k help
setLongDescription("Geef hier eventueel een lange omschriving, deze is zichtbaar in /k help mycommand"); // (optioneel)
setAliases("l"); //geef hier een alias in voor het commando. (optioneel)
setPlayerOnly(true); //optioneel
setPermission("kingdom.mycommand"); //permissie
}
public void createCommand(KingdomCommand brigadierCommand) {
brigadierCommand
.then(literal("setdisplayname") //commando is dus: /k mycommand setdisplayname <kingdom naam> <string>
.requires(c -> c.hasKingdom() && c.isMod() && c.isPlayer() )
.then(argument("kingdom", KingdomArgumentType.kingdom()) //Kingdom argument
.then(argument("displayname", StringArgumentType.greedyString()) //String argument
.suggests(new StringSuggestion("geef naam op")) // "geef naam op" weergeven als suggestie bij de argument displayname
.executes(c -> {
String displayname = c.getArgument("displayname", String.class); //haal String argument op
Kingdom kingdom = c.getArgument("kingdom", Kingdom.class); //haal Kingdom argument op
kingdom.setDisplayName(displayname, (res,rm) -> {
if (res.isOk()) {
c.getSource().sendMessage("we hebben het aangepast");
} else {
c.getSource().sendMessage("Big Error... " + res);
}
});
return Command.SINGLE_SUCCESS;
}))));
}
```
### Registreren command
```ts
new MyCommand().register();
```
### ArgumentTypes
De onderstaande argumentypes zijn beschikbaar in de plugin.
| type | omschrijving |
| --------------------------- | --------------------------------------------------------------------- |
| KingdomArgumentType | argument voor kingdoms (Kingdom) |
| KingdomPlayerArgumentType | argument voor online spelers (KingdomPlayer) |
| ServerSpawnArgumentType | argument voor server spawns (KingdomLocation) |
| ServerSpawnArgumentType | argument voor rank groep (String) |
| PlayerLevelArgumentType | argument voor player levels (KingdomLevel) |
| KingdomLevelArgumentType | argument voor kingdom levels (PlayerLevel) |
| ChatChannelArgumentType | argument voor channels (Channels) |
| CommandsArgumentType | argument voor commands (AbstractCommand) |
| PlayerArgumentType | argument voor online spelers (lokaal Players) |
| MultiServerCachedPlayerType | argument voor online spelers (CachedPlayers) |
| RankArgumentTypeType | argument voor Rank (Rank) [zie voorbeeld 3](API#voorbeeld-3) |
| YesNoArgumentsType | argument voor Yes/No (Boolean) |
| BooleanWithWordsType | argument voor True/False (Boolean) |
| ColorArgumentType | argument voor Colors (voorbeeld :0 0 0 255) |
| HexArgumentType | argument voor Hex ( voorbeeld :404040) |
| UuidMemberArgumentType | argument voor Kingdom members. Geeft UUID van speler |
#### voorbeeld 1
```ts
public class MyCommand extends AbstractCommand {
public MyCommand() {
super("MyCommand");
setDescription("this command does nothing");
setLongDescription("This is just a demo. So don't get angry.. please...");
setPermission("demo.set");
setPlayerOnly(false);
}
@Override
public void createCommand(KingdomCommand command) {
command
.then(argument("kingdom", KingdomArgumentType.kingdom()) // [!code hl] //eerste argument van commando
.executes(c -> {
Kingdom kingdom = c.getArgument("kingdom", Kingdom.class); //[!code hl] //ophalen argument
... //do something
return Command.SINGLE_SUCCESS;
}));
}
}
```
#### voorbeeld 2
```ts
public class MyCommand extends AbstractCommand {
public MyCommand() {
super("MyCommand");
setDescription("this command does nothing");
setLongDescription("This is just a demo. So don't get angry.. please...");
setPermission("demo.set");
setPlayerOnly(false);
}
@Override
public void createCommand(KingdomCommand command) {
command
.then(argument("action", OptionCollectionArgumentType.get(Arrays.asList("enable", "disable", "status"))) // [!code hl]
.executes(c -> {
String action = c.getArgument("action", String.class); // [!code hl]
switch (action.toLowerCase()) { // [!code hl]
case "on": // [!code hl]
break; // [!code hl]
case "disable": // [!code hl]
break; // [!code hl]
case "status": // [!code hl]
break;// [!code hl]
}
return Command.SINGLE_SUCCESS;
}));
}
}
```
#### voorbeeld 3
De argument RankArgumentTypeType geeft standaard de ranken uit de groep `default`
Met 'suggests' kan een andere lijst worden gegeven.
In het onderstaande voorbeeld wordt de ranken opgehaald van de kingdom , waar de speler die het commando uitvoert, lid van is.
De speler moet een echte `speler` zijn en moet lid zijn van een kingdom om het commando te kunnen zien.
```ts
public class MyCommand extends AbstractCommand {
public MyCommand() {
super("MyCommand");
setDescription("this command does nothing");
setLongDescription("This is just a demo. So don't get angry.. please...");
setPermission("demo.set");
setPlayerOnly(false); // [!code hl] //controle van player-only doen we in het commando zelf.
}
//dit regelt de nieuwe suggestie van ranks // [!code hl]
private CompletableFuture<Suggestions> PlayerKingdomRank(CommandContext<CommandSource> suggestionsBuilder, SuggestionsBuilder builder) { // [!code hl]
KingdomPlayer player = suggestionsBuilder.getSource().asKingdomPlayerOrNull(); // [!code hl]
for (Rank rank : player.getKingdom().getRanksList()) { // [!code hl]
builder.suggest(rank.getName()); // [!code hl]
} // [!code hl]
return builder.buildFuture(); // [!code hl]
} // [!code hl]
@Override
public void createCommand(KingdomCommand command) {
command
.then(argument("rank", RankArgumentTypeType.get()) // [!code hl]
.requires(c -> c.isPlayer() && c.hasKingdom()) // [!code hl] //player-only && speler heeft kingdom
.suggests(this::PlayerKingdomRank) // [!code hl] //verwijst naar de nieuwe suggestie
.executes(c -> {
Rank rank = c.getArgument("rank",Rank.class);
... do something
return Command.SINGLE_SUCCESS;
}));
}
}
```
## Gegevens opslaan
In de plugin kan je gegevens opslaan die je op een andere server weer kan gebruiken.
Je hebt 3 plekken waar je data kan bewaren.
* spelers data
* kingdom data
* server data
De data kan je bewaren dmv MetaData
Voorbeeld kingdom data
```ts
Kingdom kingdom = Kingdom.get("MyKingdom");
MetaData md = new IntegerDataField("myplugin_key");//zorg dat je plugin naam er in zit ivm andere plugins
md.setValue(10);
kingdom.addMeta(md, (result, kd)-> {
//do something
});
```
Voorbeeld server data
```ts
Kingdom kingdom = Kingdom.get("MyKingdom");
MetaData md = new IntegerDataField("myplugin_key"); //zorg dat je plugin naam er in zit ivm andere plugins
md.setValue(10);
UltimateKingdom.Settings().addMeta(md, (result, kd)-> {
//do something
});
```
### Metadata objecten
Alleen serializable objects
| type |
| --------------------------- |
| BooleanDataField |
| DecimalDataField |
| IntegerDataField |
| LongDataField |
| ListDataFiend |
| HashMapStringBooleanField |
| HashMapStringIntegerField |
## Placeholders
### Kingdom/player object
De kingdom plugin gebruikt de onderstaande metadata labels.
| label | Type | object | omschrijving |
| ------------------------------ |:----------------: | :--------------:|------------------------------------------------ |
| strokeColor | String | kingdom | in gebruik bij setdynmap |
| strokeopacity | Double | kingdom | in gebruik bij setdynmap |
| strokeweight | Integer | kingdom | in gebruik bij setdynmap |
| fillcolor | String | kingdom | in gebruik bij setdynmap |
| fillopacity | Double | kingdom | in gebruik bij setdynmap |
| spawnicon | String | kingdom | in gebruik bij setdynmap |
| warpicon | String | kingdom | in gebruik bij setdynmap |
### Settings
De kingdom plugin gebruikt de onderstaande metadata settings labels.
| label | Type | omschrijving |
| ------------------------ | ------------- |------------------------------------------------ |
| ultimate_leavelocation | String | KingdomLocatie als String |
| ultimate_kicklocation | String | KingdomLocatie als String |
## Events
onderstaande is nog niet compleet.
### WorldGuard Events
| type | omschrijving |
| --------------------------- | --------------------------------------------------------------------- |
| RegionEnteredEvent | als een speler een regio binnen gaat |
| RegionLeftEvent | als een speler een regio verlaat |
| RegionsChangedEvent | als een speler van regio veranderd |
| RegionsLeftEvent | als een speler een regio verlaat. |
### GamePlay events
Alle gamePlay events waar je iets meer kan doen.
#### Action events
| type | omschrijving |
| --------------------------- | --------------------------------------------------------------------- |
| KingdomSwitchEvent | als een speler iets omzet zoals een schakelaar |
| KingdomItemuseEvent | als een speler een item gebruikt |
| KingdomDestroyEvent | als een speler iets kapot maakt |
| KingdomBuildEvent | als een speler iets bouwt |
| KingdomActionEvent | alles hierboven |
#### Damage events
| type | omschrijving |
| -------------------------------| --------------------------------------------------------------------- |
| KingdomPlayerDamagePlayerEvent | Speler tegen speler damage |
| KingdomDamageEvent | alles hier boven |
### Chat events
| type | omschrijving |
| ------------------------------- | --------------------------------------------------------------------- |
| AsyncNonReportableChatEvent | waneer een admin chat (nochatreport in config.yml moet aan staan) |
| AsyncPostNonReportableChatEvent | waneer een admin chat (nochatreport in config.yml moet aan staan) |
| KingdomChatEvent | wanneer eens speler chat
### Kingdom events
| type | omschrijving |
| ------------------------------- | -------------------------------------- |
| KingdomSetEvent | Speler in kingdom zetten |
| KingdomCreateEvent | kingdom aanmaken |
| KingdomDeleteEvent | kingdom verwijderen |
| KingdomRenameEvent | kingdom hernoemen |
| KingdomAddPointsEvent | toevoegen punten |
| KingdomAddSpawnEvent | toevoegen spawn |
| KingdomDeleteSpawnEvent | verwijderen spawn |
| KingdomAddWarpEvent | toevoegen warp |
| KingdomDeleteWarpEvent | verwijderen warp |
| KingdomMaxMembersEvent | instellen max. aantal leden |
| KingdomRemoveLevelEvent | verwijderen van level |
| KingdomRemoveMember | verwijderen van kingdom lid |
| KingdomRemovePointsEvent | verwijderen van punten |
| KingdomRemoveRankMaximumEvent | verwijderen van een rank max. |
| KingdomSetFriendlyFireEvent | instellen friendly-fire |
| KingdomSetInviteOnly | instellen invite-only |
| KingdomSetLevelEvent | instellen kingdom level |
| KingdomSetPlaceHolderEvent | instellen placeholder |
| KingdomSetRankMaximumEvent | instellen max rank |
| KingdomSetRelationEvent | instellen relatie |
| KingdomSetSpawnEvent | instellen spawn |
| KingdomSetWarpEvent | instellen warp |
| KingdomPlayerSetRank | instellen rank |
### Player events
| type |
| ------------------------------------ |
| PlayerJoinKingdomEvent |
| PlayerJoinServerEvent |
| PlayerDeathMessageEvent |
| PlayerKilledPlayerDeathMessageEvent |
| PlayerDeathMessageEvent |
### WorldGuardWrapper Events
| type |
| --------------------------- |
| WrappedUseEntityEvent |
| WrappedDisallowedPVPEvent |
| WrappedDamageEntityEvent |
| AbstractWrappedEvent |
Copy Permalink