<center>
  <img src="https://playerlist.astrea.cc/_static/rpl_banner.min.jpg" width="700">
</center>

<center>
  A bot that helps out owners of Minecraft: Bedrock Edition Realms by showing various statistics related to player join/leaves.
</center>

It's:
- 🚀 **Fast:** Under the right (and typical) circumstances, it can send a list of ~300 players in under 2 seconds, most of which (~1.5 seconds) is spent just sending messages to Discord.
- 📊 **Informative:** The main feature of the bot, the playerlist, can give a detailed log of players on a Realm at a moment's notice. You can also get a breakdown for an individual player to analyze as you wish.
- 👌 **Easy to Use**: Simply add the bot, link your Realm, and you already have join/leave tracking enabled - no need to use your Xbox account for the bot's features. Take a look at the [Server Setup Guide](https://playerlist.astrea.cc/wiki/server_setup) for more information.
- 🔓 **Open Source**: The code is available to the public and able to be audited and learned from. Dedicated users can even self-host the bot, if they wish.

## Features

### The Playerlist
Of course, this is the main feature of the bot. It's also one of those features that is easier to show than tell:

<center>
  <img src="https://playerlist.astrea.cc/_static/playerlist.png" alt="Picture of how the playerlist looks like." width="550">
  <figcaption>The censored space are gamertags of users on the Realm.</figcaption>
</center>

The command version allows you to get who was on the Realm up to the last 24 hours (though it defaults to 12 hours). There is also an automatic version that runs every hour in a specified channel (as seen in the picture) - it displays a list going back an hour, every hour.

The command can normally only be run by people with Manage Server permissions (can be adjusted the same way you adjust other slash command permissions) and is not meant to be seen by normal people. However, normal users, by default, can run `/online`, which shows everyone who is on the Realm at that moment:

<center>
  <img src="https://playerlist.astrea.cc/_static/online.png" alt="Picture of how /online looks like." width="450">
</center>

### Specific Player Information

You can also request for a breakdown of join/leaves (otherwise known as sessions) via `/get-player-log`:

<center>
  <img src="https://playerlist.astrea.cc/_static/get_player_log.png" alt="Picture of how /get-player-log looks like." width="550">
</center>

Using this command allows you to scroll through each session in an intuitive format. For fun, the command also displays their total playtime.

By default, the command only goes back a day, but it can go till 7, as seen here.

### Realm Offline Notifications

Realms go offline a lot if they're big, most likely because they can't handle the load. Sometimes, it can be useful to get pinged when that happens:

<center>
  <img src="https://playerlist.astrea.cc/_static/realm_offline.png" alt="Picture of how Realm offline notifications looks like.">
  <figcaption>Note: despite the role name used, this does not exclusively trigger when the Realm crashes.</figcaption>
</center>

This simply hooks onto your autorunning playerlist. The Realm offline detection is mostly accurate - it may not work as well for smaller Realms, but for larger ones, it should work fine.

### Playtime Leaderboard

By using `/leaderboard` and either voting or purchasing Premium, you can get a ranked list of players by playtime for your Realm:

<center>
  <img src="https://playerlist.astrea.cc/_static/leaderboard.png" alt="Picture of how /leaderboard looks like." width="350">
  <figcaption>Note: the playtimes are rounded for convenience, and so may be slightly off.</figcaption>
</center>

The period of time can be adjusted as needed - it can go all the way back to 30 days.

### Graphs

You can make cool graphs about your Realm and its users:

<center>
  <img src="https://playerlist.astrea.cc/_static/realm_chart.png" alt="Picture on how graphs can looks like." width="550">
</center>

There are a variety of options to chose from, from the graph up above to a day-to-day breakdown. The data isn't 100% accurate, but you can use it to observe patterns... or just show it off for fun.

### Premium

**Realms Playerlist Premium** allows for extra features that otherwise could not be provided by the bot without funding. [Take a closer look at Premium here.](https://playerlist.astrea.cc/wiki/premium)

#### Live Playerlist

Instead of making the bot send a summary of people on every hour, a **live playerlist** shows who joined and left a Realm every minute, basically making it a live join/leave logger.

It looks something like this:

<center>
  <img src="https://playerlist.astrea.cc/_static/live_playerlist.png" alt="Picture on how live playerlist looks like." width="420">
</center>

This has a variety of uses, from statistical to moderation - it's really up to you what you do with this information. Some Realms use it both to narrow down subjects to a precise degree while also tracking active Realm times. Using Discord's search functionality, the possibilities are near endless.

#### Live Online List

Taking the live playerlist to its logical conclusion, a **live online list** is a message that constantly updates with the players currently on the Realm, as seen below:

<center>
  <img src="https://playerlist.astrea.cc/_static/live_online_list.webp" alt="Animated picture on how the live online list looks like." width="500">
</center>

As of right now, this feature requires the live playerlist to also be enabled.

#### Device Information

Through an extra toggle, the bot can fetch and display device information whenever a user is online. This affects `/online`, the normal playerlist, and the live playerlist.

For example, `/online` becomes this:

<center>
  <img src="https://playerlist.astrea.cc/_static/fetch_devices.png" alt="Picture on how `/online` looks when the toggle is enabled." width="420">
</center>

This does slow the bot down a bit when fetching the device, and privacy settings may make some users not have information regardless, but can used as an extra moderation/statistical tool.

This is also available as a toggle to non-Premium users of `/online` (and only `/online`) if they vote for the bot.

#### Realm Session Export

You can export your Realm's session data (a session being a period of time where the player was on a Realm, including when they joined and were last seen) for around the last 30 days to a CSV file, which can be opened in a spreadsheet program like Excel or Google Sheets. This can be used to make your own graphs (though some fiddling around will be needed), or just to have the data for yourself.

<center>
  <img src="https://playerlist.astrea.cc/_static/export_data.png" alt="Picture on how that data is sent." width="750">
</center>

## Adding The Bot

If you wish to add this bot, just [use the Server Setup Guide on how to do so](https://playerlist.astrea.cc/wiki/server_setup). It'll give a basic rundown on how to set up the bot, as well as showing how to set basic options.

## FAQ

There's a whole section in the wiki about this! [Check it out here](https://playerlist.astrea.cc/wiki/faq).

*The Realms Playerlist Bot is not an official Minecraft product, and is not approved by or associated with Mojang or Microsoft.*

Realms Playerlist Bot

A bot that helps out owners of Minecraft: Bedrock Edition Realms by showing various statistics related to player join/leaves.

Voting for Realms Playerlist Bot