Upstream/Plan
1
0
Fork 0
mirror of https://github.com/plan-player-analytics/Plan.git synced 2024-09-15 00:07:48 +02:00
Code Issues Projects Releases Wiki Activity

Removed outdated Documentation .md files

Browse Source
This commit is contained in:
Rsl1122 2017-10-02 20:56:11 +03:00
parent 2b6b27b1e3
commit 46f1ee40b2
12 changed files with 0 additions and 860 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

296
documentation/API.md
View File

@ -1,296 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# API
- [API class](/Plan/src/main/java/com/djrapitops/plan/api/API.java)
- [API Javadocs](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/api/API.html)
## Accessing the API Methods:
Install the Plan.jar as a local dependency if you're using Maven.
Add soft-depend or depend in the plugin.yml
```
import main.java.com.djrapitops.plan.api.API;
if (getPluginManager().isPluginEnabled("Plan")) {
try {
// Throws IllegalStateException if onEnable() method for Plan has not yet been called.
// Throws NoClassDefError if Plan is not installed
API planAPI = Plan.getPlanAPI();
} catch (Throwable e) {
// Do something (Plan is not installed)
}
}
```
# Plugins Tab
- [PluginData](/Plan/src/main/java/com/djrapitops/plan/data/additional/PluginData.java)
- [PluginData Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/PluginData.html)
- [AnalysisType Enum](/Plan/src/main/java/com/djrapitops/plan/data/additional/AnalysisType.java)
- [AnalysisType Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/AnalysisType.html)
- [Example classes](/Plan/src/main/java/com/djrapitops/plan/data/additional)
## Adding plugin's data to the 'plugins'-tab on Analysis and/or Inspect pages
Plan has a flexible data addition system since 3.1.0. With it you can add Averages, Totals, Percentages, Tables & Other Html elements to the Plugins tab on the Analysis and/or Inspect pages.
To add data **a class that extends PluginData class is needed.**
One PluginData object should only contain data for one user, but tables & other elements are an exception.
### Registering the data point
```
PluginData yourPluginDataObject = new YourClassThatExtendsPluginData();
Plan.getPlanAPI().addPluginDataSource(yourPluginDataObject);
```
**If you register multiple data sources, they will appear in the order they were registered.**
## Building the PluginData object
### Super Constructors
Constructor determines if the datapoint can be analyzed or not & how it should be analyzed.
The Inspect page visibility can be changed with another method call.
Constructor | Parameters | Description
-- | -- | --
super(pluginName, placeholder) | Name of the plugin & the placeholder, eg: "stepsTaken" | This datapoint will be only shown on the Inspect page
super(pluginName, placeholder, AnalysisType.INT_TOTAL) | Type is determined by return value of getValue(UUID)-method | This datapoint will be shown on the Analysis page with total for all Players
super(pluginName, plaheholder, AnalysisType.INT_AVG, AnalysisType.INT_TOTAL) | The constructor takes as many AnalysisTypes as needed. | This datapoint will be shown on the Analysis page with the total and average for all Players
### Method calls in the contructor
There are multiple methods that change the appearance of the PluginData object on the webpage:
Method | Description
-- | --
super.analysisOnly(boolean) | Determine whether or not the datapoint should be only shown on the Analysis page, Set to false to show it on the Inspect page as well.
super.setPrefix(String) | For example: super.setPrefix("Steps taken: "), determines the prefix
super.setSuffix(String) | For example: super.setSuffix(" steps"), determines the suffix.
super.setIcon(String) | Set the font awesome icon name: [Font Awesome Icons](http://fontawesome.io/icons/)
To not show the datapoint on Analysis page, do not give the constructor any AnalysisType variables.
### getHtmlReplaceValue(String modifier, UUID uuid)-method
This method is used by Inspect page & by Analysis Page when AnalysisType.HTML is specified.
**It should use the parseContainer(String modifier, String value) method when returning a value.**
The Prefix, Suffix & Icon are added to the value automatically when using the parseContainer(String modifier, String value)-method.
Example:
```
@Override
public String getHtmlReplaceValue(String modifier, UUID uuid) {
return parseContainer(modifier, stepCounter.getSteps(uuid)+"");
}
```
UUID is the UUID of the player whose Inspect page is displayed OR Random UUID on Analysispage when AnalysisType.HTML is specified
### getValue(UUID uuid)-method
This method is used by Analysis when calculating Totals & Averages for each PluginData object.
The return type is Serializable, so Integer, Double, Long, Boolean & String can be returned.
What type you return determines what AnalýsisType you should use in the super constructor.
**-1** should be returned if the player has no value / Your plugin has no data on the player
If -1 is returned, the value is ignored when calculating Averages & Totals.
**Wrong AnalysisType will cause an exception during calculation** - It is caught per AnalysisType, so test your plugin with /plan analyze.
# Examples:
- Basic Example
- Analysis Example
- Table Example
## Basic Example
This class will show "Steps Taken" on the Inspect page.
```
public class StepCounterSteps extends PluginData {
private StepCounterPlugin stepCounter; // This is the example plugin where the data is taken from.
// Constructor with the plugin as parameter.
public StepCounterSteps(StepCounterPlugin stepCounter) {
// A call to super constructor: PluginName, PlaceholderName
super("StepCounter", "stepsTaken");
super.setPrefix("Steps taken: ")
super.setSuffix(" steps");
super.setIcon("wheelchair");
this.stepCounter = stepCounter; // Setting the plugin
// Registering to the API, this can be done outside the class as well.
API api = Plan.getPlanAPI();
if (api.isEnabled()) {
api.addPluginDataSource(this);
}
}
// Required method.
// This method is used with AnalysisType.HTML and for Inspect page's values.
// All return values should use parseContainer(String modifier, String value)-method, more on that down below.
@Override
public String getHtmlReplaceValue(String modifier, UUID uuid) {
return parseContainer(modifier, stepCounter.getSteps(uuid)+"");
}
// Required method.
// This method is used to calculate values for the Analysis page.
@Override
public Serializable getValue(UUID uuid) {
return stepCounter.getSteps(uuid);
}
}
```
## Analysis Example
Adding data to the Analysis page is straightforward as well. Please note that one class can add a data to both Analysis & Inspect pages.
To add data to the Analysis page, analysisTypes need to be set.
This is done in the super constructor.
Refer to AnalysisType for what types you should add. The type depends on the return of the getValue(UUID uuid)-method you have written.
- [AnalysisType](/Plan/src/main/java/com/djrapitops/plan/data/additional/AnalysisType.java)
- [AnalysisType Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/AnalysisType.html)
AnalysisType.HTML is for all other elements you might want to add - parseContainer method will be used instead of the getValue method.
**If you want this same datapoint to show data on the inspect page call super.analysisOnly(false);**
Good example is the [FactionsPower](/PlanPluginBridge/src/main/java/com/djrapitops/pluginbridge/plan/factions/FactionsPower.java)
## Table Example
A good example is the [AdvancedAchievementsTable](/Plan/src/main/java/com/djrapitops/plan/data/additional/advancedachievements/AdvanceAchievementsTable.java).
You can use the [Html Enum](/Plan/src/main/java/com/djrapitops/plan/ui/Html.java) to quickly create table html.
The Html Enum has easy lines for 2, 3 & 4 line columns - More than that will most likely not fit in the box.
the parse(String... p)-method takes as many strings as parameters as needed to replace all the REPLACE# placeholders on the line.
Let's deconstruct the constructor.
```
public AdvancedAchievementsTable(AdvancedAchievementsAPI aaAPI) {
super("AdvancedAchievements", "achievementstable", AnalysisType.HTML);
this.aaAPI = aaAPI;
String player = Html.FONT_AWESOME_ICON.parse("user") + " Player";
String achievements = Html.FONT_AWESOME_ICON.parse("check-circle-o") + " Achievements";
// analysisOnly true by default.
super.setPrefix(Html.TABLE_START_2.parse(player, achievements));
super.setSuffix(Html.TABLE_END.parse());
}
```
- analysisTypes is set as AnalysisType.HTML.
- prefix is set as a sortable table's start with "<icon> Player" and "<icon> Achievements" columns.
- suffix is set as the end tags for the whole table.
Now let's see how the table gets the values:
```
@Override
public String getHtmlReplaceValue(String modifierPrefix, UUID uuid) {
StringBuilder html = new StringBuilder();
List<OfflinePlayer> offlinePlayers = Arrays.stream(getOfflinePlayers()).filter(p -> p.hasPlayedBefore()).collect(Collectors.toList());
if (offlinePlayers.isEmpty()) {
html.append(Html.TABLELINE_2.parse("No Players.",""));
} else {
for (OfflinePlayer p : offlinePlayers) {
String inspectUrl = HtmlUtils.getInspectUrl(p.getName());
String achievements = aaAPI.getPlayerTotalAchievements(p.getUniqueId()) + "";
html.append(Html.TABLELINE_2.parse(Html.LINK.parse(inspectUrl, p.getName()), achievements));
}
}
return parseContainer("", html.toString());
}
```
It simply gets the Players that have played on the server. If the list is empty, a row with "No Players" is added to the value (html, StringBuilder).
Otherwise it get's the Url for the Inspect page of each player, and the amount of achievements a player has.
The link is parsed inside a html a-tag (with the text of the players name).
Then that is parsed into a table line with the a-tag & achievements.
The parseContainer uses an empty string as modifierPrefix, because we don't want any extra text added in-front of the table.
Inspect doesn't use getValue(UUID uuid) &
AnalysisType.HTML disregards it's return values, so that simply returns an empty string.
```
@Override
public Serializable getValue(UUID uuid) {
return "";
}
```
# Accessing the Data & Modification
In addition to the Plugins tab methods the API provides methods for accessing the data of Analysis & Players.
Before using these methods you might want to read about the Caches to understand the difference between DataCache, InspectCache & AnalysisCache
- [Gathering the data & Data Cache](/documentation/DataGathering.md)
## Utility methods
Method | Returns | Description
-- | -- | --
playerNameToUUID(String) | UUID of the player or null | Uses [UUIDFetcher](/Plan/src/main/java/com/djrapitops/plan/utilities/UUIDFetcher.java) to fetch the UUID
getPlayerName(UUID) | Players username | Get's the OfflinePlayer and asks for it's name.
isEnabled() | boolean | Check whether or not Plan enabled successfully
isPlayersDataInspectCached(UUID uuid) | boolean | Check if player's data is in the InspectCache
isAnalysisCached() | boolean | Check if the AnalysisData is cached.
getPlayerInspectPageLink(String name) | Web address | Get the Inspect page link for a player.
## Web methods
Method | Description
-- | --
getAnalysisHtmlAsString() | Returns the full html for Analysis page. If isAnalysisCached() is false, will return html for a 404.
getPlayerHtmlAsString(UUID uuid) | Returns the full html for Inspect page. If isPlayersDataInspectCached(UUID) is false, will return html for a 404.
## Cache methods
Method | Description
-- | --
updateAnalysisCache() | Run's the analysis & places AnalysisData to the cache.
getAnalysisDataFromCache() | Returns the AnalysisData in the cache.
cacheUserDataToInspectCache(UUID uuid) | Caches the UserData of the player to InspectCache from cache or the database. Call from Async thread.
scheduleForGet(UUID uuid, DBCallableProcessor processor) | Schedule a UserData object to be fetched from the database or cache if the player is online.
scheduleEventHandlingInfo(HandlingInfo info) | Cause your own Event to modify the UserData object that is stored in the database.
placeDataToCache(UserData data) | Used to cache a UserData object. If data is already cached it will be overridden. (Use with caution)
saveCachedData() | Saves all UserData in the Cache to the database. Should be only called from an Asyncronous thread.
### DBCallableProcessor
scheduleForGet uses [DBCallableProcessor interface](/Plan/src/main/java/com/djrapitops/plan/data/cache/DBCallableProcessor.java).
The processor's method is called after the fetch is complete.
UUID is the uuid of the player.
Example:
```
DBCallableProcessor p = new DBCallableProcessor() {
@Override
public void process(UserData data) {
// Do something with the data
}
};
Plan.getPlanAPI().scheduleForGet(uuid, p);
```
### HandlingInfo
scheduleEventHandlingInfo uses [HandlingInfo abstract class](/Plan/src/main/java/com/djrapitops/plan/data/handling/info/HandlingInfo.java).
This object can modify the UserData in the cache. If the data is not in the cache prior to processing the data, it will be fetched & placed there.
UUID is the uuid of the player.
Example:
```
long time = new Date().getTime();
HandlingInfo i = new HandlingInfo(uuid, InfoType.OTHER, time) {
@Override
public boolean process(UserData data) {
if (uuid.equals(data.getUuid()) {
// Modify the data in some way
return true;
}
return false;
}
};
Plan.getPlanAPI().scheduleEventHandlingInfo(i);
```

78
documentation/CertificateTutorial.md
View File

@ -1,78 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# HTTPS Configuration
## How to configure Plan to use SSL Encryption:
- Obtain a Java Keystore file (More below)
- Place the keystore file in the /plugins/Plan/ folder
(If you have a keystore file elsewhere on the machine, you can specify the full path to the file.)
- Change the config settings under **WebServer**:
Config.Setting | Description
------------------- | ---------------
Certificate.KeyStorePath | The absolute path to the certificate file, you can directly use “KEYSTORE.FILE” if the certificate is placed in the Plan folder, if it’s elsewhere, use the direct path to it.
Certificate.KeyPass | The password of the certificate
Certificate.StorePass | The password of the keystore
Certificate.Alias | The alias of the keystore
# Obtaining a Java Keystore File
## How to get a certificate issued by Let’s Encrypt:
See here:
https://letsencrypt.org/getting-started/
## How to convert the certificate files into a Java KeyStore:
Execute keytool command in the Command Prompt (Windows) or in the Shell (Linux)
`keytool -importcert -file $CERTIFICATE -keystore $KEYSTORE -alias “$ALIAS”`
After executing the command, you need to enter the password of the keystore currently being created.
Notes:
The password for the keystore must be at least 6 characters long.
**NOTE FOR WINDOWS USERS:**
The keytool command is only going to work, when the Command Prompt is opened in `$JAVA_HOME\jre$VERSION\lib\security`
You can manage that by going to that path using
`cd $JAVA_HOME\jre$VERSION\lib\security`
## If you’re unable to obtain a certificate
If you do not have a domain for certificate registration, or can not create a self signed one, Plan.jar contains a self signed RSA 2048 certificate that can be used.
Open Plan.jar in any archive manager (Like WinRAR) and drop the Certificate.keystore file in the /plugins/Plan/ folder.
Set the config settings as follows so that the Certificate works.
Config.Setting | Value
------------------- | ---------------
Certificate.KeyStorePath | Cert.keystore
Certificate.KeyPass | MnD3bU5HpmPXag0e
Certificate.StorePass | wDwwf663NLTm73gL
Certificate.Alias | DefaultPlanCert
Self signed certificates cause browsers to display security warning:
![Certificate Warning](http://puu.sh/wY5Gs/91883c1ced.jpg)
You can ignore this warning. [“Dangers” of self signed certificates, Article](https://www.globalsign.com/en/ssl-information-center/dangers-self-signed-certificates/)
### Displaying a Green HTTPS Lock with Cloudflare
Requirements:
- A cloudflare account
- A domain with full access
If you wish to bypass the security warning (not seeing that the connection isn’t private), you can use [Cloudflare](https://www.cloudflare.com)
- Connect your domain to Cloudflare
- Add a DNS record of the type “A” which points to your Server IP
- Go to “Crypto” -> “SSL” and set the option to “Flexible”
Notes:
If you only want to use HTTPS on the Analytics site, you can use the “Page Rules”
[Page Rules Tutorial](https://support.cloudflare.com/hc/en-us/articles/218411427-Page-Rules-Tutorial)
It is recommend to activate “Automatic HTTPS Rewrites” under “Crypto” to be able to use http://LINK.TLD as well.
This removes the need to write “https://” at the beginning of the address.

1
documentation/Class Diagram
View File

File diff suppressed because one or more lines are too long

53
documentation/CommandsAndPermissions.md
View File

@ -1,53 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Commands & Permissions
- [Plugin.yml](/Plan/src/main/resources/plugin.yml)
- [Permissions Enum](/Plan/src/main/java/com/djrapitops/plan/Permissions.java)
This page is an in depth documentation of all permissions & commands.
Page version: **3.6.0**
# Commands
Command | Permission | Default | Description
--- | ---- | ------ | ---------------------------------
/plan | plan.? | true | Base command, Shows help. Alias for /plan inspect [player] when used like /plan [player]
/plan inspect | plan.inspect | true | Gives the link to player page of the player who issued the command.
/plan inspect [player] | plan.inspect.other | OP | Gives link to player page of the given playername, CaSe-SenSiTiVe.
/plan qinspect | plan.qinspect | OP | Displays information about the issuing player in the chatbox.
/plan qinspect [player] | plan.qinspect.other | OP | Displays information about the player in the chatbox, CaSe-SenSiTiVe.
/plan analyze | plan.analyze | OP | Gives a link to the Analysis page of the server.
/plan qanalyze | plan.qanalyze | OP | Displays analysis information in the chatbox.
/plan search [argument] | plan.search | OP | Searches for matching playernames & gives the link to matching player's pages.
/plan reload | plan.reload | OP | Reloads the plugin. (All active play-sessions will be ended & started.)
/plan info | plan.info | OP | View version, update availability & active database
/plan manage | plan.manage | OP | Manage the database of the plugin.
/plan register | none / plan.webmanage | true | Register the sender / another user (requires the perm)
/plan webuser | plan.webmanage | OP | Manage web users.
none | plan.ignore.commanduse | false | Commands issued by players with this permission will be ignored.
## Permission Groups:
### plan.basic:
- plan.?
- plan.inspect
- plan.qinspect
### plan.advanced
- plan.basic
- plan.info
- plan.qanalyze
### plan.staff
- plan.advanced
- plan.search
- plan analyze
- plan.inspect.other
- plan.qinspect.other
- plan.reload
- plan.webmanage
### plan.*
- plan.staff
- plan.manage
- apf.notify

86
documentation/Configuration.md
View File

@ -1,86 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Configuration
- [Default Config](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/resources/config.yml)
- [Settings Enum](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/Settings.java)
This page is an in depth documentation on what each Setting does in the config.
Page Version: **3.6.0**
# Settings
## Basic settings
Config.Point | Version introduced | Type | Default | Description
--- | ---- | ------ | --- | ---------------------------------
Debug | 3.0.0 | boolean | false | Enables debug messages on console.
Locale | 2.5.0 | String | default | Two letter Locale combination. Can be set to one of the Available locales. If a faulty combination is used, default locale will be used. [Available locales](https://github.com/Rsl1122/Plan-PlayerAnalytics/tree/master/Plan/localization)
WriteNewLocaleFileOnStart | 3.6.2 | boolean | false | Setting this to true & reloading the plugin will generate a new locale.txt & it will be set back to false. [Localization](/documentation/Localization.md)
UseTextUI | 3.0.0 | boolean | false | Redirects */plan inspect* and */plan analyze* commands to display same messages as */plan qinspect* & */plan qanalyze*
Data.ChatListener | 3.4.2 | boolean | true | Enables Chat listener
Data.GatherKillData | 3.4.2 | boolean | true | Enables Death listener
Data.GatherCommandUsage | 3.4.2 | boolean | true | Enables CommandPreprocess listener
## Analysis settings
Config.Point | Version introduced | Type | Default | Description
--- | ---- | ------ | --- | ---------------------------------
LogProgressOnConsole | 2.4.0 | boolean | false | More detailed analysis progress to console.
NotifyWhenFinished | 3.0.0 | boolean | true | Enables ["Analysis Complete"-message](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/Phrase.java#L73) will be shown on the console after analysis is complete.
MinutesPlayedUntilConsidiredActive | 2.0.0 | Integer | 10 | This setting affects how the Analysis treats player's activity. Whether or not a player is active is determined with 3 values: Last Login, Playtime and Login Times. If the player has logged in in the last 2 weeks, has playtime higher than in the config, and has logged in 3 times, the player is considered active. Otherwise the player is counted as inactive.
Export.Enabled | 3.4.0 | boolean | false | Enables export of html pages after analysis
Export.DestinationFolder | 3.4.0 | String | 'Analysis Results' | Path to the export folder. Will be created if doesn't exist. If contains ':' will be regarded as full filepath.
## Cache settings
Config.Point | Version introduced | Type | Default | Description
--- | ---- | ------ | --- | ---------------------------------
Processing.GetLimit | 2.8.0 | Integer | 2000 | Changes the queue size for database get actions. If queue runs out notification is given on console.
Processing.SaveLimit | 2.8.0 | Integer | 1000 | Changes the queue size for database save actions. If queue runs out notification is given on console.
Processing.ClearLimit | 2.8.0 | Integer | 1000 | Changes the queue size for clearing datacache. If queue runs out notification is given on console.
AnalysisCache.RefreshAnalysisCacheOnEnable | 2.?.0 | boolean | true | Enables Analysis refresh 30 seconds after boot/reload
AnalysisCache.RefreshEveryXMinutes | 2.4.0 | Integer | -1 | Enables periodic Analysis refresh, -1 to disable
DataCache.SaveEveryXMinutes | 2.0.0 | Integer | 2 | Determines how often cache is saved to the Database.
DataCache.ClearCacheEveryXSaves | 2.0.0 | Integer | 5 | Determines how often cache clear attempt is made. This is done in case some data is left lingering even after the player has been gone for a long time.
## WebServer settings
Config.Point | Version introduced | Type | Default | Description
--- | ---- | ------ | --- | ---------------------------------
Enabled | 2.1.0 | boolean | true | Enables the Webserver
Port | 2.0.0 | Integer | 8804 | Port of the Webserver
InternalIP | 3.0.0 | String | 0.0.0.0 | Internal InetAddress to start the WebServer on.
ShowAlternativeServerIP | 2.0.0 | boolean | false | Enables the use of the link below in the inspect and analyze commands.
AlternativeIP | 2.0.0 | String | `your.ip.here:%port%` | Address to use as link in inspect and analyze commands if setting above is enabled. %port% will be replaced with the Port automatically. If you have port-forwarded an alternate address to the webserver port, %port% is not required.
ExternalWebServerLinkProtocol | 3.6.0 | String | http | Changes the protocol in links given by the commands. SHOULD NOT BE CHANGED IF NOT USING EXTERNAL WEBSERVER.
Security.DisplayIPsAndUUIDs | 2.5.0 | boolean | true | Toggles visibility of UUIDs and IPs on player Inspect page.
Security.Certificate | 3.6.0 | | | [View the tutorial on setting up a SSL Certificate](/documentation/CertificateTutorial.md)
## Customization settings
Config.Point | Version introduced | Type | Default | Description
--- | ---- | ------ | --- | ---------------------------------
ServerName | 3.3.0 | String | 'Plan' | Changes the Name in the Header of Analysis & Inspect pages.
Formats.TimeAmount | 3.3.0 | String | '%days%d ' | Changes the format used when formatting Time Amounts. Include %zero% to add a 0 in front of single numbers.
Formats.DecimalPoints | 3.3.0 | String | #.## | Changes how many decimals are displayed after doubles. (For 3 use #.### etc.)
Colors.Commands | 2.1.0 | String | | Color codes used with the */plan* commands.
Colors.HTML | 2.1.0 | String |  | These HTML Color codes are used when generating the Html pages. Use without the # (hashtag)
Plugins.Enabled | 3.3.0 | boolean | true | Settings for enabling hooks to plugins (For Plugins tab)
Plugins.Factions.HideFactions | 3.1.0 | String list | - ExampleFaction | Add a list of Faction names you don't want to show up on the Analysis page.
Plugins.Towny.HideTowns | 3.1.0 | String list | - ExampleTown | Add a list of Town names you don't want to show up on the Analysis page.
## Database settings
Config.Point | Version introduced | Type | Default | Description
--- | ---- | ------ | --- | ---------------------------------
database.type | 2.0.0 | String | sqlite | Determines the type of database the plugin will use. **sqLite** - sqLite database file will be created. **MySQL** - MySQL settings are used.
mysql.host | 2.0.0 | String | localhost | IP of the MySQL-database
mysql.port | 2.0.0 | Integer | 3306 | Port of the MySQL-database
mysql.user | 2.0.0 | String | root | MySQL user
mysql.password | 2.0.0 | String | minecraft | User's password
mysql.database | 2.0.0 | String | Plan | Name of the database that has already been created. Please note, that you have to create this database in your mysql solution (eg. MariaDB)!
## End
If you don't see explanation for a config point or need help setting up the plugin, don't hesitate to ask for help! :)
- [Ask for help with an issue](https://github.com/Rsl1122/Plan-PlayerAnalytics/issues/new)
- [Ask for help in the spigot thread](https://www.spigotmc.org/threads/plan-player-analytics.197391/)

49
documentation/DataGathering.md
View File

@ -1,49 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Gathering the Data & Datacache
This article is an in depth explanation how the data Plan stores is gathered.
Page Version: **3.6.0**
[Stored Data & Data Format](/documentation/StoredData.md)
## Bukkit Player data
Some information is taken from Bukkit's Player or OfflinePlayer objects & Stored in the database:
- UUID (Used for saving & processing)
- Register Date
- Is the player banned
- Is the player opped
- Is the player online
## Listeners
[Listener classes](/Plan/src/main/java/com/djrapitops/plan/data/listeners)
Inside Plan, there are 6 listeners:
- Chat Listener*, Nickname & Demographics information
- Command Listener, Command Usage
- Death Listener*, Kills & Deaths
- Gamemode Change Listener*, Gamemode time calculation
- Player Listener*, Join, Leave & Kick
- World Change Listener, World time calculation
*When an event is fired, the information contained within it is placed inside [HandlingInfo objects](/Plan/src/main/java/com/djrapitops/plan/data/handling/info) related to the event.
This object is passed to the [DataCacheProcessQueue](/Plan/src/main/java/com/djrapitops/plan/data/cache/queue/DataCacheProcessQueue.java), where it will be processed.
## Processing
The HandlinInfo object has a process(UserData)-method to modify UserData.
When the processing queue starts processing the data, it asks the cache for the UserData object of the player. If the Cache doesn't have the object, it will be fetched from the dabase & placed into the cache.
After the modification, the data will be saved back into the database sometime in the future.
## Cache
[Cache classes](/Plan/src/main/java/com/djrapitops/plan/data/cache)
There are 3 Caches.
- DataCache, The active cache where data can be modified, fetched to & saved from while the player is online.
- InspectCache, Cache that stores the data of individual players when they need to be viewed on the web or for Analysis. Changes are not saved.
- AnalysisCache, Cache that stores the results of Analysis for fast access for the webserver.
### Storage in memory:
- Players data: [UserData object](/Plan/src/main/java/com/djrapitops/plan/data/UserData.java)
- Analysis data: [AnalysisData object](/Plan/src/main/java/com/djrapitops/plan/data/AnalysisData.java)
- Command Usage: [DataCacheHandler](/Plan/src/main/java/com/djrapitops/plan/data/cache/DataCacheHandler.java#L52)
- Active Sessions: [SessionCache](/Plan/src/main/java/com/djrapitops/plan/data/cache/SessionCache.java)
- Html Pages: [PageCacheHandler](/Plan/src/main/java/com/djrapitops/plan/data/cache/PageCacheHandler.java)

10
documentation/Dependencies.md
View File

@ -1,10 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Links to Dependencies - Version 3.6.0
In order to fork the project, some dependencies may need to be installed locally.
- [PaperSpigot 1.12](https://yivesmirror.com/downloads/paperspigot)
- [PlanPluginBridge](/PlanPluginBridge) (Included in the Repository)
- [Abstract Plugin Framework](https://github.com/Rsl1122/Abstract-Plugin-Framework/releases/)

135
documentation/HtmlCustomization.md
View File

@ -1,135 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Html Customization
The html web pages of the plugin can be completely customized.
The plugin uses two .html files: `analysis.html` and `player.html`
If the `/plugins/Plan/` folder contains either of the files, they will be used instead of the ones found inside the .jar.
This means you can copy the html files from the jar to the folder and edit them.
Page version: **3.4.0**
## Placeholders
The plugin uses placeholders to place the values into the html. Here I will go through each placeholder.
- [PlaceholderUtils.java](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/utilities/PlaceholderUtils.java)
## Inspect placeholders
Placeholder | Description | Example
---------- | ------------------------------------- | -----
%currenttime% | Server epoch ms, used for clock. | 1496486156
%refreshlong% | Epoch ms of last refresh (server time) | 1496486156
%uuid% | Players UUID or 'Hidden' if config setting for UUID visibility is disabled. | 88493cd1-567a-49aa-acaa-84197b5de595
%lastseen% | A formatted version of the last Epoch second the user was seen. | Feb 02 18:03:12
%logintimes% | How many times the user has logged in | 34
%geoloc% | Demographics geolocation of the user. | United States
%active% | 'Player is Active' or 'Player is Inactive' depending on [isActive](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/utilities/AnalysisUtils.java#L27)- method. |
%age% | 'Not Known' if age is not known (-1) or the users age. | 14
%gender% | 'Unknown', 'Male' or 'Female' |
%gm0% | A formatted version of milliseconds spent in SURVIVAL. | 1h 30m 4s
%gm1% | A formatted version of milliseconds spent in CREATIVE. | 1h 30m 4s
%gm2% | A formatted version of milliseconds spent in ADVENTURE. | 1h 30m 4s
%gm3% | A formatted version of milliseconds spent in SPECTATOR. | 1h 30m 4s
%gmdata% | Number array of seconds spent in each gamemode, used by piechart. | [32423, 5436, 432543, 23]
%gmlables% | Array of labels used by piechart. | ["Survival", "Creative", "Adventure", "Spectator"]
%gmcolors% | List of html color codes that depend on config values. | "#ffffff","#eeeeee","#000000","#213123"
%gmtotal% | A formatted version of milliseconds spent in All gamemodes. | 1h 30m 4s
%ips& | An array of users ip addresses or 'Hidden'. | [127.0.0.1/]
%nicknames% | Formatted Array of Users nicknames, with `<span class="color_#"></span>` wrapped to represent §#-color tags. | [Steve, `<span class="color_4">Steve</span>`]
%name% | User's username | Steve
%registered% | A formatted version of the Epoch second the user registered. | Feb 02 18:03:12
%timeskicked% | Number how many times the user was kicked. | 5
%playtime% | A formatted version of milliseconds spent on the server. | 1h 30m 4s
%banned% | `<span class="color_4">Banned</span>` or nothing. |
%op% | ', Operator (Op)' or nothing |
%isonline& | `| <span class="color_2">Online</span>` or `| <span class="color_4">Offline</span>`
%deaths% | Number of deaths. | 24
%playerkills% | Number of Player kills the user has (Size of KillData list) | 14
%sessionstable% | Old feature, no longer in use. |
%sessionaverage% | A formatted version of the average length of all of the sessions. | 10m 23s
%killstable% | Table containing up to 10 of the most recent player kills. Example contains one line. | `<table class="sortable table"><thead><tr><th>Date</th><th>Killed</th><th>With</th></tr></thead><tbody><tr><td sorttable_customkey="324123421">FORMATTED_TIME</td><td>Rsl1122</td><td>DIAMOND_SWORD</td></tr></tbody></table>`
%version% | Version of the plugin | 3.2.5
%planlite% | Replaced with an empty string. Old feature. |
%dataweek% | Array containing users online numbers for last 7 days, used by the graph. | [0, 0, 1, 1, 1, 0, 0, 1, 0, 0]
%labelsweek% | Array containing formatted time labels corresponding the data array. | ["Feb 02 18:03:12", "Feb 02 18:06:32"]
%playersgraphcolor% | Color code for the online graph in the config. | ffffff
%playersgraphfill% | Color code for fill of the online graph in the config. | 000000
%gm0col% | Color of the SURVIVAL box in the config | ffffff
%gm1col% | Color of the CREATIVE box in the config | 000000
%gm2col% | Color of the ADVENTURE box in the config | ffffff
%gm3col% | Color of the SPECTATOR box in the config | 000000
%datapunchcard% | Data for the punch card graph | [{x:0, y:2},{x:1, y:2}]
%datasessiondistribution% | Data for the session length distribution graph | [54, 34, 12]
%labelssessiondistribution& | Labels for the session length distribution bars | ["0-5 min", "5-10 min", "10-15 min"]
%inaccuratedatawarning% | Replaced with a warning if the player has registered 3 minutes ago | `<div class="warn">Data might be inaccurate, player has just registered.</div>`
%plugins% | Content for the Plugins tab | `<div class="columns"><div class="about box column">CONTENT</div><div class="about box column">CONTENT</div></div>`
## Analysis placeholders
Placeholder | Description | Example
---------- | ------------------------------------- | -----
%currenttime% | Server epoch ms, used for clock. | 1496486156
%refreshlong% | Epoch ms of last refresh (server time) | 1496486156
%gm0% | Total percentage all players have spent in SURVIVAL | 66%
%gm1% | Total percentage all players have spent in CREATIVE | 19%
%gm2% | Total percentage all players have spent in ADVENTURE | 10%
%gm3% | Total percentage all players have spent in SPECTATOR | 5%
%active% | Number of [Active](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/utilities/AnalysisUtils.java#L27) players | 4
%inactive% | Number of Inactive players. | 43
%banned% | Number of Banned players. | 5
%joinleaver% | Number of players who have only joined once | 100
%activitytotal% | Total number of players in the database. | 152
%npday% | Number of new players who have joined in the last 24h | 5
%npweek% | Number of new players who have joined in the last 7d | 13
%npmonth% | Number of new players who have joined in the last 30d | 53
%commanduse% | Table format lines for commands & times used, sorted to descending order. | `<tr><td><b>/spawn</b></td><td>42</td></tr><tr><td><b>/plan</b></td><td>4</td></tr>`
%totalcommands% | Number of unique commands used | 2
%avgage% | 'Not Known' or an average of known user ages. | 14.5
%avgplaytime% | Formatted average playtime of all players. | 1h 30m 4s
%totalplaytime% | Formatted total playtime of all players. | 4d 2h 43m 5s
%op% | Amount of Operators on the server | 1
%refresh% | Formatted time since Epoch second of the last refresh. | 4m 5s
%totallogins% | Total number of logins of all players | 342
%top20mostactive% | Not in use, old feature. | Error: Replace rule was not set
%recentlogins% | Buttons with links to the inspect pages of most recent players | `<p><a class="button" href="http://localhost:8804/bAkEd/player/Rsl1122">Rsl1122</a> </p>`
%deaths% | Total amount of deaths for all players | 43
%playerkills% | Total amount of player kills | 32
%mobkills% | Total amount of mobs killed | 432
%sessionaverage% | Formatted time amount of the average session length | 4m 30s
%version% | Version of Plan | 3.2.0
%planlite% | Replaced with an empty string. Old feature. |
%uniquejoinsday% | Replaced with number of unique players | 5
%uniquejoinsweek% | Replaced with number of unique players | 47
%uniquejoinsmonth% | Replaced with number of unique players | 234
%avguniquejoins% | Replaced with number of average joins / day | 56
%avguniquejoinsday% | Replaced with number of average joins / day in last 24h | 56
%avguniquejoinsweek% | Replaced with number of average joins / day in last 7d | 60
%avguniquejoinsmonth% | Replaced with number of average joins / day in last 30d | 59
%sortabletable% | Multi column table containing all players | [Created with this code](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/ui/tables/SortablePlayersTableCreator.java)
%dataday% | Data for 24h online activity | [0, 0, 0, 0, 1]
%dataweek% | Data for 7d online activity | [0, 0, 0, 0, 1]
%datamonth% | Data for 30d online activity | [0, 0, 0, 0, 1]
%labelsday% | Labels for each point on 24h graph | [FORMATTED TIMESTAMPS]
%labelsweek% | Labels for each point on 7d graph | [FORMATTED TIMESTAMPS]
%labelsmonth% | Labels for each point on 30d graph | [FORMATTED TIMESTAMPS]
%activitydata% | Data for the sectors on the activity pie | [32, 43, 3, 2]
%labelsactivity% | Labels for the sectors of activity pie | ["Active", "Inactive", "Unknown", "Banned"]
%geomapcountries% | Country Array for Chloropleth map | [...]
%geomapcodes% | Country code Array for Chloropleth map | [...]
%geomapz% | Number array for Chloropleth map | [...]
%gmdata% | Data for the sectors on the gm usage pie | [43242, 432423421, 35345, 5432534]
%gmlabels% | Labels for the sectors of gm pie. | ["Survival", "Creative", "Adventure", "Spectator"]
%activecol% | Color of the ACTIVE sector in config | ffffff
%inactivecol% | Color of the INACTIVE sector in config | 000000
%joinleavecol% | Color of the UNKNOWN sector in config | ffffff
%bancol% | Color of the BANNED sector in config | 000000
%playersgraphcolor% | Color code for the online graph in the config. | ffffff
%playersgraphfill% | Color code for fill of the online graph in the config. | 000000
%gm0col% | Color of the SURVIVAL box in the config | ffffff
%gm1col% | Color of the CREATIVE box in the config | 000000
%gm2col% | Color of the ADVENTURE box in the config | ffffff
%gm3col% | Color of the SPECTATOR box in the config | 000000
348e0f | Light color of green to be replaced with config value Main | ffffff
267F00 | Darker color of green to be replaced with config value MainDark | 000000
5cb239 | Lighter color of green to be replaced with config value Secondary | ffffff
89c471 | Lightest color of green to be replaced with config value Tertiary | 000000
5da341 | Darker color of green to be replaced with config value TertiaryDark | ffffff
%plugins% | Content for the Plugins tab | `<div class="columns"><div class="about box column">CONTENT</div><div class="about box column">CONTENT</div></div>`

30
documentation/Localization.md
View File

@ -1,30 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Localization
This article will tell you how you can change the messages seen in the plugin.
(Introduced in version 2.5.0 & Revamped in 3.6.2)
By Default Plan uses internal Locale found inside Locale.java (Config setting: default)
- [Locale](https://github.com/Rsl1122/Plan-PlayerAnalytics/blob/master/Plan/src/main/java/com/djrapitops/plan/locale/Locale.java)
## Config setting
In the config, there is a setting for Locale.
Setting this to, for example FI, (Finnish) will attempt to use locale from inside the plugin jar.
Inside the plugin there are multiple locale files.
You can generate a new locale (default values) by setting the config setting **WriteNewLocaleFileOnStart** to true.
This will generate a locale.txt to the plugin's folder & that will be used when present.
To change the messages, only change the parts on the right, left ones are identifiers.
Some messages in the html pages are not loaded from the text file, and need to be changed seperately.
This can be done by copying the html files from the .jar to the plugin folder and editing them.
- [Available Locales](https://github.com/Rsl1122/Plan-PlayerAnalytics/tree/master/Plan/localization)
## End
If you want to help me out with localizing the plugin to your language, you can translate the locale file to your language and send the contents to me in one way:
- Do a pull request
- [Open an issue](https://github.com/Rsl1122/Plan-PlayerAnalytics/issues)
- [Send me private message on spigot](https://www.spigotmc.org/members/rsl1122.122894/)

86
documentation/ManageCommandGuide.md
View File

@ -1,86 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Manage-command Guide
![Manage Help in 3.1.0](http://puu.sh/vQAaV/41ea052a5d.jpg)
*/plan manage-command*
# Commands
## /plan manage move
This command can be used to move all data from one database to another. This is useful when you have had Plan installed for a while, but have not had MySQL available.
The command moves all data from one database to another & overwrites all values in the destination database.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<fromDB>` | Yes | sqlite / mysql | The database the data will be moved from. Database will stay unaffected.
`<toDB>` | Yes | sqlite / mysql | The database the data will be moved to. Old data in the database will be removed.
[-a] | No | -a | Confirmation argument, Required for change to occur.
## /plan manage backup
This command can be used to backup all data from a database into a separate .db file.
The name of the new file depends on the database & date. For example mysql-backup-Feb-11.db or sqlite-backup-Mar-12.db
The database file will use SQLite save format.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<DB>` | Yes | sqlite / mysql | The database the data will be backed up from. Database will stay unaffected.
## /plan manage restore
This command can be used to restore data from a backup file.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<Filename.db>` | Yes | Anything | The filename of the backup database file.
`<toDB>` | Yes | sqlite / mysql | The database the data will be restored to. Old data in the database will be removed.
[-a] | No | -a | Confirmation argument, Required for change to occur.
## /plan manage hotswap
This command restarts the plugin and changes the config value of database.type to the given argument.
If connection to the given database fails the command is cancelled & plugin is not restarted.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<DB>` | Yes | sqlite / mysql | The database the config value should be changed to.
## /plan manage status
Used to check what database is in use (Active Database)
## /plan import
This command can be used to import data from other plugins into the Plan database.
A revamp of the system is coming in 3.2.0.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<plugin>` | Yes | A supported plugin's name | Plugin where data should be imported from
[-a] | No | -a | Confirmation argument, Required for change to occur.
### Supported plugins
Plugin | What is done
-- | ----
OnTime | Playtime is imported & Gamemode times table is reset for affected players (Gamemode time calculation is dependent on playtime.)
## /plan manage remove
Removes all data of a player from the database.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<player>` | Yes | Playername | Player whose data should be deleted.
[-a] | No | -a | Confirmation argument, Required for change to occur.
## /plan manage clear
This command is used to completely empty a database. It uses DROP TABLE queries so everything goes.
Argument | Required | Accepted values | Description
-- | -- | -- | ----
`<DB>` | Yes | sqlite / mysql | Database all data will be cleared from.
[-a] | No | -a | Confirmation argument, Required for change to occur.

BIN
documentation/Plan-3.1.0-Class Diagram.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 503 KiB

36
documentation/StoredData.md
View File

@ -1,36 +0,0 @@
![Player Analytics](https://puu.sh/t8vin.png)
# Stored Data & Data format
This Article is about the information stored in the Database.
Page version: **3.6.0**
## Stored Data & Format
Data | Format in DB | Location in DB | Description
-- | -- | ---- | --
UUID | varchar | plan_users | UUID of the player, used for saving & processing all the information
Age | integer | plan_users | Age of the player, gathered from chat. -1 if not known
Gender | varchar | plan_users | String representation of the [Gender Enum](/Plan/src/main/java/com/djrapitops/plan/api/Gender.java)
Geolocation | varchar | plan_users | Geolocation of the player
Last Gamemode | varchar | plan_users | Last Gamemode the user was seen in. Used for GMTime calculations.
Last GM Swap Time | bigint | plan_users | Playtime ms the user swapped their gamemode. Used for GMTime calculations.
Playtime | bigint | plan_users | Total playtime of the player
Login Times | integer | plan_users | How many times the player has joined.
Last Played | bigint | plan_users | Last time the player's data was processed, used for Playtime calculations
Register Date | bigint | plan_users | Bukkit's Register date
Banned | boolean | plan_users | Bukkit's Ban value
OP | boolean | plan_users | Bukkit's OP value
Nicknames | varchar | plan_nicknames | All the nicknames the player has used
Last nickname | boolean | plan_nicknames | The last nickname known stated as a boolean.
IPs | varchar | plan_ips | InetAddress the player connected from
GM Times | bigint | plan_gamemodetimes | Time spent in each Gamemode
Locations | integer, integer, String | plan_locations | X, Z & World name the player has visited.
Mob kills | integer | plan_users | Mobs the player has slain
Deaths | integer | plan_users | How many times the player has died
Player kills & Weapon used | integer, varchar, bigint, string | plan_kills | User the player killed, the time of the kill & the name of MATERIAL of the weapon.
SessionData (Start & End of session) | bigint, bigint | plan_sessions | Used for all sorts of activity calculation.
Command Usage | varchar | plan_commandusages | Each base command & how many times they have been used.
World times | bigint | plan_world_times | World Playtimes
World names | varchar(255) | plan_worlds | All names worlds have appeared as.
Player Online is determined by the data being in the DataCache.