Plan - Data Available

Apr 16, 2020
Plan - Data Available
  • This article is out of date, as it covers version 2.x.x
    See Github Wiki for more up to date information

    This wiki article is a detailed description of what data Plan gathers, how it is gathered & how it is visualized.

    Inside Plan, there are 5 listeners: Chat Listener, Command Listener, Gamemode Change Listener, Move listener and Player Listener.
    When an event is fired in one of these listeners, it is passed onto multiple Handlers that process the information stored in that event.

    When a player joins, their data is fetched from the database (or created if the player is not in the database), and put into a Cache.
    This Cache is used by the Handlers to save the data without putting more strain on the database.
    This Cached Data is saved periodically and when the player leaves.

    Stored data
    The Database stores most data that is visualized in the plugin.
    It contains following information about a player:

    • UUID (Used for saving)
    • Age
    • Gender
    • Geolocation
    • Last Gamemode & Last GM Swap time
    • Play time
    • Login times
    • When the player Last Played
    • Nicknames
    • IPs
    • Times spent in each gamemode
    • Locations where players have been at
    • Mob kills & Deaths (number)
    • Player kills & weapon used
    • Session data on start and end of each session
    • Command usage
    Rest of the information is taken from Bukkit's player data:
    • When the player Registered
    • Is the player banned
    • Is the player Opped
    • Is the player online
    Gathering the data
    Most of the data is just added to the cache by updating the value, and here I will only go in detail about the most interesting ones.

    Times spent in each gamemode
    The time spent in each gamemode is dependent on the playtime, as it is calculated via the difference of the current playtime, and the Last GM Swap time.
    When a player swaps gamemode, the current playtime is updated & time is added to the Last Gamemode. After that the needed values for the next change are saved.

    Demographics data (Age, Gender, Geolocaton)
    Geolocation is gathered using the free web service of, and the information is read from the csv file inputstream recieved from the address for the ip.

    Age & Gender are gathered from the chat.
    When a message contains a trigger word (config), Demographics Handler attempts to see if it contains numbers. Any numbers between 1 and 100 are accepted as the player's age.
    Then Demographics Handler checks if the message contains gender trigger and acts accordingly.
    Before any of this, the Handler checks if the message contains any of the ignore words, and ignores the message if it is the case.

    Session data is saved when the player leaves. When the player joins, the time is put to Current Sessions-List and after he leaves the end time is put to the session and session is saved.

    Displaying the data
    To Display the data, there is a separate cache called InspectCache. When a command like /plan inspect/search/analyze is used, the UserData is copied from Cache if it is cached, or from the database.

    Then a link is given to the user.

    How to read the information
    Information is shown in the analysis window as couple graphs and lists. Let's look at each graph and what they will tell you
    Player activity graph
    This graph shows how many players were online, and when. Above it is the amount of new players who joined during that period.
    New Players are determined from the registration date, and online players are calculated from every player's SessionData.
    There are 3 graphs for 3 different scopes, last 24h, 7d and 30d.
    You can hover over the graph to see when the peak times happen.

    Playerbase composition piechart
    This chart visualizes how active your playerbase is.
    Activity is calculated with the last login of players, how long they have been online, and how many times they have logged in.
    If they have logged in just once, activity can not be determined, and thus the player is put to the Unknown part. This part grows if many players join and never return.
    If a player has logged in 3 times, and has played in the last 2 weeks, they are considered active. Otherwise they are deemed inactive.

    Gamemode Usage piechart
    This graph shows how much of the playtime has been spent in each gamemode.
    It is quite useful if you're running a multi-world with survival and creative worlds.
    The Player inspect page shows the exact time the player has played in a gamemode.


    Players list

    This list shows most important data about each player, like registration date, last seen date, time they have been online, whether or not they are active and so on.
    The list can be sorted by clicking the header.

    Command Usage

    Command usage table shows every base command and how often they have been issued. This list can also be sorted

    Inspect Page
    Inspect page contains more in depth information about each player. It also contains tables of Last 10 Play sessions, Last 10 kills and Online activity graph for the last 7 days.

    For Developers
    If you're more interested in the coding aspect of this data, all code is available on Github.
    Data saving and gathering is done here:
    Github/Plan/Data (Database stuff elsewhere).
    Analysis of Data is done here: Github/Plan/Utils
    Data for graphs is created here: Github/Plan/UI/Graphs
    The Graphs are generated using Chart.js javascript library

    Displaying the data is done by swapping placeholders in a template Html with the placeholders that are here: Github/Plan/Utils/PlaceholderUtils
  • Loading...
  • Loading...