☕ Cómo Hacer un Plugin Minecraft en Java 2026 — Guía Completa Spigot/Paper

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.tunombre</groupId>
    <artifactId>MiPrimerPlugin</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <repositories>
        <repository>
            <id>papermc</id>
            <url>https://repo.papermc.io/repository/maven-public/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>io.papermc.paper</groupId>
            <artifactId>paper-api</artifactId>
            <version>1.21.4-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>21</source>
                    <target>21</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

name: MiPrimerPlugin
version: 1.0.0
main: com.tunombre.MiPrimerPlugin
api-version: '1.21'
author: TuNombre
description: Mi primer plugin de Minecraft

commands:
  hola:
    description: Saluda al jugador
    usage: /hola
    permission: miplugin.hola

permissions:
  miplugin.hola:
    description: Permite usar /hola
    default: true

package com.tunombre;

import org.bukkit.plugin.java.JavaPlugin;

public class MiPrimerPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getLogger().info("MiPrimerPlugin activado correctamente!");
        
        // Registrar el listener de eventos
        getServer().getPluginManager().registerEvents(new MisEventos(this), this);
        
        // Registrar el comando /hola
        getCommand("hola").setExecutor(new ComandoHola());
    }

    @Override
    public void onDisable() {
        getLogger().info("MiPrimerPlugin desactivado.");
    }
}

package com.tunombre;

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerDeathEvent;
import org.bukkit.event.block.BlockBreakEvent;

public class MisEventos implements Listener {

    private final MiPrimerPlugin plugin;

    public MisEventos(MiPrimerPlugin plugin) {
        this.plugin = plugin;
    }

    // Se ejecuta cuando un jugador entra al servidor
    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        event.getPlayer().sendMessage("§aiBienvenido al servidor, §e" + event.getPlayer().getName() + "§a!");
    }

    // Se ejecuta cuando un jugador muere
    @EventHandler
    public void onPlayerDeath(PlayerDeathEvent event) {
        event.getDeathMessage( "\u00a7c" + event.getEntity().getName() + " murió. §f¡Qué mal!");
    }

    // Se ejecuta cuando se rompe un bloque
    @EventHandler
    public void onBlockBreak(BlockBreakEvent event) {
        // Cancelar el evento niega la acción completamente:
        // event.setCancelled(true);
        
        plugin.getLogger().info(event.getPlayer().getName() + 
            " rompió " + event.getBlock().getType());
    }
}

package com.tunombre;

import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class ComandoHola implements CommandExecutor {

    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        
        // Verificar que lo ejecuta un jugador (no la consola)
        if (!(sender instanceof Player player)) {
            sender.sendMessage("Este comando solo lo pueden usar jugadores.");
            return true;
        }
        
        if (args.length == 0) {
            player.sendMessage("§aHola, §e" + player.getName() + "§a!");
        } else {
            // /hola [mensaje]
            String mensaje = String.join(" ", args);
            player.sendMessage("§e" + player.getName() + " dice: §f" + mensaje);
        }
        
        return true; // retornar true = comando ejecutado correctamente
    }
}

// En onEnable() de la clase principal:

// Crea el config.yml si no existe
saveDefaultConfig();

// Leer valores
String mensaje = getConfig().getString("mensaje-bienvenida", "Bienvenido!");
boolean modoDebug = getConfig().getBoolean("debug", false);
int limiteJugadores = getConfig().getInt("max-jugadores", 20);

// Guardar/modificar config en runtime
getConfig().set("ultima-actualizacion", System.currentTimeMillis());
saveConfig();

// Recargar desde disco
reloadConfig();

mensaje-bienvenida: "Bienvenido al servidor!"
debug: false
max-jugadores: 20