203 lines
8.1 KiB
Java
203 lines
8.1 KiB
Java
package io.papermc.paper.datapack;
|
|
|
|
import io.papermc.paper.plugin.configuration.PluginMeta;
|
|
import io.papermc.paper.plugin.lifecycle.event.registrar.Registrar;
|
|
import java.io.IOException;
|
|
import java.net.URI;
|
|
import java.nio.file.Path;
|
|
import java.util.Map;
|
|
import java.util.function.Consumer;
|
|
import net.kyori.adventure.text.Component;
|
|
import org.jetbrains.annotations.ApiStatus;
|
|
import org.jetbrains.annotations.Contract;
|
|
import org.jetbrains.annotations.Unmodifiable;
|
|
import org.jspecify.annotations.NullMarked;
|
|
import org.jspecify.annotations.Nullable;
|
|
|
|
/**
|
|
* The registrar for datapacks. The event for this registrar
|
|
* is called anytime the game tries to discover datapacks at any of the
|
|
* configured locations. This means that if a datapack should stay available to the server,
|
|
* it must always be discovered whenever this event fires.
|
|
* <p>An example of a plugin loading a datapack from within it's own jar is below</p>
|
|
* <pre>{@code
|
|
* public class YourPluginBootstrap implements PluginBootstrap {
|
|
* @Override
|
|
* public void bootstrap(BoostrapContext context) {
|
|
* final LifecycleEventManager<BootstrapContext> manager = context.getLifecycleManager();
|
|
* manager.registerEventHandler(LifecycleEvents.DATAPACK_DISCOVERY, event -> {
|
|
* DatapackRegistrar registrar = event.registrar();
|
|
* try {
|
|
* final URI uri = Objects.requireNonNull(
|
|
* YourPluginBootstrap.class.getResource("/pack")
|
|
* ).toURI();
|
|
* registrar.discoverPack(uri, "packId");
|
|
* } catch (final URISyntaxException | IOException e) {
|
|
* throw new RuntimeException(e);
|
|
* }
|
|
* });
|
|
* }
|
|
* }
|
|
* }</pre>
|
|
* @see io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents#DATAPACK_DISCOVERY
|
|
*/
|
|
@ApiStatus.NonExtendable
|
|
@ApiStatus.Experimental
|
|
@NullMarked
|
|
public interface DatapackRegistrar extends Registrar {
|
|
|
|
/**
|
|
* Checks if a datapack with the specified name has been discovered.
|
|
*
|
|
* @param name the name of the pack
|
|
* @return true if the pack has been discovered
|
|
* @see Datapack#getName()
|
|
*/
|
|
@Contract(pure = true)
|
|
boolean hasPackDiscovered(String name);
|
|
|
|
/**
|
|
* Gets a discovered datapack by its name.
|
|
*
|
|
* @param name the name of the pack
|
|
* @return the datapack
|
|
* @throws java.util.NoSuchElementException if the pack is not discovered
|
|
* @see Datapack#getName()
|
|
*/
|
|
@Contract(pure = true)
|
|
DiscoveredDatapack getDiscoveredPack(String name);
|
|
|
|
/**
|
|
* Removes a discovered datapack by its name.
|
|
*
|
|
* @param name the name of the pack
|
|
* @return true if the pack was removed
|
|
* @see Datapack#getName()
|
|
*/
|
|
@Contract(mutates = "this")
|
|
boolean removeDiscoveredPack(String name);
|
|
|
|
/**
|
|
* Gets all discovered datapacks.
|
|
*
|
|
* @return an unmodifiable map of discovered packs
|
|
*/
|
|
@Contract(pure = true)
|
|
@Unmodifiable Map<String, DiscoveredDatapack> getDiscoveredPacks();
|
|
|
|
/**
|
|
* Discovers a datapack at the specified {@link URI} with the id.
|
|
* <p>Symlinks obey the {@code allowed_symlinks.txt} in the server root directory.</p>
|
|
*
|
|
* @param uri the location of the pack
|
|
* @param id a unique id (will be combined with plugin for the datapacks name)
|
|
* @return the discovered datapack (or null if it failed)
|
|
* @throws IOException if any IO error occurs
|
|
*/
|
|
default @Nullable DiscoveredDatapack discoverPack(final URI uri, final String id) throws IOException {
|
|
return this.discoverPack(uri, id, c -> {});
|
|
}
|
|
|
|
/**
|
|
* Discovers a datapack at the specified {@link URI} with the id.
|
|
* <p>Symlinks obey the {@code allowed_symlinks.txt} in the server root directory.</p>
|
|
*
|
|
* @param uri the location of the pack
|
|
* @param id a unique id (will be combined with plugin for the datapacks name)
|
|
* @param configurer a configurer for extra options
|
|
* @return the discovered datapack (or null if it failed)
|
|
* @throws IOException if any IO error occurs
|
|
*/
|
|
@Nullable DiscoveredDatapack discoverPack(URI uri, String id, Consumer<Configurer> configurer) throws IOException;
|
|
|
|
/**
|
|
* Discovers a datapack at the specified {@link Path} with the id.
|
|
* <p>Symlinks obey the {@code allowed_symlinks.txt} in the server root directory.</p>
|
|
*
|
|
* @param path the location of the pack
|
|
* @param id a unique id (will be combined with plugin for the datapacks name)
|
|
* @return the discovered datapack (or null if it failed)
|
|
* @throws IOException if any IO error occurs
|
|
*/
|
|
default @Nullable DiscoveredDatapack discoverPack(final Path path, final String id) throws IOException {
|
|
return this.discoverPack(path, id, c -> {});
|
|
}
|
|
|
|
/**
|
|
* Discovers a datapack at the specified {@link Path} with the id.
|
|
* <p>Symlinks obey the {@code allowed_symlinks.txt} in the server root directory.</p>
|
|
*
|
|
* @param path the location of the pack
|
|
* @param id a unique id (will be combined with plugin for the datapacks name)
|
|
* @param configurer a configurer for extra options
|
|
* @return the discovered datapack (or null if it failed)
|
|
* @throws IOException if any IO error occurs
|
|
*/
|
|
@Nullable DiscoveredDatapack discoverPack(Path path, String id, Consumer<Configurer> configurer) throws IOException;
|
|
|
|
/**
|
|
* Discovers a datapack at the specified {@link URI} with the id.
|
|
* <p>Symlinks obey the {@code allowed_symlinks.txt} in the server root directory.</p>
|
|
*
|
|
* @param pluginMeta the plugin which will be the "owner" of this datapack
|
|
* @param uri the location of the pack
|
|
* @param id a unique id (will be combined with plugin for the datapacks name)
|
|
* @param configurer a configurer for extra options
|
|
* @return the discovered datapack (or null if it failed)
|
|
* @throws IOException if any IO error occurs
|
|
*/
|
|
@Nullable DiscoveredDatapack discoverPack(PluginMeta pluginMeta, URI uri, String id, Consumer<Configurer> configurer) throws IOException;
|
|
|
|
/**
|
|
* Discovers a datapack at the specified {@link Path} with the id.
|
|
* <p>Symlinks obey the {@code allowed_symlinks.txt} in the server root directory.</p>
|
|
*
|
|
* @param pluginMeta the plugin which will be the "owner" of this datapack
|
|
* @param path the location of the pack
|
|
* @param id a unique id (will be combined with plugin for the datapacks name)
|
|
* @param configurer a configurer for extra options
|
|
* @return the discovered datapack (or null if it failed)
|
|
* @throws IOException if any IO error occurs
|
|
*/
|
|
@Nullable DiscoveredDatapack discoverPack(PluginMeta pluginMeta, Path path, String id, Consumer<Configurer> configurer) throws IOException;
|
|
|
|
/**
|
|
* Configures additional, optional, details about a datapack.
|
|
*/
|
|
@ApiStatus.NonExtendable
|
|
@ApiStatus.Experimental
|
|
interface Configurer {
|
|
|
|
/**
|
|
* Changes the title of the datapack from the default which
|
|
* is just the "id" in the {@code registerPack} methods.
|
|
*
|
|
* @param title the new title
|
|
* @return the configurer for chaining
|
|
*/
|
|
@Contract(value = "_ -> this", mutates = "this")
|
|
Configurer title(Component title);
|
|
|
|
/**
|
|
* Sets whether this pack is going to be automatically enabled on server starts even if previously disabled.
|
|
* Defaults to false.
|
|
*
|
|
* @param autoEnableOnServerStart true to ensure the pack is enabled on server starts.
|
|
* @return the configurer for chaining
|
|
*/
|
|
@Contract(value = "_ -> this", mutates = "this")
|
|
Configurer autoEnableOnServerStart(boolean autoEnableOnServerStart);
|
|
|
|
/**
|
|
* Configures the position in the
|
|
* load order of this datapack.
|
|
*
|
|
* @param fixed won't move around in the load order as packs are added/removed
|
|
* @param position try to insert at the top of the order or bottom
|
|
* @return the configurer for chaining
|
|
*/
|
|
@Contract(value = "_, _ -> this", mutates = "this")
|
|
Configurer position(boolean fixed, Datapack.Position position);
|
|
}
|
|
}
|