⚔️ Combat Companions ⚔️



Create unlockable NPC companions for your players — fully customizable with Citizens + Sentinel integration. Players can unlock, manage, and summon companions through an intuitive GUI, using in-game currency.

Great for progression, perks, donor content, or just giving players something cool to show off.

Plugin GUI

Main Menu


Unlock Companions


Manage Companions


Video Tutorial




Recently featured in a Reddit thread with 2,000+ views — now actively gathering feedback from server owners.

Recently showcased in a YouTube Short that reached 1,000+ views!


✨ Key Features:

• Unlock companions using Vault-integrated in-game currency

• Fully control companion stats: health, damage, speed, equipment, entity type

• GUI interface for players to unlock, spawn, and manage companions

• Permission-based access for donor ranks or progression

• Designed for Spigot 1.19–1.21

Premium Version – Support Development and Unlock More

Looking to take your companions to the next level?

The full version of Combat Companions is available through my Discord!

Full version includes:

• ✅ Spartex AI v2.1 – an overhauled, superior AI system for your companions

• ✅ Automatic detection of melee vs ranged companions

• ✅ Companion spawn and teleport animations.

Every feature I release is built to genuinely improve your server — nothing less.


Discord:
Join the Discord to gain access to the full version of the plugin, give plugin recommendations, ask for support, raise any issues or just to be a member of the community!


Plugin Dependencies: Vault (and a compatible economy plugin), Citizens, Sentinel


If you like the plugin, please leave a rating — it helps massively.

Now, onto the guide...


Versions

The plugin is downloaded as a zip file with the plugin jar files in folders for each Spigot version.

Tutorial

Regular Player Usage
Regular players will have all of the plugin functionality within a GUI which can be displayed using the following command: /companions

There, they can unlock companions and spawn or despawn their unlocked companions.


Admin Usage
If you are not a server operator, please refer to the permissions section to see what permissions you will need to have in order to use the commands mentioned in this section.

Lets start by creating a new companion for it to then be available for purchase.

Start by entering the following command: /companions create TestCompanion

An NPC will be spawned at your location, this is the basic companion. You can equip the companion by right clicking on it with weapons and armor, or by using the citizens commands to equip an NPC. You can also use Citizens commands to change the entity type of the NPC. To unlock more customization, select the NPC using the Citizens plugin command: /npc sel. The spawned NPC already has the sentinel trait (from the Sentinels plugin) attached to it so you can modify most sentinel traits of the NPC now to change properties such as movement speed, or health. There are only a few exceptions which you should not modify, as they will be set to preconfigured values by the plugin regardless, those are the following:

• Range
• Chase Range
• Invincibility

If you want a color coded companion name, that will be configured at a later stage, so do not change the NPC name yet.

After you are done configuring the NPC attributes, you can save the created companion using the save command: /companions save. The NPC will now disappear.

The companion is nearly ready! At the moment the companion will have a default unlock and respawn price (configured in the general config), and the display name will not be color coded.

You can use the set command to change these properties. The available property names for this commands are the following:

• unlock_price
• respawn_price
• display_name

Lets first set the unlock price for this companion.

Enter the following command: /companions set TestCompanion unlock_price 150.

This sets the unlock price to be $150 of in-game currency. You can also set the respawn_price and display_name properties using the same command. For the display name property, you can enter a color coded name for your companion!

For players to be able to unlock this companion they will need the following permission: combatcompanions.companion.TestCompanion.

When that permission has been added to a permission group or player, they will now be able to view the companion in the Unlock Companions menu of the GUI

There are more commands which are listed and explained in the Commands section.


Commands

/companions - Displays the Combat Companions GUI, where you can manage and unlock companions.

/companions help - Display the commands and their functionality in-game.

/companions create <companion name> - Start the creation of a new companion.

/companions save - Save a companion after using the create command, to end the creation session.

/companions add <companion name> <player> - Add a companion to a player, bypassing the unlock price of the companion.

/companions remove <companion name> <player> - Removes a companion from a player, making it available for unlock again.

/companions edit <companion name> - Starts an edit session for a companion, use /companions save to save changes.

/companions delete <companion name> - Delete a companion from the game entirely.

/companions set <companion name> <property> <value> - Set a property to a specified value for an existing companion (the companion has to have been saved before this command can be used). Properties that are available are listed in the Admin Usage section.

/companions spawn <companion name> - Spawn one of your companions, bypassing the respawn price of the companion.

/companions reload - Load data from the configs into the plugin.

/companions list - Lists all created companion names and display names.


Permissions

combatcompanions.help - Provides access to the "/companions help" command.

combatcompanions.companions - Provides access to the "/companions" GUI command.

combatcompanions.create - Provides access to the "/companions create" and "/companions save" command.

combatcompanions.delete - Provides access to the "/companions delete" command.

combatcompanions.spawn - Provides access to the "/companions spawn" command, which bypasses the respawn price.

combatcompanions.add - Provides access to the "/companions add" command, to add a companion to a player, bypassing the unlock price.

combatcompanions.remove - Provides access to the "/companions remove" command to remove a companion from a player.

combatcompanions.edit - Provides access to the "/companions edit" command.

combatcompanions.companion.<companion name> - Allows player to unlock the companion with the name specified in this permission.

combatcompanions.reload - Provides access to the "/companions reload" command.

combatcompanions.allow.spawn.spam - Allows spam spawning companions in the Manage Companions GUI menu.

combatcompanions.list - Provides access to the "/companions list" command


Configurations

There are 3 configuration files used by this plugin:

• general.yml
• companions.yml
• player_data.yml

General Config:
The general config contains a few settings that can be changed to modify default values in-game, make sure to run the /companions reload command after any modification. Values that can be modified are:

• Sentinel respawn time: by default I set the respawn time to be forever, so that the NPC's do not respawn automatically, I would recommend leaving this value the default.
• Default unlock price: this is the unlock price that is set for newly created companions before you modify it using the "set" commands.
• Default unlock price: this is the respawn price that is set for newly created companions before you modify it using the "set" commands.
• Player companion respawn time: This is the amount of seconds the players will have to wait after despawning a companion before being able to spawn it again.

Companions Config:
This config contains information about your created companions, such as the display name, their unlock and respawn prices as well as the ID reference to the citizens NPC they are based upon. I would not recommend changing the NPC ID as this can lead to issues, however the other properties can be modified and when the plugin is reloaded they will be reflected in game.


Player Data Config:
This config should not be tampered with, and could break the plugin functionality if done incorrectly. You will see values such as number of companions and maximum number of companions, however these do not take affect in the game and are planned to be used in future releases.


If you experience any other issues please let me know in the Discord and we can communicate to fix them together!

I hope you enjoy using this plugin and it adds a nice feature to your server!