Skip to content
RitomasssCommunity
Product documentation

TrainingBot Documentation

TrainingBot is an advanced Minecraft training bot plugin using Citizens, combat profiles, AI modes, menus and optional practice integration.

1.7.3Local source version
Java 21Bytecode target
Paper 26.3 build 207Paper API dependency
API 1.21Plugin descriptor

Overview#

Product purpose, target audience, main systems, dependencies and quick links.

Quick links: Installation, First Setup, Commands, Permissions, Configuration, GUI, Storage, Integrations, Common Setups, Troubleshooting, Changelog and Support.

What is TrainingBot?#

A bot profile and combat simulation system for crystal, nethpot, melee, diamondpot and training scenarios.

Who is it for?#

Practice servers, PvP trainers and bot research environments that need configurable combat opponents.

Supported server types#

Practice, PvP, training and bot duel servers.

Main features#

  • Bot control panel
  • Combat profiles
  • Crystal PvP AI
  • NethPot AI
  • Melee AI
  • DiamondPot AI
  • Citizens NPCs
  • EventPractice hook

Dependencies#

  • Citizens is optional; the plugin descriptor declares Folia support and the source includes a region-aware scheduler.
  • Local source version 1.7.3 compiles with Java 21 bytecode release.
  • The POM uses Paper API 26.3 build 207; plugin.yml declares API baseline 1.21.
  • These metadata do not establish exact server release compatibility. Verify against the product binary you install.
  • EventPractice optional
  • ONNX runtime library
  • MySQL/SQLite support

Installation#

Installation gets the plugin to boot. First Setup prepares it for production use.

Do not replace plugin jars while the server is running. Always make a backup before updating.
Download the latest TrainingBot jar from the official buyer/download source.
Stop the server before replacing the jar.
Upload the jar to /plugins.
Start the server once and confirm the plugin folder was generated.
Configure license, storage and core files listed in the Configuration section.
Restart the server and run the main status/admin command.

First Setup#

Recommended first configuration pass after the plugin has generated its files.

Make one change at a time, reload or restart, then test the player workflow with a real account.

Setup checklist#

  1. Install Citizens
  2. Create first bot profile
  3. Select combat mode
  4. Configure kit/equipment
  5. Set AI difficulty
  6. Spawn test bot
  7. Save profile

Production notes#

  • Give permissions through LuckPerms or your permission manager.
  • Keep backups of YAML files and database tables.
  • Use a staging server before large updates.
  • Do not claim Folia or network support unless the full setup has been tested.

Commands#

Commands, permissions, and usage examples.

Command entries are read from this product's plugin.yml.
/botCommand
Description

Opens the Bot Control Panel

Permission

trainingbot.use

Example

/bot

/trainingbotCommand
Description

Admin bot command

Permission

trainingbot.admin

Example

/trainingbot

Permissions#

Permission nodes are based on plugin.yml. Assign admin and bypass permissions carefully.

/lp group admin permission set trainingbot.admin true
/lp group default permission set trainingbot.use true
trainingbot.use

Allows usage of the bot command

Default: truePlayers
trainingbot.admin

Allows usage of the botadmin command

Default: opOwner/Admin

Configuration#

Configuration YAML files below contain short bundled default excerpts, not full files. Message YAML is documented only in Messages & Language.

Validate YAML indentation before restarting the server.
config.yml short excerpt, not full file

Main runtime settings, license, modules, limits, storage and feature behavior.

Short YAML preview only. This block shows selected lines from config.yml. The generated file contains more options than this docs excerpt.
# ...
# Short documentation excerpt from config.yml.
# This is not the complete YAML file.
# Lines before and after this preview are omitted from the docs.
# ...
# Training Bot Configuration
debug: false
license-key: "none"

# Database Configuration
database:
  method: "SQLITE" # Options: SQLITE, MYSQL
  mysql:
    host: "localhost"
    port: 3306
    database: "trainingbot"
    username: "root"
    password: ""
    use-ssl: false

# Color Format: MINIMESSAGE or LEGACY
color-format: "LEGACY"

# Black-Listed Worlds
blacklisted-worlds:
  - "blacklisted_world_example"

# Bot names that are not allowed after color parsing/stripping.
# If a custom bot name matches one of these values, the bot falls back to the owner/display name.
bot-name-blacklist: []

# Auto Despawn Settings
auto-despawn:
  on-death: true
  on-quit: true
  on-teleport: true
  max-distance: 50.0

# Whether bot/NPC death messages should be broadcast to chat.
# ...
# More options continue in the generated plugin YAML file.
# Open plugins/<plugin-folder>/config.yml to review every setting.
# ...
Top-level keys

debug, license-key, database, color-format, blacklisted-worlds, bot-name-blacklist

Production handling

Back up this file, edit the generated copy under the plugin folder, then run the product reload command or restart for startup-level settings.

Messages & Language#

Translation and formatting guidance based on the product's bundled resources.

Message reload follows the product's reload command. Restart after jar, storage or license changes.

How to edit messages#

This product ships messages.yml. Edit the generated copy in the plugin folder, keep placeholders intact, then reload the plugin command or restart for startup-level changes.

Formatting#

<red>Error message</red>
&cLegacy color message
{player} {amount} {reason}
messages.yml short excerpt, not full file
Short YAML preview only. This block shows selected lines from messages.yml. The generated file contains more message keys than this docs excerpt.
# ...
# Short documentation excerpt from messages.yml.
# This is not the complete YAML file.
# Lines before and after this preview are omitted from the docs.
# ...
prefix: "&8[&6TrainingBot&8] &r"
no-permission: "&cYou don't have permission to do this."
spawned: "&aBot spawned!"
despawned: "&cBot despawned!"
invalid-number: "&cInvalid number!"
totem-set: "&aTotem limit set to &e<amount>&a."
teleported: "&aBot teleported to your location."
mode-changed: "&aMovement mode changed to &e<mode>&a."
only-players: "&cOnly players can use this command."
remove-usage: "&cUsage: /trainingbot remove <player>"
player-not-found: "&cPlayer not found."
bot-removed: "&aBot of &e<player> &aremoved."
enabled: "&aEnabled"
disabled: "&cDisabled"
attack-type-select: "&eLeft-Click &7to select"
attack-type-selected: "&aSelected"
attack-type-display:
  normal: "&fNormal"
  w-tap: "&6W-Tap"
  crit-spam: "&cCrit Spam"
  strafe: "&bStrafe"
  crystal-pvp: "&dCrystal PvP"
  nethpot: "&8Nethpot"
  diamondpot: "&bDiamondPot"
  beast: "&4Beast"
  ai-crystal-pvp: "&5AI Crystal PvP"
item-material-display:
  none: "&7None"
  netherite: "&8Netherite"
  diamond: "&bDiamond"
  iron: "&fIron"
  gold: "&6Gold"
  chainmail: "&7Chainmail"
  leather: "&6Leather"
# ...
# More options continue in the generated plugin YAML file.
# Open plugins/<plugin-folder>/messages.yml to review every setting.
# ...

GUI / Menus#

GUI cards describe the actual menus available in this product build.

Each card shows the configured menu title, inventory size, item count and detected actions when those values exist.

Admin Bot#

Staff editor for a selected bot profile, including behavior toggles, combat settings and profile management actions.

  • Configured title: Editing:
  • Size: 54 slots
  • Configured items: 12

Admin List#

Staff bot browser for opening, editing and managing saved bot profiles across pages.

  • Configured title: Admin Bot List | Page
  • Size: 54 slots
  • Configured items: 5

Attack Type#

Combat behavior selector that controls how a bot attacks and which PvP mode logic it uses.

  • Configured title: Select Attack Type
  • Size: 36 slots
  • Configured items: 11

Bot Inventory#

Equipment editor for saving the bot inventory, armor and combat items used by the active profile.

  • Configured title: Bot Inventory
  • Size: 54 slots
  • Configured items: 16

Bot#

Bot control panel for reach, movement, totems, shields, potion behavior and the main profile controls.

  • Configured title: Bot Control Panel
  • Size: 54 slots
  • Configured items: 15

Confirm Delete#

Deletion confirmation screen for preventing accidental removal of saved bot profiles.

  • Configured title: Confirm Deletion?
  • Size: 27 slots
  • Configured items: 3

CPvP Settings#

Crystal PvP settings menu for crystal-specific bot behavior such as placement, pressure, combat tuning, and Aim Noise (configurable jitter for realistic aiming).

  • Configured title: ⚔ Crystal PVP Settings
  • Size: 45 slots
  • Configured items: 15

Diamondpot Settings#

DiamondPot settings menu for potion-combat behavior, healing rhythm and mode-specific bot tuning.

  • Configured title: DiamondPot Settings
  • Size: 27 slots
  • Configured items: 7

Nethpot Settings#

NethPot settings menu for Netherite potion practice behavior and mode-specific profile values.

  • Configured title: ⚗ Nethpot Settings
  • Size: 27 slots
  • Configured items: 7

Potions#

Potion loadout menu for selecting which potion effects or potion items the bot profile should use.

  • Configured title: §8Set the Potions
  • Size: 45 slots
  • Configured items: 9

Preset#

Admin preset menu for applying saved bot templates instead of rebuilding every profile by hand.

  • Configured title: Admin Presets
  • Size: 45 slots
  • Configured items: 5

Profile Select#

Profile selector used to choose which saved bot profile will be edited or spawned.

  • Configured title: Select a Profile
  • Size: 27 slots
  • Configured items: 3

Profile Settings#

Profile settings menu for saved bot metadata, difficulty and reusable profile options.

  • Configured title: Profile Settings
  • Size: 45 slots
  • Configured items: 6

Developer API#

Integrate TrainingBot into your own plugins using the public API surface.

Access the API via TrainingBot.getInstance().getApi() or through the Bukkit Services Manager.
Bot Session Management Methods
spawnBot(Player owner, String profile, Location loc)Method
Return

BotSession

Description

Spawns a bot for the specified player using a saved profile.

destroyBot(Player owner)Method
Return

boolean

Description

Despawns and removes the bot session for the player.

isBotSpawned(Player owner)Method
Return

boolean

Description

Checks if the player currently has an active bot session.

Combat & Targeting Methods
setBotTarget(Player owner, LivingEntity target)Method
Return

void

Description

Forces the bot to target a specific entity.

setMovementMode(Player owner, MovementMode mode)Method
Return

void

Description

Changes the bot's movement logic (STATIONARY, FOLLOW, etc).

Profiles Methods
applyGlobalProfile(Player owner, String preset)Method
Return

void

Description

Applies a global admin preset to the player's active bot.

Storage#

Storage docs explain YAML, SQLite, MySQL, MariaDB and backup expectations when supported.

Always back up before changing storage type or updating a production server.

Storage recommendation#

TrainingBot config exposes SQLITE and MYSQL under database.method, while profiles.yml stores bot profile data.

Backup checklist#

  • Stop the server before copying live flat files.
  • Export SQL databases before updates.
  • Keep plugin version and server version in backup notes.
  • Test migration on a copy first.

Integrations#

Each integration explains purpose, required/optional status, setup steps and troubleshooting.

Soft hooks load after the dependency is available through Bukkit's plugin manager.
Citizens Required

Purpose: Provides NPC entities used by bot or combat punishment workflows.

Troubleshooting: If NPCs or bots fail, check Citizens startup errors, skin fetch warnings, disabled worlds and pathfinder restrictions.

  1. Install Citizens before starting the server.
  2. Confirm Citizens loads without NPC registry errors.
  3. Enable the feature that uses NPCs, bots, corpses or combat entities.
  4. Spawn or trigger one test entity and check console for skin, pathfinder or trait errors.
EventPractice Optional hook

Purpose: Connects this product to the practice and bot training ecosystem.

Troubleshooting: If queues or duels do not bridge, confirm the arena/kit exists and both plugins agree on the same mode/profile names.

  1. Install EventPractice and confirm arenas, kits and queues load correctly.
  2. Enable the practice/bot duel bridge in the relevant config file.
  3. Use a test queue, duel or arena flow to confirm both plugins exchange state.
  4. Check that match cleanup works after the integration flow ends.
ONNX Runtime Runtime library

Purpose: Provides the runtime layer used by AI-driven bot behavior and combat inference.

Troubleshooting: If bots do not fight correctly, test the profile directly in TrainingBot before testing the external bridge.

  1. Install TrainingBot and its runtime requirements when bot fights are used.
  2. Create at least one saved bot profile and kit.
  3. Enable the hook from the practice or combat plugin config.
  4. Start one bot duel or bot spawn test and verify movement, attacks and cleanup.

Common Setups#

Ready-to-follow scenarios reduce support tickets and make the product easier to configure.

Tune durations, limits, prices and permissions with the YAML files above.

CrystalPvP Bot Setup#

Use stricter cooldowns, staff visibility, abuse protection and clear player feedback for high-conflict gameplay.

Nethpot Bot Setup#

Create profiles or kits, verify arenas, test matchmaking, and record the exact player flow staff should use.

Melee Practice Setup#

Create profiles or kits, verify arenas, test matchmaking, and record the exact player flow staff should use.

Beginner Training Setup#

Use conservative defaults, SQLite or simple file storage, readable messages and relaxed limits for community servers.

Advanced Training Setup#

Create profiles or kits, verify arenas, test matchmaking, and record the exact player flow staff should use.

Troubleshooting#

Start with console logs, config diffs, plugin version and reproduction steps.

The first error in console is usually more useful than repeated follow-up errors.
Bot does not spawn issue

Confirm Citizens loads first, the target world is enabled and the bot profile has a valid spawn location, skin and equipment set.

Bot does not attack issue

Check combat mode, target selection rules, Citizens navigation, disabled worlds and whether the bot is in the same arena/world as the target.

Bot movement looks wrong issue

Tune strafe, speed and follow distance values for the selected profile. Also confirm the arena floor is pathfinder-friendly and not blocked by region flags.

Crystal bot does not place crystals issue

Verify the profile uses a crystal-capable mode, has crystals/obsidian configured and is running in a world where end crystals can be placed.

Kit is not saved issue

Use the save command/menu after equipping the bot, then verify the profile YAML updates on disk. Check file permissions if it reverts after restart.

Profile does not load issue

Check profile name casing, YAML indentation and required fields such as mode, kit and difficulty. Remove broken partial profiles and resave from the editor.

FAQ#

Short answers for common buyer and staff questions.

Does TrainingBot support Folia?#

Yes. TrainingBot includes a region-aware scheduler that detects Folia at runtime and delegates tasks to the appropriate region or entity scheduler.

Does it support Bedrock players?#

Yes. v1.4.0 introduced GUI optimizations for Bedrock Edition players connecting through Geyser and Floodgate.

Does it support old Minecraft versions?#

The checked-out source declares plugin API baseline 1.21 and compiles to Java 21 bytecode. The POM references Paper API build 26.3.207; these values do not confirm the exact Minecraft server releases supported by a published binary.

Does it require MySQL?#

TrainingBot supports both SQLITE and MYSQL. Profile data is also backed up to YAML files.

Can I edit all messages?#

Yes. Edit messages.yml and reload or restart according to the setting changed.

Changelog#

Product release notes grouped by version. Major public changes are written for buyers and server owners, not as raw commit logs.

Historical release notes below are retained as published. The local source checkout is version 1.7.3, targets Java 21 bytecode, references Paper API build 26.3.207 and declares plugin API 1.21; verify server compatibility against the binary being installed.

v1.4.0#

Minecraft 26.1.2 and Quality of Life update.

Added
  • Full support for Minecraft 26.1.2 (Requires Java 25).
  • Added Aim Noise settings in CPvP menu for more human-like aiming jitter.
  • Initial Bedrock GUI optimizations for Geyser/Floodgate users.
Changed
  • Optimized Folia region-aware scheduling for combat tasks.
  • Improved human-like acceleration and movement patterns.
Fixed
  • Fixed NMS reflection issues on newer Minecraft builds.
  • Optimized NPC visibility packets for high-population lobbies.

v1.2.1#

Combat mode and movement update.

Added
  • Added NethPot attack type support.
  • Added Crystal PvP attack mode work for advanced training profiles.
  • Added nametag and strafe attack type improvements.
Changed
  • Updated bot command flow and runtime settings for the new combat modes.
Fixed
  • Fixed strafe behavior issues found during combat profile testing.
  • Fixed message issues and menu item disable handling with slot -1.

v1.1.0#

Attack type foundation release.

Added
  • Added solid attack-type support for bot profiles.
  • Added bot settings data model support.
Changed
  • Updated bot command handling and profile data flow.
  • Improved player data handling used by training sessions.

v1.0.4#

Compatibility and admin menu update.

Added
  • Added Minecraft 1.21.11 support.
  • Added delay handling for shield animations so Citizens can update skins correctly.
Changed
  • Optimized bot runtime code and NPC manager behavior.
  • Updated admin menu behavior for bot item rendering.
Fixed
  • Fixed admin menu issue where bot items rendered as the same player head.

v1.0.3#

Bot behavior and config update.

Added
  • Added collidable option for bot behavior.
  • Added auto-jump option to the config.
Changed
  • Optimized bot listener and NPC manager logic.
Fixed
  • Fixed armor update issues.
  • Fixed shield break animation.

Support#

Send enough information to reproduce the issue.

Join Discorddiscord.gg/fANhQcyA7XInclude logs, config snippets and exact steps. Screenshots alone are not enough for config or database issues.

Before asking for support#

  • Test on the latest available plugin version.
  • Check server version and Java version.
  • Temporarily remove unrelated plugins when debugging conflicts.
  • Attach changed YAML files when config is involved.
Plugin: TrainingBot
Plugin version:
Server version:
Java version:
Server software:
Database type:
Installed hooks:
Error log:
Steps to reproduce:
Expected behavior:
Screenshots/video: