Plugins should use {@link org.bukkit.plugin.Plugin#getDataFolder()} rather than traversing this * directory manually when determining the location in which to store their data and configuration files.
* * @return plugins directory */ @NotNull File getPluginsFolder(); /** * Used for all administrative messages, such as an operator using a * command. ** For use in {@link #broadcast(net.kyori.adventure.text.Component, java.lang.String)}. */ public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin"; /** * Used for all announcement messages, such as informing users that a * player has joined. *
* For use in {@link #broadcast(net.kyori.adventure.text.Component, java.lang.String)}. */ public static final String BROADCAST_CHANNEL_USERS = "bukkit.broadcast.user"; /** * Gets the name of this server implementation. * * @return name of this server implementation */ @NotNull public String getName(); /** * Gets the version string of this server implementation. * * @return version of this server implementation */ @NotNull public String getVersion(); /** * Gets the Bukkit version that this server is running. * * @return version of Bukkit */ @NotNull public String getBukkitVersion(); // Paper start - expose game version /** * Gets the version of game this server implements * * @return version of game */ @NotNull String getMinecraftVersion(); // Paper end /** * Gets a view of all currently logged in players. This {@linkplain * Collections#unmodifiableCollection(Collection) view} is a reused * object, making some operations like {@link Collection#size()} * zero-allocation. *
* The collection is a view backed by the internal representation, such * that, changes to the internal state of the server will be reflected * immediately. However, the reuse of the returned collection (identity) * is not strictly guaranteed for future or all implementations. Casting * the collection, or relying on interface implementations (like {@link * Serializable} or {@link List}), is deprecated. *
* Iteration behavior is undefined outside of self-contained main-thread * uses. Normal and immediate iterator use without consequences that * affect the collection are fully supported. The effects following * (non-exhaustive) {@link Entity#teleport(Location) teleportation}, * {@link Player#setHealth(double) death}, and {@link Player#kickPlayer( * String) kicking} are undefined. Any use of this collection from * asynchronous threads is unsafe. *
* For safe consequential iteration or mimicking the old array behavior,
* using {@link Collection#toArray(Object[])} is recommended. For making
* snapshots, {@link ImmutableList#copyOf(Collection)} is recommended.
*
* @return a view of currently online players.
*/
@NotNull
public Collection getOnlinePlayers();
/**
* Get the maximum amount of players which can login to this server.
*
* @return the amount of players this server allows
*/
public int getMaxPlayers();
/**
* Set the maximum amount of players allowed to be logged in at once.
*
* @param maxPlayers The maximum amount of concurrent players
*/
void setMaxPlayers(int maxPlayers);
/**
* Get the game port that the server runs on.
*
* @return the port number of this server
*/
public int getPort();
/**
* Get the view distance from this server.
*
* @return the view distance from this server.
*/
public int getViewDistance();
/**
* Get the simulation distance from this server.
*
* @return the simulation distance from this server.
*/
public int getSimulationDistance();
/**
* Get the IP that this server is bound to, or empty string if not
* specified.
*
* @return the IP string that this server is bound to, otherwise empty
* string
*/
@NotNull
public String getIp();
/**
* Get world type (level-type setting) for default world.
*
* @return the value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1)
*/
@NotNull
public String getWorldType();
/**
* Get generate-structures setting.
*
* @return true if structure generation is enabled, false otherwise
*/
public boolean getGenerateStructures();
/**
* Get max world size.
*
* @return the maximum world size as specified for the server
*/
public int getMaxWorldSize();
/**
* Gets whether this server allows the End or not.
*
* @return whether this server allows the End or not
*/
public boolean getAllowEnd();
/**
* Gets whether this server allows the Nether or not.
*
* @return whether this server allows the Nether or not
*/
public boolean getAllowNether();
/**
* Gets whether the server is logging the IP addresses of players.
*
* @return whether the server is logging the IP addresses of players
*/
public boolean isLoggingIPs();
/**
* Gets a list of packs to be enabled.
*
* @return a list of packs names
*/
@NotNull
public List
* This is the same as calling {@link #broadcast(java.lang.String,
* java.lang.String)} to {@link #BROADCAST_CHANNEL_USERS}
*
* @param message the message
* @return the number of players
* @deprecated use {@link #broadcast(net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
public int broadcastMessage(@NotNull String message);
// Paper start
/**
* Sends the component to all online players.
*
* @param component the component to send
* @deprecated use {@code sendMessage} methods that accept {@link net.kyori.adventure.text.Component}
*/
@Deprecated
public default void broadcast(@NotNull net.md_5.bungee.api.chat.BaseComponent component) {
spigot().broadcast(component);
}
/**
* Sends an array of components as a single message to all online players.
*
* @param components the components to send
* @deprecated use {@code sendMessage} methods that accept {@link net.kyori.adventure.text.Component}
*/
@Deprecated
public default void broadcast(@NotNull net.md_5.bungee.api.chat.BaseComponent... components) {
spigot().broadcast(components);
}
// Paper end
/**
* Gets the name of the update folder. The update folder is used to safely
* update plugins at the right moment on a plugin load.
*
* The update folder name is relative to the plugins folder.
*
* @return the name of the update folder
*/
@NotNull
public String getUpdateFolder();
/**
* Gets the update folder. The update folder is used to safely update
* plugins at the right moment on a plugin load.
*
* @return the update folder
*/
@NotNull
public File getUpdateFolderFile();
/**
* Gets the value of the connection throttle setting.
*
* @return the value of the connection throttle setting
*/
public long getConnectionThrottle();
/**
* Gets default ticks per animal spawns value.
*
* Example Usage:
*
* Note: If set to 0, animal spawning will be disabled. We
* recommend using spawn-animals to control this instead.
*
* Minecraft default: 400.
*
* @return the default ticks per animal spawns value
* @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
public int getTicksPerAnimalSpawns();
/**
* Gets the default ticks per monster spawns value.
*
* Example Usage:
*
* Note: If set to 0, monsters spawning will be disabled. We
* recommend using spawn-monsters to control this instead.
*
* Minecraft default: 1.
*
* @return the default ticks per monsters spawn value
* @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
public int getTicksPerMonsterSpawns();
/**
* Gets the default ticks per water mob spawns value.
*
* Example Usage:
*
* Note: If set to 0, water mobs spawning will be disabled.
*
* Minecraft default: 1.
*
* @return the default ticks per water mobs spawn value
* @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
public int getTicksPerWaterSpawns();
/**
* Gets the default ticks per water ambient mob spawns value.
*
* Example Usage:
*
* Note: If set to 0, ambient mobs spawning will be disabled.
*
* Minecraft default: 1.
*
* @return the default ticks per water ambient mobs spawn value
* @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
public int getTicksPerWaterAmbientSpawns();
/**
* Gets the default ticks per water underground creature spawns value.
*
* Example Usage:
*
* Note: If set to 0, water underground creature spawning will be disabled.
*
* Minecraft default: 1.
*
* @return the default ticks per water underground creature spawn value
* @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
public int getTicksPerWaterUndergroundCreatureSpawns();
/**
* Gets the default ticks per ambient mob spawns value.
*
* Example Usage:
*
* Note: If set to 0, ambient mobs spawning will be disabled.
*
* Minecraft default: 1.
*
* @return the default ticks per ambient mobs spawn value
* @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
public int getTicksPerAmbientSpawns();
/**
* Gets the default ticks per {@link SpawnCategory} spawns value.
*
* Example Usage:
*
* Note: If set to 0, {@link SpawnCategory} mobs spawning will be disabled.
*
* @param spawnCategory the category of spawn
* @return the default ticks per {@link SpawnCategory} mobs spawn value
* @throws IllegalArgumentException if the category is {@link SpawnCategory#MISC}
*/
public int getTicksPerSpawns(@NotNull SpawnCategory spawnCategory);
/**
* Gets a player whose name matches the given name closest.
*
* Use {@link #getPlayerExact(String)} to get the player matching the input exactly
* and {@link #matchPlayer(String)} if you want a list of all players matching the input.
*
* This method may not return objects for offline players.
*
* @param name the name to look up
* @return a player if one was found, null otherwise
*/
@Nullable
public Player getPlayer(@NotNull String name);
/**
* Gets the player with the exact given name, case insensitive.
*
* @param name Exact name of the player to retrieve
* @return a player object if one was found, null otherwise
*/
@Nullable
public Player getPlayerExact(@NotNull String name);
/**
* Attempts to match any players with the given name, and returns a list
* of all possibly matches.
*
* This list is not sorted in any particular order. If an exact match is
* found, the returned list will only contain a single result.
*
* @param name the (partial) name to match
* @return list of all possible players
*/
@NotNull
public List
* If the world is already loaded, it will just return the equivalent of
* getWorld(creator.name()).
*
* @param creator the options to use when creating the world
* @return newly created or loaded world
*/
@Nullable
public World createWorld(@NotNull WorldCreator creator);
/**
* Unloads a world with the given name.
*
* @param name Name of the world to unload
* @param save whether to save the chunks before unloading
* @return true if successful, false otherwise
*/
public boolean unloadWorld(@NotNull String name, boolean save);
/**
* Unloads the given world.
*
* @param world the world to unload
* @param save whether to save the chunks before unloading
* @return true if successful, false otherwise
*/
public boolean unloadWorld(@NotNull World world, boolean save);
/**
* Gets the world with the given name.
*
* @param name the name of the world to retrieve
* @return a world with the given name, or null if none exists
*/
@Nullable
public World getWorld(@NotNull String name);
/**
* Gets the world from the given Unique ID.
*
* @param uid a unique-id of the world to retrieve
* @return a world with the given Unique ID, or null if none exists
*/
@Nullable
public World getWorld(@NotNull UUID uid);
/**
* Create a new virtual {@link WorldBorder}.
*
* Note that world borders created by the server will not respect any world
* scaling effects (i.e. coordinates are not divided by 8 in the nether).
*
* @return the created world border instance
*
* @see Player#setWorldBorder(WorldBorder)
*/
@NotNull
public WorldBorder createWorldBorder();
/**
* Gets the map from the given item ID.
*
* @param id the id of the map to get
* @return a map view if it exists, or null otherwise
*/
// @Deprecated(since = "1.6.2") // Paper - Not a magic value
@Nullable
public MapView getMap(int id);
/**
* Create a new map with an automatically assigned ID.
*
* @param world the world the map will belong to
* @return a newly created map view
*/
@NotNull
public MapView createMap(@NotNull World world);
/**
* Create a new explorer map targeting the closest nearby structure of a
* given {@link StructureType}.
* The list is formatted as a crafting matrix where the index follow
* the pattern below: NOTE: This method will not modify the provided ItemStack array, for that, use
* {@link #craftItem(ItemStack[], World, Player)}. The list is formatted as a crafting matrix where the index follow
* the pattern below: The {@link World} and {@link Player} arguments are required to fulfill the Bukkit Crafting
* events. Calls {@link org.bukkit.event.inventory.PrepareItemCraftEvent} to imitate the {@link Player}
* initiating the crafting event. The list is formatted as a crafting matrix where the index follow
* the pattern below: The list is formatted as a crafting matrix where the index follow
* the pattern below: The {@link World} and {@link Player} arguments are required to fulfill the Bukkit Crafting
* events. Calls {@link org.bukkit.event.inventory.PrepareItemCraftEvent} to imitate the {@link Player}
* initiating the crafting event. The list is formatted as a crafting matrix where the index follow
* the pattern below:
* This is the same as calling {@link #broadcast(net.kyori.adventure.text.Component,
* java.lang.String)} with the {@link #BROADCAST_CHANNEL_USERS} permission.
*
* @param message the message
* @return the number of players
*/
int broadcast(net.kyori.adventure.text.@NotNull Component message);
/**
* Broadcasts the specified message to every user with the given
* permission name.
*
* @param message message to broadcast
* @param permission the required permission {@link Permissible
* permissibles} must have to receive the broadcast
* @return number of message recipients
*/
int broadcast(net.kyori.adventure.text.@NotNull Component message, @NotNull String permission);
// Paper end
/**
* Gets the player by the given name, regardless if they are offline or
* online.
*
* This method may involve a blocking web request to get the UUID for the
* given name.
*
* This will return an object even if the player does not exist. To this
* method, all players will exist.
*
* @param name the name the player to retrieve
* @return an offline player
* @see #getOfflinePlayer(java.util.UUID)
*/
// @Deprecated(since = "1.7.5") // Paper
@NotNull
public OfflinePlayer getOfflinePlayer(@NotNull String name);
/**
* Gets the player by the given UUID, regardless if they are offline or
* online.
*
* This will return an object even if the player does not exist. To this
* method, all players will exist.
*
* @param id the UUID of the player to retrieve
* @return an offline player
*/
@NotNull
public OfflinePlayer getOfflinePlayer(@NotNull UUID id);
/**
* Creates a new {@link PlayerProfile}.
*
* @param uniqueId the unique id
* @param name the name
* @return the new PlayerProfile
* @throws IllegalArgumentException if both the unique id is
*
* This method can be expensive as it loads all the player data files from the disk.
*
* @return an array containing all previous players
*/
@NotNull
public OfflinePlayer[] getOfflinePlayers();
/**
* Gets the {@link Messenger} responsible for this server.
*
* @return messenger responsible for this server
*/
@NotNull
public Messenger getMessenger();
/**
* Gets the {@link HelpMap} providing help topics for this server.
*
* @return a help map for this server
*/
@NotNull
public HelpMap getHelpMap();
/**
* Creates an empty inventory with the specified type. If the type
* is {@link InventoryType#CHEST}, the new inventory has a size of 27;
* otherwise the new inventory has the normal size for its type.
*
* Note: this method should not be used to indicate the current
* synchronized state of the runtime. A current thread matching the main
* thread indicates that it is synchronized, but a mismatch does not
* preclude the same assumption.
*
* @return true if the current thread matches the expected primary thread,
* false otherwise
*/
boolean isPrimaryThread();
// Paper start
/**
* Gets the message that is displayed on the server list.
*
* @return the server's MOTD
*/
net.kyori.adventure.text.@NotNull Component motd();
/**
* Set the message that is displayed on the server list.
*
* @param motd The message to be displayed
*/
void motd(final net.kyori.adventure.text.@NotNull Component motd);
/**
* Gets the default message that is displayed when the server is stopped.
*
* @return the shutdown message
*/
net.kyori.adventure.text.@Nullable Component shutdownMessage();
// Paper end
/**
* Gets the message that is displayed on the server list.
*
* @return the servers MOTD
* @deprecated in favour of {@link #motd()}
*/
@NotNull
@Deprecated // Paper
String getMotd();
/**
* Set the message that is displayed on the server list.
*
* @param motd The message to be displayed
* @deprecated in favour of {@link #motd(net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
void setMotd(@NotNull String motd);
/**
* Gets the server links which will be sent to clients
*
* @return the server's links
*/
@NotNull
@ApiStatus.Experimental
ServerLinks getServerLinks();
/**
* Gets the default message that is displayed when the server is stopped.
*
* @return the shutdown message
* @deprecated in favour of {@link #shutdownMessage()}
*/
@Nullable
@Deprecated // Paper
String getShutdownMessage();
/**
* Gets the current warning state for the server.
*
* @return the configured warning state
*/
@NotNull
public WarningState getWarningState();
/**
* Gets the instance of the item factory (for {@link ItemMeta}).
*
* @return the item factory
* @see ItemFactory
*/
@NotNull
ItemFactory getItemFactory();
/**
* Gets the instance of the entity factory (for {@link EntitySnapshot}).
*
* @return the entity factory
* @see EntityFactory
*/
@NotNull
EntityFactory getEntityFactory();
/**
* Gets the instance of the scoreboard manager.
*
* This will only exist after the first world has loaded.
*
* @return the scoreboard manager or null if no worlds are loaded.
*/
@NotNull // Paper
ScoreboardManager getScoreboardManager();
/**
* Get (or create) a new {@link Criteria} by its name.
*
* @param name the criteria name
* @return the criteria
* @see Criteria Criteria for a list of constants
*/
@NotNull
Criteria getScoreboardCriteria(@NotNull String name);
/**
* Gets an instance of the server's default server-icon.
*
* @return the default server-icon; null values may be used by the
* implementation to indicate no defined icon, but this behavior is
* not guaranteed
*/
@Nullable
CachedServerIcon getServerIcon();
/**
* Loads an image from a file, and returns a cached image for the specific
* server-icon.
*
* Size and type are implementation defined. An incompatible file is
* guaranteed to throw an implementation-defined {@link Exception}.
*
* @param file the file to load the from
* @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)}
* @throws IllegalArgumentException if image is null
* @throws Exception if the image does not meet current server server-icon
* specifications
*/
@NotNull
CachedServerIcon loadServerIcon(@NotNull File file) throws IllegalArgumentException, Exception;
/**
* Creates a cached server-icon for the specific image.
*
* Size and type are implementation defined. An incompatible file is
* guaranteed to throw an implementation-defined {@link Exception}.
*
* @param image the image to use
* @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)}
* @throws IllegalArgumentException if image is null
* @throws Exception if the image does not meet current server
* server-icon specifications
*/
@NotNull
CachedServerIcon loadServerIcon(@NotNull BufferedImage image) throws IllegalArgumentException, Exception;
/**
* Set the idle kick timeout. Any players idle for the specified amount of
* time will be automatically kicked.
*
* A value of 0 will disable the idle kick timeout.
*
* @param threshold the idle timeout in minutes
*/
public void setIdleTimeout(int threshold);
/**
* Gets the idle kick timeout.
*
* @return the idle timeout in minutes
*/
public int getIdleTimeout();
/**
* Gets the pause when empty threshold seconds. To save resources, the
* pause most functions after this time if there are no players online.
*
* @return the pause threshold in seconds
*/
public int getPauseWhenEmptyTime();
/**
* Sets the pause when empty threshold seconds. To save resources, the
* pause most functions after this time if there are no players online.
*
* A value of less than 1 will disable the setting
*
* @param seconds the pause threshold in seconds
*/
public void setPauseWhenEmptyTime(int seconds);
/**
* Create a ChunkData for use in a generator.
*
* See {@link ChunkGenerator#generateChunkData(org.bukkit.World, java.util.Random, int, int, org.bukkit.generator.ChunkGenerator.BiomeGrid)}
*
* @param world the world to create the ChunkData for
* @return a new ChunkData for the world
*
*/
@NotNull
public ChunkGenerator.ChunkData createChunkData(@NotNull World world);
/**
* Creates a boss bar instance to display to players. The progress
* defaults to 1.0
*
* @param title the title of the boss bar
* @param color the color of the boss bar
* @param style the style of the boss bar
* @param flags an optional list of flags to set on the boss bar
* @return the created boss bar
*/
@NotNull
BossBar createBossBar(@Nullable String title, @NotNull BarColor color, @NotNull BarStyle style, @NotNull BarFlag... flags);
/**
* Creates a boss bar instance to display to players. The progress defaults
* to 1.0.
*
* E.g. if the player 'jeb_' is currently playing on the server, calling {@code createProfile("JEB_")} will
* yield a profile with the name 'jeb_', their uuid and their textures.
* To bypass this pre-population on a case-insensitive name match, see {@link #createProfileExact(UUID, String)}.
*
*
* @param name Name to create profile for
* @return A PlayerProfile object
* @throws IllegalArgumentException if the name is longer than 16 characters
* @throws IllegalArgumentException if the name contains invalid characters
*/
@NotNull
com.destroystokyo.paper.profile.PlayerProfile createProfile(@NotNull String name);
/**
* Creates a PlayerProfile for the specified name/uuid
*
* Both UUID and Name can not be null at same time. One must be supplied.
* If a player with the passed uuid or name exists on the server at the time of creation, the returned player
* profile will be populated with the properties of said player (including their uuid and name).
*
* E.g. if the player 'jeb_' is currently playing on the server, calling {@code createProfile(null, "JEB_")} will
* yield a profile with the name 'jeb_', their uuid and their textures.
* To bypass this pre-population on an case-insensitive name match, see {@link #createProfileExact(UUID, String)}.
*
*
* The name comparison will compare the {@link String#toLowerCase()} version of both the passed name parameter and
* a players name to honour the case-insensitive nature of a mojang profile lookup.
*
* @param uuid UUID to create profile for
* @param name Name to create profile for
* @return A PlayerProfile object
* @throws IllegalArgumentException if the name is longer than 16 characters
* @throws IllegalArgumentException if the name contains invalid characters
*/
@NotNull
com.destroystokyo.paper.profile.PlayerProfile createProfile(@Nullable UUID uuid, @Nullable String name);
/**
* Creates an exact PlayerProfile for the specified name/uuid
*
* Both UUID and Name can not be null at same time. One must be supplied.
* If a player with the passed uuid or name exists on the server at the time of creation, the returned player
* profile will be populated with the properties of said player.
*
* Compared to {@link #createProfile(UUID, String)}, this method will never mutate the passed uuid or name.
* If a player with either the same uuid or a matching name (case-insensitive) is found on the server, their
* properties, such as textures, will be pre-populated in the profile, however the passed uuid and name stay intact.
*
* @param uuid UUID to create profile for
* @param name Name to create profile for
* @return A PlayerProfile object
* @throws IllegalArgumentException if the name is longer than 16 characters
* @throws IllegalArgumentException if the name contains invalid characters
*/
@NotNull
com.destroystokyo.paper.profile.PlayerProfile createProfileExact(@Nullable UUID uuid, @Nullable String name);
/**
* Get the current internal server tick
*
* @return Current tick
*/
int getCurrentTick();
/**
* Checks if the server is in the process of being shutdown.
*
* @return true if server is in the process of being shutdown
*/
boolean isStopping();
/**
* Returns the {@link com.destroystokyo.paper.entity.ai.MobGoals} manager
*
* @return the mob goals manager
*/
@NotNull
com.destroystokyo.paper.entity.ai.MobGoals getMobGoals();
// Paper end
}
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* This method uses implementation default values for radius and
* findUnexplored (usually 100, true).
*
* @param world the world the map will belong to
* @param location the origin location to find the nearest structure
* @param structureType the type of structure to find
* @return a newly created item stack
*
* @see World#locateNearestStructure(org.bukkit.Location,
* org.bukkit.StructureType, int, boolean)
*/
@NotNull
public ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType);
/**
* Create a new explorer map targeting the closest nearby structure of a
* given {@link StructureType}.
*
* This method uses implementation default values for radius and
* findUnexplored (usually 100, true).
*
* @param world the world the map will belong to
* @param location the origin location to find the nearest structure
* @param structureType the type of structure to find
* @param radius radius to search, see World#locateNearestStructure for more
* information
* @param findUnexplored whether to find unexplored structures
* @return the newly created item stack
*
* @see World#locateNearestStructure(org.bukkit.Location,
* org.bukkit.StructureType, int, boolean)
*/
@NotNull
public ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType, int radius, boolean findUnexplored);
/**
* Reloads the server, refreshing settings and plugin information.
*/
public void reload();
/**
* Reload only the Minecraft data for the server. This includes custom
* advancements and loot tables.
*/
public void reloadData();
/**
* Returns the primary logger associated with this server instance.
*
* @return Logger associated with this server
* @see org.bukkit.plugin.Plugin#getSLF4JLogger()
* @apiNote This logger is for the Minecraft server software, not for specific plugins. You should
* use a logger for a specific plugin, either via {@link org.bukkit.plugin.Plugin#getSLF4JLogger()}
* or {@link org.bukkit.plugin.Plugin#getLogger()} or create a specific logger for a class via slf4j.
* That way, log messages contain contextual information about the source of the message.
*/
@NotNull
@org.jetbrains.annotations.ApiStatus.Internal // Paper - internalize Bukkit#getLogger
public Logger getLogger();
/**
* Gets a {@link PluginCommand} with the given name or alias.
*
* @param name the name of the command to retrieve
* @return a plugin command if found, null otherwise
*/
@Nullable
public PluginCommand getPluginCommand(@NotNull String name);
/**
* Writes loaded players to disk.
*/
public void savePlayers();
/**
* Dispatches a command on this server, and executes it if found.
*
* @param sender the apparent sender of the command
* @param commandLine the command + arguments. Example: test abc
* 123
* @return returns false if no target is found
* @throws CommandException thrown when the executor for the given command
* fails with an unhandled exception
*/
public boolean dispatchCommand(@NotNull CommandSender sender, @NotNull String commandLine) throws CommandException;
/**
* Adds a recipe to the crafting manager.
*
* @param recipe the recipe to add
* @return true if the recipe was added, false if it wasn't for some
* reason
*/
@Contract("null -> false")
public boolean addRecipe(@Nullable Recipe recipe);
/**
* Get a list of all recipes for a given item. The stack size is ignored
* in comparisons. If the durability is -1, it will match any data value.
*
* @param result the item to match against recipe results
* @return a list of recipes with the given result
*/
@NotNull
public List
* [ 0 1 2 ]
* [ 3 4 5 ]
* [ 6 7 8 ]
*
*
*
* [ 0 1 2 ]
* [ 3 4 5 ]
* [ 6 7 8 ]
*
*
*
* [ 0 1 2 ]
* [ 3 4 5 ]
* [ 6 7 8 ]
*
*
* @param craftingMatrix list of items to be crafted from.
* Must not contain more than 9 items.
* @param world The world the crafting takes place in.
* @return the {@link ItemStack} resulting from the given crafting matrix, if no recipe is found
* an ItemStack of {@link Material#AIR} is returned.
*/
@NotNull
public ItemStack craftItem(@NotNull ItemStack[] craftingMatrix, @NotNull World world);
/**
* Get the crafted item using the list of {@link ItemStack} provided.
*
*
* [ 0 1 2 ]
* [ 3 4 5 ]
* [ 6 7 8 ]
*
*
*
* [ 0 1 2 ]
* [ 3 4 5 ]
* [ 6 7 8 ]
*
*
* @param craftingMatrix list of items to be crafted from.
* Must not contain more than 9 items.
* @param world The world the crafting takes place in.
* @return resulting {@link ItemCraftResult} containing the resulting item, matrix and any overflow items.
*/
@NotNull
public ItemCraftResult craftItemResult(@NotNull ItemStack[] craftingMatrix, @NotNull World world);
/**
* Get an iterator through the list of crafting recipes.
*
* @return an iterator
*/
@NotNull
public Iteratornull and the name is null or blank
* @deprecated use {@link #createProfile(UUID, String)}
*/
@NotNull
@Deprecated(since = "1.18.1") // Paper
PlayerProfile createPlayerProfile(@Nullable UUID uniqueId, @Nullable String name);
/**
* Creates a new {@link PlayerProfile}.
*
* @param uniqueId the unique id
* @return the new PlayerProfile
* @throws IllegalArgumentException if the unique id is null
* @deprecated use {@link #createProfile(UUID)}
*/
@NotNull
@Deprecated(since = "1.18.1") // Paper
PlayerProfile createPlayerProfile(@NotNull UUID uniqueId);
/**
* Creates a new {@link PlayerProfile}.
*
* @param name the name
* @return the new PlayerProfile
* @throws IllegalArgumentException if the name is null or
* blank
* @deprecated use {@link #createProfile(String)}
*/
@NotNull
@Deprecated(since = "1.18.1") // Paper
PlayerProfile createPlayerProfile(@NotNull String name);
/**
* Gets a set containing all current IPs that are banned.
*
* @return a set containing banned IP addresses
*/
@NotNull
public Set
* {@link InventoryType#WORKBENCH} will not process crafting recipes if
* created with this method. Use
* {@link Player#openWorkbench(Location, boolean)} instead.
*
* {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
* for possible enchanting results. Use
* {@link Player#openEnchanting(Location, boolean)} instead.
*
* @param owner the holder of the inventory, or null to indicate no holder
* @param type the type of inventory to create
* @return a new inventory
* @throws IllegalArgumentException if the {@link InventoryType} cannot be
* viewed.
*
* @see InventoryType#isCreatable()
*/
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type);
// Paper start
/**
* Creates an empty inventory with the specified type and title. If the type
* is {@link InventoryType#CHEST}, the new inventory has a size of 27;
* otherwise the new inventory has the normal size for its type.
* It should be noted that some inventory types do not support titles and
* may not render with said titles on the Minecraft client.
*
* {@link InventoryType#WORKBENCH} will not process crafting recipes if
* created with this method. Use
* {@link Player#openWorkbench(Location, boolean)} instead.
*
* {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
* for possible enchanting results. Use
* {@link Player#openEnchanting(Location, boolean)} instead.
*
* @param owner The holder of the inventory; can be null if there's no holder.
* @param type The type of inventory to create.
* @param title The title of the inventory, to be displayed when it is viewed.
* @return The new inventory.
* @throws IllegalArgumentException if the {@link InventoryType} cannot be
* viewed.
*
* @see InventoryType#isCreatable()
*/
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type, net.kyori.adventure.text.@NotNull Component title);
// Paper end
/**
* Creates an empty inventory with the specified type and title. If the type
* is {@link InventoryType#CHEST}, the new inventory has a size of 27;
* otherwise the new inventory has the normal size for its type.
* It should be noted that some inventory types do not support titles and
* may not render with said titles on the Minecraft client.
*
* {@link InventoryType#WORKBENCH} will not process crafting recipes if
* created with this method. Use
* {@link Player#openWorkbench(Location, boolean)} instead.
*
* {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
* for possible enchanting results. Use
* {@link Player#openEnchanting(Location, boolean)} instead.
*
* @param owner The holder of the inventory; can be null if there's no holder.
* @param type The type of inventory to create.
* @param title The title of the inventory, to be displayed when it is viewed.
* @return The new inventory.
* @throws IllegalArgumentException if the {@link InventoryType} cannot be
* viewed.
* @deprecated in favour of {@link #createInventory(InventoryHolder, InventoryType, net.kyori.adventure.text.Component)}
*
* @see InventoryType#isCreatable()
*/
@Deprecated // Paper
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type, @NotNull String title);
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the
* specified size.
*
* @param owner the holder of the inventory, or null to indicate no holder
* @param size a multiple of 9 as the size of inventory to create
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
*/
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, int size) throws IllegalArgumentException;
// Paper start
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the
* specified size and title.
*
* @param owner the holder of the inventory, or null to indicate no holder
* @param size a multiple of 9 as the size of inventory to create
* @param title the title of the inventory, displayed when inventory is
* viewed
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
*/
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, int size, net.kyori.adventure.text.@NotNull Component title) throws IllegalArgumentException;
// Paper end
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the
* specified size and title.
*
* @param owner the holder of the inventory, or null to indicate no holder
* @param size a multiple of 9 as the size of inventory to create
* @param title the title of the inventory, displayed when inventory is
* viewed
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
* @deprecated in favour of {@link #createInventory(InventoryHolder, int, net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, int size, @NotNull String title) throws IllegalArgumentException;
// Paper start
/**
* Creates an empty merchant.
*
* @param title the title of the corresponding merchant inventory, displayed
* when the merchant inventory is viewed
* @return a new merchant
*/
@NotNull Merchant createMerchant(net.kyori.adventure.text.@Nullable Component title);
// Paper start
/**
* Creates an empty merchant.
*
* @param title the title of the corresponding merchant inventory, displayed
* when the merchant inventory is viewed
* @return a new merchant
* @deprecated in favour of {@link #createMerchant(net.kyori.adventure.text.Component)}
*/
@NotNull
@Deprecated // Paper
Merchant createMerchant(@Nullable String title);
/**
* Gets the amount of consecutive neighbor updates before skipping
* additional ones.
*
* @return the amount of consecutive neighbor updates, if the value is
* negative then the limit it's not used
*/
int getMaxChainedNeighborUpdates();
/**
* Gets user-specified limit for number of monsters that can spawn in a
* chunk.
*
* @return the monster spawn limit
* @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
int getMonsterSpawnLimit();
/**
* Gets user-specified limit for number of animals that can spawn in a
* chunk.
*
* @return the animal spawn limit
* @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
int getAnimalSpawnLimit();
/**
* Gets user-specified limit for number of water animals that can spawn in
* a chunk.
*
* @return the water animal spawn limit
* @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
int getWaterAnimalSpawnLimit();
/**
* Gets user-specified limit for number of water ambient mobs that can spawn
* in a chunk.
*
* @return the water ambient spawn limit
* @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
int getWaterAmbientSpawnLimit();
/**
* Get user-specified limit for number of water creature underground that can spawn
* in a chunk.
* @return the water underground creature limit
* @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
int getWaterUndergroundCreatureSpawnLimit();
/**
* Gets user-specified limit for number of ambient mobs that can spawn in
* a chunk.
*
* @return the ambient spawn limit
* @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
*/
@Deprecated(since = "1.18.1")
int getAmbientSpawnLimit();
/**
* Gets user-specified limit for number of {@link SpawnCategory} mobs that can spawn in
* a chunk.
*
* Note: the {@link SpawnCategory#MISC} are not consider.
*
* @param spawnCategory the category spawn
* @return the {@link SpawnCategory} spawn limit
*/
int getSpawnLimit(@NotNull SpawnCategory spawnCategory);
/**
* Checks the current thread against the expected primary thread for the
* server.
*
* This instance is added to the persistent storage of the server and will
* be editable by commands and restored after restart.
*
* @param key the key of the boss bar that is used to access the boss bar
* @param title the title of the boss bar
* @param color the color of the boss bar
* @param style the style of the boss bar
* @param flags an optional list of flags to set on the boss bar
* @return the created boss bar
*/
@NotNull
KeyedBossBar createBossBar(@NotNull NamespacedKey key, @Nullable String title, @NotNull BarColor color, @NotNull BarStyle style, @NotNull BarFlag... flags);
/**
* Gets an unmodifiable iterator through all persistent bossbars.
*
*
*
* e.g. bossbars created using the bossbar command
*
* @return a bossbar iterator
*/
@NotNull
Iterator
*
*
* e.g. bossbars created using the bossbar command
*
* @param key unique bossbar key
* @return bossbar or null if not exists
*/
@Nullable
KeyedBossBar getBossBar(@NotNull NamespacedKey key);
/**
* Removes a {@link KeyedBossBar} specified by this key.
*
*
*
* e.g. bossbars created using the bossbar command
*
* @param key unique bossbar key
* @return true if removal succeeded or false
*/
boolean removeBossBar(@NotNull NamespacedKey key);
/**
* Gets an entity on the server by its UUID
*
* @param uuid the UUID of the entity
* @return the entity with the given UUID, or null if it isn't found
*/
@Nullable
Entity getEntity(@NotNull UUID uuid);
// Paper start
/**
* Gets the current server TPS
*
* @return current server TPS (1m, 5m, 15m in Paper-Server)
*/
@NotNull
public double[] getTPS();
/**
* Get a sample of the servers last tick times (in nanos)
*
* @return A sample of the servers last tick times (in nanos)
*/
@NotNull
long[] getTickTimes();
/**
* Get the average tick time (in millis)
*
* @return Average tick time (in millis)
*/
double getAverageTickTime();
// Paper end
// Paper start
/**
* Gets the active {@link org.bukkit.command.CommandMap}
*
* @return the active command map
*/
@NotNull
org.bukkit.command.CommandMap getCommandMap();
/**
* Get the advancement specified by this key.
*
* @param key unique advancement key
* @return advancement or null if not exists
*/
@Nullable
Advancement getAdvancement(@NotNull NamespacedKey key);
/**
* Get an iterator through all advancements. Advancements cannot be removed
* from this iterator,
*
* @return an advancement iterator
*/
@NotNull
Iterator
* If material is specified, then the data string must not also
* contain the material.
*
* @param material the material
* @param data data string
* @return new data instance
* @throws IllegalArgumentException if the specified data is not valid
*/
@NotNull
@Contract("null, null -> fail")
BlockData createBlockData(@Nullable Material material, @Nullable String data) throws IllegalArgumentException;
/**
* Gets a tag which has already been defined within the server. Plugins are
* suggested to use the concrete tags in {@link Tag} rather than this method
* which makes no guarantees about which tags are available, and may also be
* less performant due to lack of caching.
*
* Tags will be searched for in an implementation specific manner, but a
* path consisting of namespace/tags/registry/key is expected.
*
* Server implementations are allowed to handle only the registries
* indicated in {@link Tag}.
*
* @param
* Server implementations are allowed to handle only the registries
* indicated in {@link Tag}.
*
* No guarantees are made about the mutability of the returned iterator.
*
* @param
* No guarantees are made about the selector format, other than they match
* the Vanilla format for the active Minecraft version.
*
* Usually a selector will start with '@', unless selecting a Player in
* which case it may simply be the Player's name or UUID.
*
* Note that in Vanilla, elevated permissions are usually required to use
* '@' selectors, but this method should not check such permissions from the
* sender.
*
* @param sender the sender to execute as, must be provided
* @param selector the selection string
* @return a list of the selected entities. The list will not be null, but
* no further guarantees are made.
* @throws IllegalArgumentException if the selector is malformed in any way
* or a parameter is null
*/
@NotNull
List
* If no registry is present for the given class null will be returned.
*
* Depending on the implementation not every registry present in
* {@link Registry} will be returned by this method.
*
* @param tClass of the registry to get
* @param