API Overview
Package Structure
The Bukkit API is organized into several key packages:
- org.bukkit - Core classes and interfaces
Contains the main Server and Plugin interfaces, as well as fundamental classes like Location and World.
- org.bukkit.entity - Entity-related classes
Includes Player, Entity, and all entity types that can exist in the game.
- org.bukkit.block - Block-related classes
Contains Block, BlockState, and related classes for manipulating blocks in the world.
- org.bukkit.inventory - Inventory management
Classes for working with inventories, items, and recipes.
- org.bukkit.event - Event system
Contains all event classes that your plugin can listen for.
- org.bukkit.configuration - Configuration handling
Classes for working with YAML configuration files.
- org.bukkit.command - Command framework
Classes for creating and managing commands.
How to Read Javadocs
Javadocs provide detailed information about classes, methods, and fields. Here's how to interpret them:
- Class documentation - Describes the purpose and behavior of a class
- Method signatures - Shows the return type, method name, and parameters
- Parameter descriptions - Explains what each parameter does
- Return value - Describes what the method returns
- Exceptions - Lists exceptions that might be thrown
- Since - Indicates which API version introduced this feature
- Deprecated - Marks methods that should no longer be used
When using the Javadocs, pay attention to the "Since" tag to ensure compatibility with your target Minecraft versions.
Key Classes and Interfaces
Core Plugin Classes
JavaPlugin
The base class for all Bukkit plugins. Extends the Plugin interface and provides implementation for common methods.
public void onEnable() Called when the plugin is enabled. Use this to initialize your plugin.
public void onDisable() Called when the plugin is disabled. Use this for cleanup.
public FileConfiguration getConfig() Returns the plugin's configuration file.
public File getDataFolder() Returns the folder where the plugin can store data.
Server
Represents the Minecraft server. Provides methods to access worlds, players, and server properties.
public Collection<? extends Player> getOnlinePlayers() Gets a list of all online players.
public World getWorld(String name) Gets the world with the given name.
public PluginManager getPluginManager() Gets the plugin manager for registering events and managing plugins.
Player and Entity Classes
Player
Represents a player connected to the server. Extends HumanEntity and provides player-specific methods.
public void sendMessage(String message) Sends a message to the player.
public boolean teleport(Location location) Teleports the player to the specified location.
public boolean hasPermission(String name) Checks if the player has the specified permission.
Entity
The base class for all entities in the game, including players, mobs, and items.
public Location getLocation() Gets the entity's current location.
public World getWorld() Gets the world the entity is in.
public boolean remove() Removes the entity from the world.
World and Block Classes
World
Represents a world on the server. Provides methods to access and modify blocks, spawn entities, and more.
public Block getBlockAt(int x, int y, int z) Gets the block at the specified coordinates.
public Entity spawnEntity(Location loc, EntityType type) Spawns an entity at the specified location.
Block
Represents a block in the world. Provides methods to get and set block data.
public Material getType() Gets the material type of the block.
public void setType(Material material) Sets the material type of the block.
public BlockState getState() Gets the block state for more advanced operations.
Common API Usage Examples
Event Handling
Events are a fundamental part of Bukkit plugin development. Here's how to listen for events:
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerQuitEvent;
public class PlayerListener implements Listener {
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
// This method is called whenever a player joins the server
event.setJoinMessage("Welcome, " + event.getPlayer().getName() + "!");
}
@EventHandler
public void onPlayerQuit(PlayerQuitEvent event) {
// This method is called whenever a player leaves the server
event.setQuitMessage(event.getPlayer().getName() + " has left the game.");
}
}Don't forget to register your listener in your main plugin class:
getServer().getPluginManager().registerEvents(new PlayerListener(), this);Configuration API
The Configuration API allows you to work with YAML configuration files:
// Load the default config.yml from your plugin's resources
saveDefaultConfig();
// Get values from the config
String serverName = getConfig().getString("server-name", "My Minecraft Server");
int maxPlayers = getConfig().getInt("max-players", 20);
List<String> welcomeMessages = getConfig().getStringList("welcome-messages");
// Set values in the config
getConfig().set("last-startup", System.currentTimeMillis());
getConfig().set("player-count", getServer().getOnlinePlayers().size());
// Save changes to the config
saveConfig();Persistent Data API
The Persistent Data API allows you to store custom data on entities, blocks, and items:
import org.bukkit.NamespacedKey;
import org.bukkit.entity.Player;
import org.bukkit.persistence.PersistentDataContainer;
import org.bukkit.persistence.PersistentDataType;
// Create a key for your data
NamespacedKey key = new NamespacedKey(this, "custom-data");
// Store data on a player
Player player = event.getPlayer();
PersistentDataContainer container = player.getPersistentDataContainer();
container.set(key, PersistentDataType.INTEGER, 42);
// Retrieve data from a player
if (container.has(key, PersistentDataType.INTEGER)) {
int value = container.get(key, PersistentDataType.INTEGER);
player.sendMessage("Your custom data value is: " + value);
}