diff --git a/README.md b/README.md index ef63c92..ade51d1 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,4 @@ -## Welcome to GitHub Pages +# Statz wiki -You can use the [editor on GitHub](https://github.com/Staartvin/Statz/edit/master/README.md) to maintain and preview the content for your website in Markdown files. +Statz is a Bukkit/Spigot plugin for storing data about players. See this [wiki](https://statz.staartvin.com/) for more information! -Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. - -### Markdown - -Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for - -```markdown -Syntax highlighted code block - -# Header 1 -## Header 2 -### Header 3 - -- Bulleted -- List - -1. Numbered -2. List - -**Bold** and _Italic_ and `Code` text - -[Link](url) and ![Image](src) -``` - -For more details see [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). - -### Jekyll Themes - -Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/Staartvin/Statz/settings). The name of this theme is saved in the Jekyll `_config.yml` configuration file. - -### Support or Contact - -Having trouble with Pages? Check out our [documentation](https://help.github.com/categories/github-pages-basics/) or [contact support](https://github.com/contact) and we’ll help you sort it out. diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..27b27cc --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,20 @@ +# Table of contents + +* [Statz wiki](README.md) +* [Commands & Permissions](commands-permissions.md) +* [FAQ](faq.md) + +## Developers + +* [Developer's API](developers/api.md) +* [Development builds](http://staartvin.com:8080/job/Statz/) + +## Data + +* [How does Statz store its data?](data/how-does-statz-store-its-data.md) +* [How to disable statistics?](data/how-to-disable-statistics.md) + +## Placeholders + +* [Placeholders](placeholders/placeholders.md) + diff --git a/commands-permissions.md b/commands-permissions.md new file mode 100644 index 0000000..443c67c --- /dev/null +++ b/commands-permissions.md @@ -0,0 +1,24 @@ +# Commands & Permissions + +## Commands + +Parentheses denote optional arguments, like '\(' and '\)'. Triangle brackets \('<' and '>'\) denote required arguments. + +* **/statz help** - Show a list of commands that can be performed. +* **/statz list \(player\) \(stat name\)** - Show a list of stats that are stored for a player. You can click on a stat to get detailed information about that specific stat. +* **/statz hooks** - Shows a list of plugins that Statz is currently hooked into. +* **/statz transfer** - Transfer data from SQLite database to your MySQL database. This command can come in handy when you have old data after your switch from SQLite to MySQL. +* **/statz transfer reverse** - Transfer data the other way around: from MySQL to SQLite database. +* **/statz migrate** - Migrate data from Stats 3 to Statz. Stats 3 has to be running to perform this command. +* **/statz purge** - Remove old players from the database that have not logged in since x time. + +## Permissions + +* _`statz.list.self`_ - This permission is automatically given to all players. It allows a player to perform **/statz list**. +* _`statz.list.others`_ - This permission is only given to OP. It allows a player to check the statistics of other players. +* _`statz.help`_ - This permission allows players to perform **/statz help** and is automatically awarded to all players. +* _`statz.hooks`_ - To be able to perform **/statz hooks**, you'll need this permission. By default, only OP's have this permission. +* _`statz.transfer.sqlite`_ - To be able to perform transfers with **/statz transfer**, you'll need this command. By default, only OP's get this permission. +* _`statz.migrate`_ - This permission allows players to perform /statz migrate. +* _`statz.purge`_ - This permission allows players to purge players from the database. + diff --git a/data/how-does-statz-store-its-data.md b/data/how-does-statz-store-its-data.md new file mode 100644 index 0000000..822af00 --- /dev/null +++ b/data/how-does-statz-store-its-data.md @@ -0,0 +1,269 @@ +# How does Statz store its data? + +Statz records quite a bit of data, as can be seen [here](https://www.spigotmc.org/resources/statz.25969/). To make sure this data is properly stored and easy and efficient to retrieve, Statz uses either [SQLite](https://www.sqlite.org/) or [MySQL](https://www.mysql.com/) \(depending on the choice of the configuration options\). Since this page is not meant for an introductory course on SQL and database, I'll provide you a link to a tutorial on the internet: [http://www.sqlcourse.com/intro.html](http://www.sqlcourse.com/intro.html). + +Table of contents: + +* [Data stored in Statz's database](how-does-statz-store-its-data.md#data-stored-in-statzs-database) +* [Data not stored in Statz's database, but still retrievable by Statz](how-does-statz-store-its-data.md#data-not-stored-in-statzs-database-but-retrievable-by-statz) + +## Data stored in Statz's database + +Statz records a multitude of different datasets and arranges them in tables. For example, Statz has a table called 'statz_distance\_travelled' that contains all info about the ways players travel. Every table will be discussed here. Every table consists of columns that hold specific info about an action. The identifier and info stored by each column vary over tables, but every table has at least an \_id_ column that will track the changes across the table. + +### arrows\_shot + +This table holds info about arrows that were shot by players. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _forceShot_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of arrows a player has fired. +The WORLD column stores on what world the arrow was fired. +The FORCESHOT column stores in with what force the arrow was shot. This can be anything from 0.0 to 1.0. + +### blocks\_broken + +This table holds all info about the blocks a player has broken. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _typeid_ and _datavalue_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of blocks that were broken for a specific block. +The WORLD column stores on what world the blocks were broken. + +Penultimately, the TYPEID column stores the id of the block that was broken. For example, a torch has id 50 \(for reference, see [http://www.minecraftwiki.net/images/8/8c/DataValuesBeta.png](http://www.minecraftwiki.net/images/8/8c/DataValuesBeta.png)\). + +Lastly, the DATAVALUE column stores the extra data that is sometimes associated with the broken block. For example, a torch does not have a data value, but wool \(id 35\) has a data value for each color \(white wool has data value 0, while black wool has data value 15\). + +### blocks\_placed + +This table has exactly the same columns as _**statz\_blocks\_broken**_, but is associated with placed blocks instead of broken ones. + +### buckets\_emptied + +This table holds info about players that emptied buckets. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_ The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the amount of buckets a player has emptied. +The WORLD column stores on what world the bucket was emptied by the player. + +### buckets\_filled + +This table stores exactly the same things as **buckets\_emptied**, but it is associated with buckets that were filled instead of emptied. + +### commands\_performed + +This table stores the commands that were performed by players. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _command_ and _arguments_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a command was performed. The WORLD column stores on what world the command was performed. The COMMAND column stores what command was performed. Together with the ARGUMENTS column, the whole argument syntax is provided. The COMMAND column only stores the first word \(or letter\) and the others words \(arguments/parameters\) are stored in the ARGUMENTS column. For example, when a player performs **/statz check Staartvin**, the COMMAND column will be filled by '/statz' and the ARGUMENTS column will store 'check Staartvin'. + +### damage\_taken + +This table holds info about players that took damage in some way or form. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _cause_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the amount of damage a player has taken. +The WORLD column stores on what world the damage was taken by the player. +The CAUSE column stores in what way the player was hurt. It can take any of the following forms: [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html). + +### deaths + +The deaths table is used to store info regarding the deaths of any player on the server. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores how many times a player has died. The WORLD column stores on what world the player has died. + +### distance\_travelled + +This table consists of data used to track the movement of players. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _moveType_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores how far a player has travelled. The WORLD column stores on what world the player travelled. The MOVETYPE column stores in what way the player travelled. This can either be: + +* BOAT +* FLY +* MINECART +* PIG +* PIG IN MINECART +* HORSE +* HORSE IN MINECART +* FLY WITH ELYTRA + +### eggs\_thrown + +This table holds info about players that threw eggs. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of eggs a player has thrown. The WORLD column stores on what world the egg was thrown. + +### entered\_beds + +This table stores when a player went to sleep. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player went to bed. The WORLD column stores on what world the player went to sleep. + +### food\_eaten + +This table holds info about what players have eaten. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _foodEaten_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has eaten a specific food item. The WORLD column stores on what world the food was omnomnom'd. The FOODEATEN column stores what food item was digested. + +### items\_caught + +This table holds info about players that caught some item while fishing. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _caught_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player caught a specific item. The WORLD column stores on what world the item was caught. The CAUGHT column stores what item was caught. \(A written book, a certain fish species, an old bottle of liquor, an old boot, etc.\) + +### items\_crafted + +This table holds info about players that crafted something. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player crafted a specific item. The WORLD column stores on what world the item was crafted. The ITEM column stores what was exactly crafted. + +### items\_dropped + +This table holds info about players that dropped something. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player dropped a specific item. The WORLD column stores on what world the item was dropped. The ITEM column stores what was exactly dropped. + +### items\_picked\_up + +This table holds info about players that picked up something. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player picked up a specific item. The WORLD column stores on what world the item was picked up. The ITEM column stores what was exactly picked up. + +### joins + +This table holds info about players that joined the server. It has 2 columns \(excluding the id column\): _uuid_ and _value_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has joined the server. + +### kills\_mobs + +This table holds info about players that killed a mob. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _mob_ and _weapon_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player killed a specific mob. The WORLD column stores on what world the mob was killed. The MOB column stores what mob was killed by the player. the WEAPON column stores what weapon was used to kill the mob. + +### kills\_players + +This table holds info about players that killed other players. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _playerKilled_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player killed another player. The WORLD column stores on what world the other player was killed. The MOB column stores what other player was killed by the player. + +### players + +This table holds info about the name and UUID of a player. It has 2 columns \(excluding the id column\): _uuid_ and _playerName_. +The UUID column stores, coincidentally, the UUID of the player. +The PLAYERNAME column stores the name of the player \(with a specific UUID\) when it joined the server. + +### teleports + +This table holds info about players that teleported. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _destWorld_ and _cause_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has teleported. The WORLD column stores what world the player teleported from. The DESTWORLD column stores what world the player teleported to. The CAUSE column stores what the cause was of the teleport. It the cause was unknown, UNKNOWN will be provided as cause. + +### time\_played + +This table holds info about the time players played on the server. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of minutes a player has been online. The WORLD column stores on what world the player has played for x minutes. + +### times\_kicked + +This table holds info about players that were kicked. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _reason_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has been kicked. The WORLD column stores what world the player was kicked. The REASON column stores what the specified reason was for the kick. If no reason was provided by the 'kicker', the reason will be 'Kicked from server.'. + +### times\_shorn + +This table holds info about players that have shorn sheep. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has shorn a sheep. The WORLD column stores on what world the player has shorn a sheep. + +### tools\_broken + +This table holds info about players that broke their tools. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has broken a type of tool. The WORLD column stores on what world the player has broken the tool. The ITEM column stores what tool was broken. + +### villager\_trades + +This table holds info about players that traded with villagers. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _trade_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has traded with a villager. The WORLD column stores on what world the player has performed the traded. The TRADE column stores what item the player received from the villager. + +### votes + +This table holds info about players that voted via Votifier or NuVotifier. It has 2 columns \(excluding the id column\): _uuid_ and _value_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has voted for the server. + +### worlds\_changed + +This table holds info about players that changed worlds \(via portals or commands\). It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _destWorld_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has switched worlds. The WORLD column stores from what world the player switched. The DESTWORLD column stores to what world the player switched. + +### xp\_gained + +This table holds info about players that gained exp. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the amount of xp that was gained. The WORLD column stores on what world the player gained xp. + +## Data not stored in Statz's database, but retrievable by Statz + +Besides storing a lot of information of players, Statz also manages data connection between other third-party plugins. + +#### MCMMO + +Statz tracks the level of each individual skill for every player and their total power level. + +#### AcidIsland + +Statz tracks island level of each player. + +#### ASkyBlock + +Much like AcidIsland, Statz tracks island level of each player. + +#### AFKTerminator + +Statz can check whether a player is AFK according to AFKTerminator + +#### EssentialsX + +Statz tracks whether a player is AFK \(according to EssentialsX\) and the \(estimated\) geo-location of their IP. + +#### Factions + +Statz can track the faction power of each player in a faction. + +#### Jobs + +Statz tracks multiple things: + +* Current points in a job +* Total points across all jobs +* Current XP in a current job +* Current level of a specific job + +#### OnTime + +Statz tracks play time of a player. + +#### RoyalCommands + +Statz can track whether a player is AFK. + +#### Stats 3 + +Statz can track all data of Stats 3 and also import data from Stats 3 \(see **/statz migrate**\). + +#### UltimateCore + +Statz tracks whether players are AFK. + +#### Vault + +Statz uses Vault to connect to permissions plugins and economy plugins, hence it can check for permissions and for money of a player. + +#### WorldGuard + +Statz can track in what region a player currently resides + +#### GriefPrevention + +Statz tracks a few things: + +* Number of claims of a player +* Number of claimed blocks of a player +* Number of remaining blocks a player can still claim +* Number of bonus blocks a player is allowed to claim + diff --git a/data/how-to-disable-statistics.md b/data/how-to-disable-statistics.md new file mode 100644 index 0000000..d367608 --- /dev/null +++ b/data/how-to-disable-statistics.md @@ -0,0 +1,21 @@ +# How to disable statistics? + +## What is it and why is it useful? + +The `disabled-stats.yml` allows you to disable any statistic in under specific circumstances. For example, you can disable the tracking of kills in a certain _WorldGuard_ arena or in a _GriefPrevention_ claim. As of now, these 'scenarios' are supported: + +* WorldGuard regions: disable a statistic in a WorldGuard region +* GriefPrevention claims: disable a statistic in the claim of any user. + +For more info on how to set this up, read on! + +## How to configure the file? + +To configure the disabled-stats.yml, you can use any file editor. Each statistic can be specified only once, but for more than one scenario's simultaneously. Let's take a look at a sample file: + +![Example of config file](https://i.imgur.com/h5ibohD.png) + +The image shows an example of how you can define WorldGuard regions and GriefPrevention claims. A WorldGuard region needs a region name, so Statz can check whether the player is in that region. The GriefPrevention claim needs a UUID of a player to check whether a random player is in the claim of the player the UUID corresponds to. + +You can see that the DISTANCE\_TRAVELLED stat will not be updated whenever a player is in a WorldGuard region called 'TestRegion' or 'Lala'. Similarly, this stat will not be updated whenever a player is in the GriefPrevention claim area that corresponds to one of those UUIDs. + diff --git a/developers/api.md b/developers/api.md new file mode 100644 index 0000000..05c6dfe --- /dev/null +++ b/developers/api.md @@ -0,0 +1,104 @@ +# Developer's API + +## Developer's API + +You're probably a developer and you want to know how Statz works and how to obtain data from Statz through its API. It's actually very easy. There are two methods that you can use to obtain info from players via Statz. + +### The Javadoc can be found [here](http://62.131.38.74:8080/job/Statz/javadoc/). + +First, you'll have to get the API class of Statz: + +```text +Plugin statz = Bukkit.getServer().getPluginManager().getPlugin("Statz"); + +if (statz != null && statz.isEnabled()) { +StatzAPI api = statz.getStatzAPI(); +} +``` + +Now, you can either choose to use the _getTotalOf\(\)_ method to obtain a total value of a stat. You can also get the total amount of a stat per world. Examples of using _getTotalOf\(\)_ are when you want to get the total number of votes of player, regardless of the world he voted on, or the total number of mob kills of a player on one specific world. + +To use this method, you'll need to provide a _PlayerStat_, a _UUID_ of the player and a specific _worldName_. If you don't care about the world, you can just leave this as **null**. **If Statz does not have the requested data, it will return null.** + +For example, to get the total amount of votes regardless of the world: + +```text +Double totalVotes = api.getTotalOf(PlayerStat.VOTES, UUID.fromString("c5f39a1d-3786-46a7-8953-d4efabf8880d"), null); +``` + +Another example, to get the total amount of mobs killed on the world 'Slaughterhouse': + +```text +Double totalMobsKilled = api.getTotalOf(PlayerStat.MOBS_KILLS, UUID.fromString("c5f39a1d-3786-46a7-8953-d4efabf8880d"), "Slaughterhouse"); +``` + +This is fun and all, but let's say you want to know the number of cows a player killed on world 'Lala'. Since this is a more specific request, you will need to use _getSpecificData\(\)_. This method is almost the same as _getTotalOf_ except that it allows you to specify certain conditions, called _RowRequirements_. You can have an unlimited amount of requirements, but the more requirements you have, the more specific a request is. Let's get back to our example. + +To obtain the amount of cows a player killed on world 'Lala', we'll have to run this code: + +```text +Double totalCowsKilled = api.getSpecificData(PlayerStat.MOBS_KILLS, UUID.fromString("c5f39a1d-3786-46a7-8953-d4efabf8880d"), new RowRequirement("mob", "COW"), new RowRequirement("world", "Lala")); +``` + +Each RowRequirement has two inputs; the first is the name of the column in the database \(you can find the different column names [here](https://github.com/Staartvin/Statz/wiki/How-does-Statz-record-its-data%3F)\), the second is the value it needs to have. The first RowRequirement says that we only want to count the data that has value _COW_ for column _mob_. The second RowRequirement tells Statz to only look for data that also has value _Lala_ for column _world_. Both these conditions need to be met. + +### Events fired by Statz + +As of Statz 1.3.3.2, Statz will fire an event \('[UpdateDataEvent](https://github.com/Staartvin/Statz/blob/master/src/me/staartvin/statz/api/events/UpdateDataEvent.java)'\) when data changes are sent to its database \(either SQLite or MySQL\). This event has two handy methods to obtain the newly updated data from the database without having to check every x seconds whether an update has occured. + +#### Method 1: getUpdatedInfo\(PlayerStat\) + +When the UpdateDataEvent is fired, it allows you, as a developer, to obtain the freshly updated data that has been sent to the database. To retrieve the data, you should create a listener, like normal, and listen for the UpdateDataEvent \(in me.staartvin.statz.api.events package\). The getUpdatedInfo\(\) method asks for one parameter, namely the stat type. Since it updates its database in bulk, it will send a lot of data simultaneously, hence you need a way to sort this data. You can retrieve updated data based on the PlayerStat. This method will return a list of PlayerInfo objects that might look confusing to you. Read on to learn more. + +#### PlayerInfo object + +The PlayerInfo class represents data from the database in almost the same way as a relational database would. Here is an example of the DISTANCE\_TRAVELLED table: + +![Example of database entries](https://cdn.pbrd.co/images/pXxSMl7di.png). + +This image shows 4 rows with a number of columns. In this table, there are 5 columns; **ID**, **UUID**, **VALUE**, **WORLD** and **MOVETYPE**. A PlayerInfo object represents this table in a more programmatical way. You can use getRow\(rowNumber\) to get a specific row number and getValue\(rowNumber, columnName\) to get the specific value of a certain column in a certain row. You can also use getTotalValue\(RowRequirements\) to get very detailed and specific information. + +Let's give an example. Let's assume Statz has just updated the FOOD\_EATEN statistic of a few players. We want to get the number of apples a player has eaten on world 'foodWorld'. We can perform the following code: + +```text +List playerInfos = event.getUpdatedInfo(PlayerStat.FOOD_EATEN); + + for (PlayerInfo playerInfo: playerInfos) { + // Incorrect PlayerInfo object. + if (playerInfo == null || !playerInfo.isValid()) { + return; + } + + double totalValue = playerInfo.getTotalValue(new RowRequirement("foodEaten", "APPLE"), new RowRequirement("world", "foodWorld")); + + System.out.println("Player " + playerInfo.getUUID() + " has now eaten " + totalValue + " apples!"); + } +``` + +Every statistic has its own table and so I appeal to you to see the structure of each table of every statistic [here](https://github.com/Staartvin/Statz/wiki/How-does-Statz-record-its-data%3F#data-stored-in-statzs-database). + +#### Method 2: getUpdatedQueries\(PlayerStat\) + +This method returns the exact queries that were sent to the database. In this way, you can fiddle yourself with the given data in a raw format and can see what the incremental changes \(update value\) are instead of just the absolute change \(final value\). I will not go into detail on how to read data from these queries, but I will provide a final example on how to listen to an UpdateDataEvent below. + +#### Final example: How to set up your listener + +```text +@EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true) +public void onUpdateDateEvent(final UpdateDataEvent event) { + + List playerInfos = event.getUpdatedInfo(PlayerStat.FOOD_EATEN); + + for (PlayerInfo playerInfo: playerInfos) { + // Incorrect PlayerInfo object. + if (playerInfo == null || !playerInfo.isValid()) { + return; + } + + double totalValue = playerInfo.getTotalValue(new RowRequirement("foodEaten", "APPLE"), new RowRequirement("world", "foodWorld")); + + System.out.println("Player " + playerInfo.getUUID() + " has now eaten " + totalValue + " apples!"); + } +} +``` + diff --git a/faq.md b/faq.md new file mode 100644 index 0000000..9f1983b --- /dev/null +++ b/faq.md @@ -0,0 +1,20 @@ +# FAQ + +This page has answers to the most commonly asked questions. Please check this page first before asking a question on the Spigot forums! + +#### Statz keeps spamming 'Save Statz database.' How do I disable this? + +If you want to disable this message completely, set _show database save message_ in the config.yml to false. + +#### How can I disable stats tracking for players in creative? + +Set _ignore creative_ in the config.yml to false. + +#### How do I disable certain statistics? + +You can add disabled statistics in the config by adding it to the list of _disabled statistics_. To view the different statistics Statz stores, [click here](data/how-to-disable-statistics.md). + +#### Where can I find a list of commands or permissions? + +[Click here](commands-permissions.md#commands). + diff --git a/how-does-statz-store-its-data.md b/how-does-statz-store-its-data.md new file mode 100644 index 0000000..822af00 --- /dev/null +++ b/how-does-statz-store-its-data.md @@ -0,0 +1,269 @@ +# How does Statz store its data? + +Statz records quite a bit of data, as can be seen [here](https://www.spigotmc.org/resources/statz.25969/). To make sure this data is properly stored and easy and efficient to retrieve, Statz uses either [SQLite](https://www.sqlite.org/) or [MySQL](https://www.mysql.com/) \(depending on the choice of the configuration options\). Since this page is not meant for an introductory course on SQL and database, I'll provide you a link to a tutorial on the internet: [http://www.sqlcourse.com/intro.html](http://www.sqlcourse.com/intro.html). + +Table of contents: + +* [Data stored in Statz's database](how-does-statz-store-its-data.md#data-stored-in-statzs-database) +* [Data not stored in Statz's database, but still retrievable by Statz](how-does-statz-store-its-data.md#data-not-stored-in-statzs-database-but-retrievable-by-statz) + +## Data stored in Statz's database + +Statz records a multitude of different datasets and arranges them in tables. For example, Statz has a table called 'statz_distance\_travelled' that contains all info about the ways players travel. Every table will be discussed here. Every table consists of columns that hold specific info about an action. The identifier and info stored by each column vary over tables, but every table has at least an \_id_ column that will track the changes across the table. + +### arrows\_shot + +This table holds info about arrows that were shot by players. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _forceShot_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of arrows a player has fired. +The WORLD column stores on what world the arrow was fired. +The FORCESHOT column stores in with what force the arrow was shot. This can be anything from 0.0 to 1.0. + +### blocks\_broken + +This table holds all info about the blocks a player has broken. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _typeid_ and _datavalue_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of blocks that were broken for a specific block. +The WORLD column stores on what world the blocks were broken. + +Penultimately, the TYPEID column stores the id of the block that was broken. For example, a torch has id 50 \(for reference, see [http://www.minecraftwiki.net/images/8/8c/DataValuesBeta.png](http://www.minecraftwiki.net/images/8/8c/DataValuesBeta.png)\). + +Lastly, the DATAVALUE column stores the extra data that is sometimes associated with the broken block. For example, a torch does not have a data value, but wool \(id 35\) has a data value for each color \(white wool has data value 0, while black wool has data value 15\). + +### blocks\_placed + +This table has exactly the same columns as _**statz\_blocks\_broken**_, but is associated with placed blocks instead of broken ones. + +### buckets\_emptied + +This table holds info about players that emptied buckets. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_ The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the amount of buckets a player has emptied. +The WORLD column stores on what world the bucket was emptied by the player. + +### buckets\_filled + +This table stores exactly the same things as **buckets\_emptied**, but it is associated with buckets that were filled instead of emptied. + +### commands\_performed + +This table stores the commands that were performed by players. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _command_ and _arguments_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a command was performed. The WORLD column stores on what world the command was performed. The COMMAND column stores what command was performed. Together with the ARGUMENTS column, the whole argument syntax is provided. The COMMAND column only stores the first word \(or letter\) and the others words \(arguments/parameters\) are stored in the ARGUMENTS column. For example, when a player performs **/statz check Staartvin**, the COMMAND column will be filled by '/statz' and the ARGUMENTS column will store 'check Staartvin'. + +### damage\_taken + +This table holds info about players that took damage in some way or form. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _cause_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the amount of damage a player has taken. +The WORLD column stores on what world the damage was taken by the player. +The CAUSE column stores in what way the player was hurt. It can take any of the following forms: [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html). + +### deaths + +The deaths table is used to store info regarding the deaths of any player on the server. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores how many times a player has died. The WORLD column stores on what world the player has died. + +### distance\_travelled + +This table consists of data used to track the movement of players. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _moveType_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores how far a player has travelled. The WORLD column stores on what world the player travelled. The MOVETYPE column stores in what way the player travelled. This can either be: + +* BOAT +* FLY +* MINECART +* PIG +* PIG IN MINECART +* HORSE +* HORSE IN MINECART +* FLY WITH ELYTRA + +### eggs\_thrown + +This table holds info about players that threw eggs. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of eggs a player has thrown. The WORLD column stores on what world the egg was thrown. + +### entered\_beds + +This table stores when a player went to sleep. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player went to bed. The WORLD column stores on what world the player went to sleep. + +### food\_eaten + +This table holds info about what players have eaten. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _foodEaten_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has eaten a specific food item. The WORLD column stores on what world the food was omnomnom'd. The FOODEATEN column stores what food item was digested. + +### items\_caught + +This table holds info about players that caught some item while fishing. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _caught_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player caught a specific item. The WORLD column stores on what world the item was caught. The CAUGHT column stores what item was caught. \(A written book, a certain fish species, an old bottle of liquor, an old boot, etc.\) + +### items\_crafted + +This table holds info about players that crafted something. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player crafted a specific item. The WORLD column stores on what world the item was crafted. The ITEM column stores what was exactly crafted. + +### items\_dropped + +This table holds info about players that dropped something. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player dropped a specific item. The WORLD column stores on what world the item was dropped. The ITEM column stores what was exactly dropped. + +### items\_picked\_up + +This table holds info about players that picked up something. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player picked up a specific item. The WORLD column stores on what world the item was picked up. The ITEM column stores what was exactly picked up. + +### joins + +This table holds info about players that joined the server. It has 2 columns \(excluding the id column\): _uuid_ and _value_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has joined the server. + +### kills\_mobs + +This table holds info about players that killed a mob. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _mob_ and _weapon_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player killed a specific mob. The WORLD column stores on what world the mob was killed. The MOB column stores what mob was killed by the player. the WEAPON column stores what weapon was used to kill the mob. + +### kills\_players + +This table holds info about players that killed other players. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _playerKilled_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player killed another player. The WORLD column stores on what world the other player was killed. The MOB column stores what other player was killed by the player. + +### players + +This table holds info about the name and UUID of a player. It has 2 columns \(excluding the id column\): _uuid_ and _playerName_. +The UUID column stores, coincidentally, the UUID of the player. +The PLAYERNAME column stores the name of the player \(with a specific UUID\) when it joined the server. + +### teleports + +This table holds info about players that teleported. It has 5 columns \(excluding the id column\): _uuid_, _value_, _world_, _destWorld_ and _cause_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has teleported. The WORLD column stores what world the player teleported from. The DESTWORLD column stores what world the player teleported to. The CAUSE column stores what the cause was of the teleport. It the cause was unknown, UNKNOWN will be provided as cause. + +### time\_played + +This table holds info about the time players played on the server. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of minutes a player has been online. The WORLD column stores on what world the player has played for x minutes. + +### times\_kicked + +This table holds info about players that were kicked. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _reason_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has been kicked. The WORLD column stores what world the player was kicked. The REASON column stores what the specified reason was for the kick. If no reason was provided by the 'kicker', the reason will be 'Kicked from server.'. + +### times\_shorn + +This table holds info about players that have shorn sheep. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has shorn a sheep. The WORLD column stores on what world the player has shorn a sheep. + +### tools\_broken + +This table holds info about players that broke their tools. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _item_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has broken a type of tool. The WORLD column stores on what world the player has broken the tool. The ITEM column stores what tool was broken. + +### villager\_trades + +This table holds info about players that traded with villagers. It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _trade_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has traded with a villager. The WORLD column stores on what world the player has performed the traded. The TRADE column stores what item the player received from the villager. + +### votes + +This table holds info about players that voted via Votifier or NuVotifier. It has 2 columns \(excluding the id column\): _uuid_ and _value_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has voted for the server. + +### worlds\_changed + +This table holds info about players that changed worlds \(via portals or commands\). It has 4 columns \(excluding the id column\): _uuid_, _value_, _world_ and _destWorld_. +The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the number of times a player has switched worlds. The WORLD column stores from what world the player switched. The DESTWORLD column stores to what world the player switched. + +### xp\_gained + +This table holds info about players that gained exp. It has 3 columns \(excluding the id column\): _uuid_, _value_ and _world_. The UUID column stores, coincidentally, the UUID of the player. +The VALUE column stores the amount of xp that was gained. The WORLD column stores on what world the player gained xp. + +## Data not stored in Statz's database, but retrievable by Statz + +Besides storing a lot of information of players, Statz also manages data connection between other third-party plugins. + +#### MCMMO + +Statz tracks the level of each individual skill for every player and their total power level. + +#### AcidIsland + +Statz tracks island level of each player. + +#### ASkyBlock + +Much like AcidIsland, Statz tracks island level of each player. + +#### AFKTerminator + +Statz can check whether a player is AFK according to AFKTerminator + +#### EssentialsX + +Statz tracks whether a player is AFK \(according to EssentialsX\) and the \(estimated\) geo-location of their IP. + +#### Factions + +Statz can track the faction power of each player in a faction. + +#### Jobs + +Statz tracks multiple things: + +* Current points in a job +* Total points across all jobs +* Current XP in a current job +* Current level of a specific job + +#### OnTime + +Statz tracks play time of a player. + +#### RoyalCommands + +Statz can track whether a player is AFK. + +#### Stats 3 + +Statz can track all data of Stats 3 and also import data from Stats 3 \(see **/statz migrate**\). + +#### UltimateCore + +Statz tracks whether players are AFK. + +#### Vault + +Statz uses Vault to connect to permissions plugins and economy plugins, hence it can check for permissions and for money of a player. + +#### WorldGuard + +Statz can track in what region a player currently resides + +#### GriefPrevention + +Statz tracks a few things: + +* Number of claims of a player +* Number of claimed blocks of a player +* Number of remaining blocks a player can still claim +* Number of bonus blocks a player is allowed to claim + diff --git a/how-to-disable-statistics.md b/how-to-disable-statistics.md new file mode 100644 index 0000000..d367608 --- /dev/null +++ b/how-to-disable-statistics.md @@ -0,0 +1,21 @@ +# How to disable statistics? + +## What is it and why is it useful? + +The `disabled-stats.yml` allows you to disable any statistic in under specific circumstances. For example, you can disable the tracking of kills in a certain _WorldGuard_ arena or in a _GriefPrevention_ claim. As of now, these 'scenarios' are supported: + +* WorldGuard regions: disable a statistic in a WorldGuard region +* GriefPrevention claims: disable a statistic in the claim of any user. + +For more info on how to set this up, read on! + +## How to configure the file? + +To configure the disabled-stats.yml, you can use any file editor. Each statistic can be specified only once, but for more than one scenario's simultaneously. Let's take a look at a sample file: + +![Example of config file](https://i.imgur.com/h5ibohD.png) + +The image shows an example of how you can define WorldGuard regions and GriefPrevention claims. A WorldGuard region needs a region name, so Statz can check whether the player is in that region. The GriefPrevention claim needs a UUID of a player to check whether a random player is in the claim of the player the UUID corresponds to. + +You can see that the DISTANCE\_TRAVELLED stat will not be updated whenever a player is in a WorldGuard region called 'TestRegion' or 'Lala'. Similarly, this stat will not be updated whenever a player is in the GriefPrevention claim area that corresponds to one of those UUIDs. + diff --git a/placeholders/placeholders.md b/placeholders/placeholders.md new file mode 100644 index 0000000..4faba9f --- /dev/null +++ b/placeholders/placeholders.md @@ -0,0 +1,158 @@ +# Placeholders + +Statz has built-in support for several placeholders. This means that you only need Statz to make use of the placeholders. **If you're still using a Statz expansion with PAPI, please remove it as it may interfere with Statz's built-in code.** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Placeholder +
statz_joins +
statz_deaths +
+

statz_deaths_WORLD_NAME +

+

(the world name is case sensitive!)

+
statz_blocks_broken +
+

statz_blocks_broken_BLOCK +

+

(for block types, see this page)

+
statz_blocks_placed +
+

statz_blocks_placed_BLOCK +

+

(for block types, see this page)

+
statz_damage_taken +
+

statz_distance_travelled +

+

(total distance travelled) +

+
+

statz_distance_travelled_MOVEMENT +

+

(you can use FLY, SWIM, BOAT, MINECART, PIG, PIG_IN_MINECART, HORSE, HORSE_IN_MINECART, WALK, + or FLY_WITH_ELYTRA)

+
+

statz_food_eaten +

+

(total +

+
+

statz_food_eaten_FOOD +

+

(for foodtypes, see this page)

+
statz_crafted_items +
statz_caught_items +
statz_players_killed +
+

statz_time_played +

+

(total time played in minutes)

+
+

statz_time_played_formatted +

+

(total play time, but formatted in x days, y hours and z minutes) +

+
statz_times_shorn +
statz_xp_gained +
+

statz_mobs_killed +

+

(total mobs killed) +

+
+

statz_mobs_killed_MOB +

+

(for mobs type, see this page)

+
+

statz_villager_trades +

+

(total trades made) +

+
+

statz_villager_trades_BLOCK +

+

(for block types, see this page)

+
statz_votes +
+ + +