Bodyguard

Bodyguard

Adds loyal personal guards with configurable follow behaviour, combat modes, persistence, fake-player visuals, and optional Accolades reward support.

Bodyguard is a standalone Paper plugin that lets players spawn personal guards to follow them, keep a sensible escort position, and defend them from configured threats. It is built for servers that want practical companion protection without requiring a database, NMS code, or a full NPC system for normal mob guards.

Bodyguard works out of the box with YAML storage. SQLite, MySQL, and MariaDB are available for larger servers that want database-backed guard rosters.

Features

• Spawn configurable mob bodyguards such as wolves, iron golems, vindicators, pillagers, skeletons, and zombies.
• Optional fake-player bodyguard appearance through the NPCs plugin.
• Follow behaviour keeps guards near the owner in a configurable ring instead of standing inside them.
• Single guards can prefer a configurable side or rear escort slot.
• Combat modes include passive, defensive, aggressive, and stay.
• Defensive guards react when their owner is damaged.
• Defensive guards can react as soon as hostile or neutral mobs target the owner.
• Aggressive guards can seek nearby hostile mobs around the owner.
• Configurable targeting for hostile mobs, neutral mobs targeting the owner, and players.
• Creative and spectator players can be ignored.
• Friendly fire prevention is configurable.
• Forced close-range attacks help guards fight targets that vanilla mob AI would otherwise ignore.
• Bodyguards can be renamed, healed, recalled, dismissed, restored, saved, backed up, and inspected.
• Persistent records are saved for each guard, including owner, type, appearance, display type, name, mode, location, and suspended state.
• Configurable limits, world whitelist/blacklist, health values, equipment, names, collision, invulnerability, drops, sunlight burning protection, and storage behaviour.
• Storage status, audit output, backups, and manual saves help admins verify roster health.

Guard Types And Modes

Bodyguard supports normal mob companions by default. The default config includes:

• wolf
• iron_golem
• vindicator
• pillager
• skeleton
• zombie

Fake-player bodyguards can be spawned with player or fake_player when fake-player support is enabled. They use a hidden mob controller for Bodyguard's combat and ownership logic, while NPCs provides the visible fake-player body.

Bodyguard modes:

• PASSIVE follows the owner without seeking combat.
• DEFENSIVE attacks things that hurt or target the owner.
• AGGRESSIVE also seeks nearby hostile mobs.
• STAY keeps the guard at its current position.

Persistence

Bodyguard stores saved guard rosters so companions can survive restarts and owner logout handling.

Supported storage modes:

• YAML
• SQLITE
• MYSQL
• MARIADB

Bodyguards can be saved manually, backed up locally, restored near their owner, and audited with active count, saved count, appearance counts, mode counts, storage description, and storage health.

Storage And Security

• YAML storage is available for simple local setups.
• SQLite, MySQL, and MariaDB are available for larger servers.
• SQLite paths are kept inside the plugin data folder.
• Example MySQL and MariaDB URLs use certificate and hostname verification.
• JDBC credentials are handled by the shared storage settings and should not be placed in public diagnostics.
• Player targeting is disabled by default.
• Reward handling is indirect through Accolades and keeps Accolades' cooldowns, history, events, and reward controls.
• World filters can disable guards in creative, minigame, or other restricted worlds.
• Bodyguard stores player identity by UUID.
• Bodyguard does not use NMS, CraftBukkit internals, packet hacks, or version-fragile reflection for normal mob bodyguards.

Commands

Main command aliases:

• /bodyguard
• /bg

Common commands:

• /bodyguard help
• /bodyguard spawn [type] [name]
• /bodyguard list
• /bodyguard info <id|name>
• /bodyguard mode [id|name] <passive|defensive|aggressive|stay>
• /bodyguard rename <id|name> <new name>
• /bodyguard heal [id|name|all]
• /bodyguard recall [id|name|all]
• /bodyguard dismiss [id|name|all]
• /bodyguard restore
• /bodyguard status
• /bodyguard stats
• /bodyguard audit
• /bodyguard save
• /bodyguard backup
• /bodyguard reload

Permissions

Every permission defaults to operator access.

Grant all Bodyguard permissions:

• bodyguard.admin

Or assign individual permissions:

• bodyguard.command
• bodyguard.spawn
• bodyguard.dismiss
• bodyguard.recall
• bodyguard.mode
• bodyguard.rename
• bodyguard.heal
• bodyguard.restore
• bodyguard.save
• bodyguard.backup
• bodyguard.reload

Optional Integrations

Bodyguard works with other Thunder plugins while remaining fully usable on its own for normal mob companions.

• NPCs provides linked fake-player visuals for bodyguards. Bodyguard creates, moves, steps, locates, and removes linked fake-player NPCs in the bodyguard namespace without turning them into standalone /npcs records.
• NPCs underwater movement lets fake-player bodyguards follow owners through flooded caves by swimming down, across, and back up instead of being forced back to dry ground.
• Accolades receives Bodyguard protection and save moments through AccoladesApi#recordExternalAccolade(...), so guard defence can use Accolades announcements, cooldowns, Bukkit events, rewards, and history.
• StormEconomy can pay for Bodyguard protection or save moments indirectly when Accolades rewards are configured with StormEconomy installed. Bodyguard does not depend directly on StormEconomy.
• ThunderPerms can manage Bodyguard's standard Bukkit permission nodes when installed.
• Other plugins can use BodyguardApi through Bukkit services to inspect active bodyguards, player-owned bodyguards, persisted guard counts, storage description, and storage health.

These hooks are optional. If the other plugins are not installed, Bodyguard still supports normal mob guards, commands, YAML storage, combat behaviour, and admin tools.

Notes

Bodyguard is designed to provide useful player protection without becoming an uncontrolled combat or reward farm. The default configuration uses a one-guard limit, disabled player targeting, world filters, friendly-fire controls, recent threat tracking, Accolades cooldown delegation, and explicit restore settings to keep behaviour predictable on public servers.

Normal mob bodyguards do not require NPCs, Accolades, StormEconomy, ThunderPerms, WorldGuard, PlaceholderAPI, Vault, or a database.

Fake-player bodyguards require the companion NPCs plugin unless fallback mode is explicitly enabled.