MultiLib

MultiLib is a plugin library for interfacing with MultiPaper specific APIs (such as external player detection), with graceful fallbacks maintaining compatibility with both the Bukkit and Spigot API's.

API

All API calls can be found as static util methods in the MultiLib class.

Chunks

booleanisChunkExternal(Worldworld, intcx, intcz);
booleanisChunkExternal(Locationlocation);
booleanisChunkExternal(Entityentity);
booleanisChunkExternal(Blockblock);
booleanisChunkExternal(Chunkchunk);
booleanisChunkLocal(Worldworld, intcx, intcz);
booleanisChunkLocal(Locationlocation);
booleanisChunkLocal(Entityentity);
booleanisChunkLocal(Blockblock);
booleanisChunkLocal(Chunkchunk);

On MultiPaper, an external chunk is one being ticked on an external server, with this server simply containing a copy of the chunk. On Bukkit, all chunks are local.

Players

booleanisExternalPlayer(Playerplayer);
booleanisLocalPlayer(Playerplayer);
StringgetExternalServerName(Playerplayer);
StringgetLocalServerName();

On MultiPaper, an external player is a player connected to another server. Even if the player is an external player, it may still be in local chunks. The same can be said for local players, they can be in external chunks. On Bukkit, all players are local, and the server's local name will always be "bukkit".

@NullableStringgetExternalServerName(Playerplayer);

On MultiPaper, an external player will return the name of the server that the player is on. A local player has no external server, and will return null. On Bukkit, all players are local, and will always return null.

Collection<? extendsPlayer> getAllOnlinePlayers();
Collection<? extendsPlayer> getLocalOnlinePlayers();

On MultiPaper, all online players will return all players across all MultiPaper instances. Local online players will return the players on your single local MultiPaper instance. On Bukkit, both these methods return the same collection of players.

Sharing data

StringgetData(Playerplayer, Stringkey);
voidsetData(Playerplayer, Stringkey, Stringvalue);
StringgetPersistentData(Playerplayer, Stringkey);
voidsetPersistentData(Playerplayer, Stringkey, Stringvalue);

On MultiPaper, data stored with these methods will be available on all servers. Persistent data will be saved to the disk while non-persistent data will be lost when the player disconnects. On Bukkit, this data will only be available on the one server, and persistent data will be stored in a yaml file under multilib-data.

Notifying other servers

voidon(Pluginplugin, Stringchannel, Consumer<byte[]> callback);
voidonString(Pluginplugin, Stringchannel, Consumer<String> callback);
voidon(Pluginplugin, Stringchannel, BiConsumer<byte[], BiConsumer<String, byte[]>> callbackWithReply);
voidonString(Pluginplugin, Stringchannel, BiConsumer<String, BiConsumer<String, String>> callbackWithReply);
voidnotify(Stringchannel, byte[] data);
voidnotify(Stringchannel, Stringdata);
voidnotify(Chunkchunk, Stringchannel, byte[] data);
voidnotify(Chunkchunk, Stringchannel, Stringdata);

On MultiPaper, plugins running on other servers can be notified with a data payload. You can also notify only certain server with a specified chunk loaded. On Bukkit, these methods will do nothing as there are no other servers.

Running commands on other servers

voidchatOnOtherServers(Playerplayer, Stringmessage);

On MultiPaper, the specified player will say a chat message (or run a command) on all other servers. On Bukkit, this method will do nothing as there are no other servers.

Simple key-value data storage

MultiLib.getDataStorage();
CompletableFuture<String> get(Stringkey);
CompletableFuture<Map<String, String>> list(StringkeyPrefix);
CompletableFuture<String> set(Stringkey, Stringvalue);
CompletableFuture<Integer> add(Stringkey, intincrement);
CompletableFuture<Double> add(Stringkey, doubleincrement);
MultiLib.getDataStorage().createCache(Pluginplugin, StringkeyPrefix);

An async key-value data storage. This should not be used for large data as the backing database is in-memory and utilises an inefficient file storage format. Adding is an atomic operation. Any changes on one server will instantly be reflected across all other servers.

ShreddedPaper / Folia methods

RegionizedSchedulergetRegionScheduler();
EntitySchedulergetEntityScheduler(Entityentity);
booleanisOwnedByCurrentRegion(Locationlocation);
booleanisOwnedByCurrentRegion(Entityentity);
CompletableFuture<Chunk> getChunkAtAsync(Locationlocation);
CompletableFuture<Boolean> teleportAsync(Entityentity, Locationlocation, PlayerTeleportEvent.TeleportCausecause);

Example Plugin

importcom.github.puregero.multilib.MultiLib;
publicclassMyPluginextendsJavaPlugin {
publicvoidonEnable() {
MultiLib.onString(this, "myplugin:testchannel", (data, reply) -> {
getLogger().info("Received " + data);
reply.accept("myplugin:testchannelreply", "Replying to " + data);
});
MultiLib.onString(this, "myplugin:testchannelreply", data -> {
getLogger().info("Received the reply " + data);
});
MultiLib.notify("myplugin:testchannel", "Hello!");
}
publicvoiddoSomething(Playerplayer) {
if (MultiLib.isExternalPlayer(player)) {
getLogger().info("Not our player! Let's not actually do this!");
} else {
actuallyDoTheSomething(player);
}
}
}

Build Script Setup

Add the Clojars repository and the MultiLib dependency, then shade and relocate it to your own package. Relocation helps avoid version conflicts with other plugins using MultiLib.

Gradle

Repo:

repositories {
maven {
url "https://repo.clojars.org/"
}
}

Dependency:

dependencies {
implementation "com.github.puregero:multilib:1.2.5"
}

Shadow Jar and Relocate (Groovy Syntax):

plugins {
id "com.gradleup.shadow" version "8.3.5"// Make sure to always use the latest version (https://plugins.gradle.org/plugin/com.gradleup.shadow)
}
shadowJar {
relocate "com.github.puregero.multilib", "[YOUR PLUGIN PACKAGE].multilib"
}

Maven

Repo:

<repositories>
<repository>
<id>clojars</id>
<url>https://repo.clojars.org</url>
</repository>
</repositories>

Dependency:

<dependencies>
<dependency>
<groupId>com.github.puregero</groupId>
<artifactId>multilib</artifactId>
<version>1.2.5</version>
<scope>compile</scope>
</dependency>
</dependencies>

Shade & Relocate:

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.0</version> <!-- Make sure to always use the latest version (https://maven.apache.org/plugins/maven-shade-plugin/) -->
<configuration>
<dependencyReducedPomLocation>${project.build.directory}/dependency-reduced-pom.xml</dependencyReducedPomLocation>
<relocations>
<relocation>
<pattern>com.github.puregero.multilib</pattern>
<shadedPattern>[YOUR PLUGIN PACKAGE].multilib</shadedPattern> <!-- Replace this -->
</relocation>
</relocations>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

Compiling

MultiPaper is compiled using maven:

mvn

License

MultiLib is licensed under the MIT license

PaperLib

MultiLib is inspired by PaperMC's PaperLib