luffy_uchia

Create a complete Minecraft server plugin called PvP Bot NPC.

Main idea

The plugin lets server administrators spawn NPCs representing different bot difficulty levels. When a player clicks an NPC, they are teleported from the lobby to a private 1v1 PvP arena where they fight an AI/bot. When either the player or the bot dies, the player is automatically returned to the lobby.

Commands

Use the main command:

/pvpbotnpc <level> spawn

Examples:

/pvpbotnpc 1 spawn /pvpbotnpc 2 spawn /pvpbotnpc 3 spawn

The <level> number determines the bot's difficulty.

Also implement useful management commands:

/pvpbotnpc <level> spawn — Spawn an NPC for that bot level at the administrator's current location.

/pvpbotnpc remove — Remove the NPC the administrator is looking at.

/pvpbotnpc reload — Reload the plugin configuration.

/pvpbotnpc setlobby — Set the lobby return location.

/pvpbotnpc setarena <level> — Set/configure an arena for a specific bot level.

Make command permissions configurable, with a default permission such as:

pvpbotnpc.admin

NPC appearance

Each level should have its own NPC.

For example:

Level 1 NPC display name: &aBot Level 1 Level 2 NPC display name: &eBot Level 2 Level 3 NPC display name: &cBot Level 3

Make the display name fully configurable in config.yml.

Each NPC must support a configurable Minecraft skin. Allow the skin to be configured using a player name, UUID, or skin texture/value if supported by the chosen NPC system.

The NPC should be clearly identifiable as a PvP bot.

Clicking an NPC

When a player right-clicks or otherwise interacts with a PvP Bot NPC:

Detect which bot level the NPC represents.

Check whether the player is already fighting a bot.

If they are already in a match, do not allow them to start another match.

Find an available arena for that bot level.

Teleport the player into the arena.

Spawn/create the appropriate AI bot.

Start the 1v1 match.

Give the player the configured PvP kit/loadout for that level.

Prevent the player from escaping the arena if possible.

Display useful messages such as: &aYou are now fighting Bot Level 1! &cDefeat the bot to return to the lobby.

Bot levels

Create a scalable difficulty system.

Do NOT hard-code only three levels. The plugin should support as many levels as the server owner wants.

For example:

Level 1:

Easy AI Lower attack speed Lower accuracy/reaction Basic movement Basic combat

Level 2:

Better movement Faster reactions Better attacking Better targeting

Level 3:

Advanced movement Faster reactions Better combat decisions More aggressive behavior

Higher levels should continue increasing the difficulty using configurable values.

All bot difficulty settings should be configurable in config.yml.

AI bot

The bot should behave like a real Minecraft PvP opponent as much as the selected Minecraft/server API allows.

It should be able to:

Detect the player.

Follow the player.

Attack the player.

Rotate/look toward the player.

Move around the arena.

Chase the player.

React to the player's position.

Stop attacking when the match ends.

Die normally.

Be removed cleanly after the match.

Use a reliable NPC/entity approach compatible with the target Minecraft version.

If true human-like AI is not possible using the standard API alone, implement the best practical PvP combat AI possible rather than creating a fake/static NPC.

Match system

Each player should have an independent match.

A player entering a match should be tracked by UUID.

Prevent:

Multiple simultaneous matches for one player.

Multiple bots being assigned to the same player.

Players interfering with another player's match.

When a match starts, save the player's:

Location Inventory Armor Health Food level Game mode Potion effects Other relevant player state

Then prepare them for the PvP match.

Match ending

The match must end when either:

Player kills bot

Announce that the player won.

Optionally give configurable rewards.

Remove the bot.

Clean up the arena.

Restore the player's saved state.

Teleport the player back to the lobby.

Bot kills player

Announce that the player lost.

Remove the bot.

Clean up the arena.

Restore the player's saved state where appropriate.

Teleport the player back to the lobby.

Also handle abnormal situations safely:

Player disconnects.

Server/plugin reloads.

Player dies.

Bot disappears.

Arena becomes unavailable.

Player leaves the arena.

Plugin shuts down.

There must be no duplicated items, lost inventories, stuck players, or orphaned bots.

Arena system

Support multiple arenas.

For example:

arena1 arena2 arena3

Each arena should have:

Player spawn location Bot spawn location Level/difficulty Enabled/disabled state

The plugin should automatically find an available arena when a player clicks an NPC.

Multiple players should be able to fight bots simultaneously in different arenas.

Make arena configuration easy to understand and edit.

Lobby

Add:

/pvpbotnpc setlobby

This saves the current location as the lobby location.

After every completed match, the player should return to this location.

Make the lobby location persistent in config.yml or a separate data file.

Configuration

Create a clean and well-commented config.yml.

It should contain settings for:

NPC display names NPC skins Bot levels Bot difficulty Bot health Bot damage Bot attack speed Bot movement speed AI reaction time Arena locations Lobby location PvP kits Match messages Win rewards Loss behavior Permissions Sounds Effects Whether players can use commands during matches Whether players can leave the arena Match timeout

Example configuration structure:

npc-levels: 1: display-name: "&aPvP Bot &7- &aLevel 1" skin: "BotLevel1" difficulty: 1 2: display-name: "&ePvP Bot &7- &eLevel 2" skin: "BotLevel2" difficulty: 2 3: display-name: "&cPvP Bot &7- &cLevel 3" skin: "BotLevel3" difficulty: 3

match: timeout: 300 return-to-lobby: true

messages: match-start: "&aYou are now fighting Bot Level %level%!" win: "&aYou defeated the bot!" lose: "&cThe bot defeated you!" no-arena: "&cThere is currently no available arena." already-in-match: "&cYou are already fighting a bot."

NPC persistence

NPCs must remain after a server restart.

Save spawned NPC information to a data file such as:

npcs.yml

When the server starts, automatically recreate/load all configured NPCs.

Compatibility

Before implementing the plugin, determine the appropriate Minecraft server API/version and use a modern compatible implementation.

Prefer:

Paper API where appropriate.

Java.

Gradle or Maven.

A reliable NPC library if necessary.

Clearly state any required dependencies.

Do not use unsafe NMS code unnecessarily. If NMS is required for the AI/NPC implementation, isolate it properly and document the dependency.

Project structure

Create a complete production-ready plugin project, including:

plugin.yml Main plugin class Command classes NPC manager Bot/AI manager Arena manager Match manager Configuration manager Data persistence Event listeners Player state/inventory manager Utility classes Build configuration README Example configuration files

Keep the code modular and maintainable.

Important requirements

The final result must be an actual working plugin, not pseudocode or a partial example.

Make sure the project compiles successfully.

Handle errors gracefully and log useful information to the console.

Use UUIDs rather than player names for persistent player/match tracking.

Make all important settings configurable.

If a requested feature requires an external dependency, include the dependency and explain exactly how to install it.

Most importantly, the complete gameplay flow should work like this:

Lobby → Click Bot NPC → Select Bot Level → Find Arena → Teleport Player → Spawn Bot → 1v1 PvP Fight → Player or Bot Dies → End Match → Clean Up → Return Player to Lobby

Also make it easy to add Level 4, Level 5, Level 6, etc. later without changing the Java source code.

Kodari AI
KodariAug 20 at 3:12 pm 8
PvPBotNPC
A comprehensive Minecraft server plugin that spawns configurable NPCs representing different bot difficulty levels. When players click an NPC, they are teleported to private 1v1 PvP arenas to fight AI-controlled bots. The plugin features a scalable difficulty system supporting unlimited bot levels, persistent NPC spawning, automatic arena assignment, player state saving/restoration, match management, and full configuration through config.yml. Includes commands for spawning/removing NPCs, setting lobby/arena locations, and reloading configuration. Matches end when either player or bot dies, returning players to the lobby with their original inventory, health, and location restored. Designed for Paper API with modular architecture including separate managers for NPCs, bots, arenas, matches, and player state.
  1. Create the Gradle/Paper project metadata and documented runtime dependency.

  2. Create configuration, persistence, arena, NPC, bot AI, match, state, command, and listener classes.

  3. Create plugin.yml, default configuration, NPC data template, and README with setup and arena instructions.

Implemented the complete PvPBotNPC Paper plugin project.

Key features included:

  • Paper 1.20.6+ / Java 21 Gradle project

  • Citizens-based persistent player NPCs

  • Configurable NPC names, skins, bot levels, kits, damage, health, speed, accuracy, reaction time, and attack range

  • Dynamic difficulty levels without Java changes

  • Independent arena allocation and occupancy tracking

  • Lobby and arena setup commands

  • Player state preservation and restoration

  • Bot AI for chasing, strafing, facing, and attacking

  • Match timeout handling

  • Player death, disconnect, quit, shutdown, and bot cleanup handling

  • Command and arena-boundary restrictions

  • Configurable rewards, sounds, particles, and messages

  • Persistent npcs.yml NPC storage

  • Citizens dependency documentation

  • README setup instructions

Commands:

Plain Text
/pvpbotnpc <level> spawn
/pvpbotnpc remove
/pvpbotnpc reload
/pvpbotnpc setlobby
/pvpbotnpc setarena <level> [id]

Required server dependency:

Plain Text
Citizens

Build with:

Shell
./gradlew build

Install the generated plugin jar and Citizens in the server’s plugins directory.

Kodari can make mistakes. Review important code before using.
Files
src
build.gradle
manifest.kod
README.md
settings.gradle
Code
21 1,272
src/main/java/com/kodari/pvpbotnpc/PvPBotNPCPlugin.java
package com.kodari.pvpbotnpc;

import com.kodari.pvpbotnpc.arena.ArenaManager;
import com.kodari.pvpbotnpc.command.PvPBotCommand;
import com.kodari.pvpbotnpc.config.ConfigManager;
import com.kodari.pvpbotnpc.listener.PvPBotListener;
import com.kodari.pvpbotnpc.match.MatchManager;
import com.kodari.pvpbotnpc.npc.NPCManager;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public final class PvPBotNPCPlugin extends JavaPlugin {
    private ConfigManager configManager;
    private ArenaManager arenaManager;
    private NPCManager npcManager;
    private MatchManager matchManager;

    @Override
    public void onEnable() {
        saveDefaultConfig();
        configManager = new ConfigManager(this);
        arenaManager = new ArenaManager(this);
        npcManager = new NPCManager(this);
        matchManager = new MatchManager(this);
        Bukkit.getPluginManager().registerEvents(new PvPBotListener(this), this);
        PvPBotCommand command = new PvPBotCommand(this);
        getCommand("pvpbotnpc").setExecutor(command);
        getCommand("pvpbotnpc").setTabCompleter(command);
        Bukkit.getScheduler().runTaskTimer(this, matchManager::tick, 1L, 1L);
        getLogger().info("PvPBotNPC enabled with " + configManager.getLevels().size() + " configured bot levels.");
    }

    @Override
    public void onDisable() {
        if (matchManager != null) matchManager.shutdown();
        if (npcManager != null) npcManager.shutdown();
    }

    public ConfigManager getConfigManager() { return configManager; }
    public ArenaManager getArenaManager() { return arenaManager; }
    public NPCManager getNpcManager() { return npcManager; }
    public MatchManager getMatchManager() { return matchManager; }
}