# User Guide Contains all the information relating to running the BattleTracker plugin. # Plugin Overview **BattleTracker is a standalone plugin that tracks PVP & PVE statistics along with a suite of combat features to enhance server gameplay.** BattleTracker tracks player statistics for both PVP and PVE combat. It also comes with a full suite of customizable features, such as death messages, combat logging, damage indicators and more. It also serves as the companion to [BattleArena](https://modrinth.com/plugin/battlearena), and handles keeping track of arena and competition statistics. ## Features[](https://github.com/BattlePlugins/BattleTracker/#features) ### PVP and PVE Records[](https://github.com/BattlePlugins/BattleTracker/#pvp-and-pve-records) One of the core features of BattleTracker is its robust tracking system for PVP and PVE statistics. BattleTracker tracks a variety of statistics including kills, deaths, killstreaks, and more. These statistics are saved in MySQL or SQLite, allowing them to be shared across Minecraft servers, or accessed by web applications. ### Leaderboards[](https://github.com/BattlePlugins/BattleTracker/#leaderboards) Another feature BattleTracker includes is a leaderboard system that allows players to view the top players on the server based on various statistics. ### Death Messages[](https://github.com/BattlePlugins/BattleTracker/#death-messages) BattleTracker provides customizable death messages that can be displayed to players when they are killed in PVP or PVE combat. These are easily configurable for each tracker type, and can be customized to fit the theme of your server. ### Damage Recap[](https://github.com/BattlePlugins/BattleTracker/#damage-recap) BattleTracker also includes a damage recap feature that displays a summary of the damage dealt and received by a player during combat. This can be summarized in multiple ways, such as which item dealt the most damage, a breakdown of players that dealt damage, or all the types of damage a player received. ### Combat Logging[](https://github.com/BattlePlugins/BattleTracker/#combat-logging) BattleTracker includes a combat logging feature that places players "in combat" when they attack another player. If they log out, they will be killed and their attacker will receive credit for the kill. ### Damage Indicators[](https://github.com/BattlePlugins/BattleTracker/#damage-indicators) Inside BattleTracker, there is also support for damage indicators, which show to a player how much damage they inflicted on another player or entity. # Installation ### Requirements - A Paper server (or other derivative) running 1.19.4 or above ### Downloading 1. Download the [BattleTracker](https://modrinth.com/plugin/battletracker/versions) plugin 2. Stop your server and place the plugins in your plugins folder 3. Start the server and BattleTracker will load # Features Documentation for all the features that BattleTracker includes. # PVP and PVE Trackers One of the core features of BattleTracker is its robust tracking system for PVP and PVE statistics. BattleTracker tracks a variety of statistics including kills, deaths, killstreaks, and more. These statistics are saved in MySQL or SQLite, allowing them to be shared across Minecraft servers, or accessed by web applications. ### Configuration By default, BattleTracker has support for both PVP and PVE tracking. These configurations can be found in the **plugins/BattleTracker/trackers/pvp.yml** and **plugins/BattleTracker/trackers/pve.yml** YML files respectively. #### Recaps By default, each tracker supports recaps, which recaps information about when a player took damage. This also includes information such as a player's inventory or armor at the time of the recap. Options: - **enabled** (default: true) - Whether recaps are enabled. - **display-content** (default: armor) - What is displayed when a recap is viewed. - **all:** Shows a player's full inventory and armor at the time of their death - **armor:** Shows a player's armor at the time of their death - **recap:** Only includes the damage recap of a player, excluding armor and inventory - **hover-recap** (default: true) - Whether a small recap should be shown when a death message is hovered over #### Tracked Statistics Which statistics are tracked by a tracker. The options available are **pvp, pve** and **world**. By default, BattleTracker splits this into two trackers, with **PVP** tracking exclusively PVP data, and **PVE** tracking both PVE and world data. #### Calculator Which calculator is used to rank players in leaderboards. By default, this is **elo**. As of BattleTracker 4.0.0, only **elo** is supported. #### Killstreaks Whether the killstreak feature is enabled. A killstreak occurs when a player kills a certain number of players in a row without dying. Options: - **enabled** (default: true in pvp.yml; false in pve.yml) - Whether killstreaks are enabled. - **minimum-kills** (default: 5) - The minimum number of kills before it is announced in chat that a player is on a killstreak - **killstreak-message-interval** (default: 5) - The interval in which killstreak messages are broadcasted. With the default value of 5, a killstreak message will only be broadcasted for a multiple of 5 kills (i.e. 5, 10, 15, 20, etc.) - **audience** (default: global) - The audience that the killstreak message will be broadcasted to - **global:** All players on the server - **world:** Only players in the same world - **local:** Only the player and the target - **arena:** Only players in the same arena (requires [BattleArena](https://modrinth.com/plugin/battlearena)) - **messages** - The messages that will be sent when a player is on a killstreak. Allows for configuring custom killstreak messages once a certain milestone is hit (i.e. at 20 kills, sending an "unstoppable killstreak" message) #### Rampage Whether the rampage feature is enabled. A rampage occurs when a player kills a certain number of players in a short amount of time. Options: - **enabled** (default: true in pvp.yml; false in pve.yml) - Whether rampages are enabled. - **rampage-time** (default: 10) - The maximum duration between kills in order for a player to be marked as being on a rampage - **audience** (default: global) - The audience that the rampage message will be broadcasted to - **global:** All players on the server - **world:** Only players in the same world - **local:** Only the player and the target - **arena:** Only players in the same arena (requires [BattleArena](https://modrinth.com/plugin/battlearena)) - **messages** - The messages that will be sent when a player is on a rampage. Allows for configuring custom rampage messages once a certain milestone is hit (i.e. at a rampage of 5, sending an "unstoppable rampage" message) # Death Messages BattleTracker provides customizable death messages that can be displayed to players when they are killed in PVP or PVE combat. These are easily configurable for each tracker type, and can be customized to fit the theme of your server. ### Configuration #### Player Player death messages are death messages that occur when a player dies due to another player. By default, these come pre-configured in the **pvp.yml**, and are configured in conjunction with the item type that is used to kill the player. Additionally, Minecraft [Item Tags](https://minecraft.wiki/w/Tag#Item_tags_2) are also able to be used, allowing you to configure death messages for similar types of items, denoted by a pound/hashtag (#) symbol (i.e. #axes for all axes, #pickaxes for all pickaxes, etc.) Variables: - **%player%** - The player which was responsible for the kill. - **%target%** - The player who died. - **%item%** - The name of the item that was used to kill the player. #### World World death messages are death messages that occur when a player dies due to a world event, such as suffocating in sand, burning in lava, or anything that does not involve a death by an entity or player. By default, these come pre-configured in the **pve.yml**, and can be set for any [Damage Cause](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html). Variables: - **%player%** - The name of the player that died. #### Entity Entity death messages are death messages that occur when a player is killed by an entity. This does not include players, or world events. By default, these come pre-configured in the **pve.yml**, and can be set for any [Minecraft Entity](https://minecraft.wiki/w/Entity), using it's official identifier. Variables: - **%player%** - The name of the player that died. # Damage Recaps BattleTracker also includes a damage recap feature that displays a summary of the damage dealt and received by a player during combat. This can be summarized in multiple ways, such as which item dealt the most damage, a breakdown of players that dealt damage, or all the types of damage a player received. By default, BattleTracker allows for recapping damage based on players, entities, items and cause. The image below demonstrates how this is shown to players: ![](https://cdn.modrinth.com/data/cached_images/4b22a886a0a012ed8c1e43c0543e4b2cb8e2e3d1.png) ### Configuration Configuration for damage recaps can be found in the [PVP and PVE Tracker](https://docs.bplug.in/books/user-guide-UMJ/page/pvp-and-pve-trackers) configuration page. # Combat Logging BattleTracker includes a configurable combat logging feature that places players "in combat" when they attack another player. If they log out, they will be killed and their attacker will receive credit for the kill. ### Configuration The combat logging configuration can be found in the **plugins/BattleTracker/features/combat-log.yml** YML file. Options: - **enabled** (default: true) - Whether combat logging is enabled. - **disabled-worlds** (default: empty list) - The worlds combat logging is disabled in. - **combat-time** (default: 10) - How long a player will be tagged for combat once hit. - **combat-self** (default: false) - Whether a player will be placed in combat if they inflict damage on themselves. - **combat-entities** (default: true) - Whether a player will be marked as in combat when they hit an entity, or are attacked by an entity. - **combat-entities** (default: true) - Whether a player will be marked as in combat when they hit a player, or are attacked by a player. - **display-method** (default: action\_bar) - The type of message used to display to a player how long they have left in combat. - **action\_bar:** Displays in the action bar how much time a player has left in combat - **bossbar:** Displays in the bossbar how much time a player has left in combat - **chat:** Displays in the chat how much time a player has left in combat - **title:** Displays in the title how much time a player has left in combat - **subtitle:** Displays in the subtitle how much time a player has left in combat - **none:** No message will be displayed - **allow-permission-bypass** (default: false) - Whether having the "battletracker.combatlog.bypass" permission will exempt a player from being in combat. - **disabled-entities** Which entities will not mark a player as in combat when they are hit by them - **disabled-commands** The commands that are disabled when a player is in combat # Damage Indicators Inside BattleTracker, there is also toggleable damage indicators, which show to a player how much damage they inflicted on another player or entity. ### Configuration The combat logging configuration can be found in the **plugins/BattleTracker/features/damage-indicators.yml** YML file. Options: - **enabled** (default: true) - Whether damage indicators are enabled. - **disabled-worlds** (default: empty list) - The worlds damage indicators are disabled in. - **format** - The format of the damage indicator. The **%damage%** variable is used to display the damage dealt. # Commands ### Tracker Commands These are the commands present for any tracker. By default, these will include **/pvp** and **/pve**.
**Command** **Description**
/<tracker> top \[max\] View the top players of this tracker.
/<tracker> rank \[player\] View the rank of a player in a tracker.
/<tracker> versus <player> \[target\] Compare the stats of two different players.
/<tracker> recap \[player\] View the last damage recap of a player.
# Permissions
**Permission****Description**
battletracker.command.<tracker>.top Permission for the /<tracker> top command.
battletracker.command.<tracker>.rank Permission for the /<tracker> rank command.
battletracker.command.<tracker>.versus Permission for the /<tracker> versus command.
battletracker.command.<tracker>.recap Permission for the /<tracker> recap command.
battletracker.combatlog.<tracker>.bypass Whether a player will bypass the combat log (if enabled). Requires that **allow-permission-bypass** is enabled in the [Combat Log](https://docs.bplug.in/books/user-guide-UMJ/page/combat-logging) config.
# Plugin Integrations Integrations with third party plugins to extend BattleTracker functionality. # Placeholder API Within BattleTracker, there is support to display tracker info through a plugin called [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/). If you are unfamiliar with the plugin, it allows for you to show information with certain placeholders (e.g. %player\_name% will return the player name) in plugins that have support for PlaceholderAPI. An example usage of this is displaying your PVP kills through BattleTracker on a scoreboard through PlaceholderAPI. If you also have BattleArena installed, you can display tracker information from it too. An example usage of this is displaying the top players in arena. The support for these placeholders even extends to custom arena games you have created or even plugins that hook into BattleTracker directly for stats. ### Placeholders These are the placeholders for BattleTracker. They are split into two sections: player placeholders and rating placeholders. Player placeholders get information on the player that "sees" the placeholder. The rating placeholders get information about players for the rating you specify. #### Player Placeholders These placeholders show statistics for the player viewing the information. This information will look different to each player seeing it in-game. **<tracker>** below can be replaced with any tracker BattleTracker has registered (i.e. pvp, pve). - **%bt\_<tracker>\_kills%**: Displays the number of kills. - **%bt\_<tracker>\_losses%**: Displays the number of losses. - **%bt\_<tracker>\_ties%**: Displays the number of ties. - **%bt\_<tracker>\_streak%**: Displays the current streak. - **%bt\_<tracker>\_max\_streak%**: Displays the max streak. - **%bt\_<tracker>\_ranking%**: Displays the current ranking. - **%bt\_<tracker>\_max\_ranking%**: Displays the max ranking reached. - **%bt\_<tracker>\_rating%**: Displays the current rating. - **%bt\_<tracker>\_max\_rating%**: Displays the max rating reached. - **%bt\_<tracker>\_kd\_ratio%**: Displays the kills-to-deaths ratio. - **%bt\_<tracker>\_max\_kd\_ratio%**: Displays the max kills-to-death ratio. If you are using BattleArena, replace the tracker name with the name of your arena. #### Rating Placeholders These placeholders show statistics for the top players. The placeholder must be specified with a rating at the end. **<tracker>** below can be replaced with any tracker BattleTracker has registered (i.e. pvp, pve). **<rating>** below can be replaced with the rating you want to get placeholder information from. For example, `1` will get information from the #1 player on the leaderboard. - **%bt\_<tracker>\_top\_kills\_<rating>%**: Displays the number of kills. - **%bt\_<tracker>\_top\_losses\_<rating>%**: Displays the number of losses. - **%bt\_<tracker>\_top\_ties\_<rating>%**: Displays the number of ties. - **%bt\_<tracker>\_top\_streak\_<rating>%**: Displays the current streak. - **%bt\_<tracker>\_top\_max\_streak\_<rating>%**: Displays the max streak. - **%bt\_<tracker>\_top\_ranking\_<rating>%**: Displays the current ranking. - **%bt\_<tracker>\_top\_max\_ranking\_<rating>%**: Displays the max ranking reached. - **%bt\_<tracker>\_top\_rating\_<rating>%**: Displays the current rating. - **%bt\_<tracker>\_top\_max\_rating\_<rating>%**: Displays the max rating reached. - **%bt\_<tracker>\_top\_kd\_ratio\_<rating>%**: Displays the kills-to-deaths ratio. - **%bt\_<tracker>\_top\_max\_kd\_ratio\_<rating>%**: Displays the max kills-to-deaths ratio. Additionally, if you wish to get the name or UUID of the user that holds a certain rating, you can add **\_name** or **\_uuid** to the end of the placeholder (i.e. **%bt\_<tracker>\_top\_kills\_<rating>\_name%**). If you are using BattleArena, replace the tracker name with the name of your arena.