Combat Companions

This plugin allows you to create custom NPC companions which are then available for players to unlock on the server using in-game currency! Companions can be configured using many attributes, including but not limited to health, damage, movement speed, the equipment they use and the entity they are (e.g. Skeleton). This can be an additional progression mechanic for your server, or a fun plugin.


Join the Discord to 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


A lot of time and effort has gone into creating this plugin, if you can give a small donation, it would go a long way in supporting me and allowing me to spend more time on this plugin and more in the future. That way, we can make the Minecraft experience that bit better for everyone. Either way, I hope you enjoy my contribution to the community!

Feel free to start any discussions on here or on the discord. If you do enjoy the plugin, please leave a rating if you can, would help me out a great deal.

Now, onto the guide...


How to use




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 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.


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.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.


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:

• 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.

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.


Known limitations
The are some known limitations of the plugin, for which updates are ongoing and will be resolved in the near future:

• NPC created by the latest citizens plugin seem to have very low movement speed by default (at least in my experience), this seems to be a problem in the Citizens plugin. You can fix this by modifying the companions speed during creation using the Sentinel trait (from the Sentinel plugin). If you select the companion NPC during creation and enter the following command: /sentinel speed 5 it seems to give the NPC a more reasonable movement speed.

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!