Configuration
The config is plugins/xStats/config.yml, written on first start. Apply changes with /xstats reload; only storage, server-name and network need a restart.
| Section | What it covers |
|---|---|
theme |
The prefix and colours xStats’ messages share: see the theme. |
messages |
What players are told, and shared errors under messages.error. |
commands |
/stats and /leaderboard: on or off, their aliases and permission. |
stats |
The stats xStats keeps, where each comes from, and which have periods: see Choosing stats. |
collecting |
How often to save, how many players to read each tick, AFK-aware playtime, and the first-start import. |
leaderboards |
Places kept, leaving banned players out, /leaderboard’s page size, and how boards in the world look. |
periods |
The time zone, the day weeks start, how long each day’s numbers are kept, and the periods’ names. |
web |
The website and its API: see The website. |
server-name |
This server’s name in the database, for networks. |
storage |
SQLite in the plugin’s folder (stats.db), or MySQL/MariaDB. |
network |
Several servers sharing one database: see Networks. |
update-checker |
Checks Modrinth for a new version once a day: Privacy. |
Saving
Section titled “Saving”Every collecting.save-every-minutes (5), xStats reads every online player’s stats, collecting.reads-per-tick (4) players a tick, writes what changed, and works out every leaderboard. Reading is a lookup in counters the server already keeps; a stat that adds up every block or item (mined:*) looks at each one, so it’s the costliest kind. Lower reads-per-tick to spread a save over more ticks on a very full server.
A crash loses at most one save’s worth of playtime and placeholder stats. Minecraft’s own stats aren’t lost: the next reading makes up the difference.
A bad value falls back to its default with a warning in the console.
The full default config
Section titled “The full default config”# xStats: player stats, leaderboards and a website.# Docs: https://docs.xenastudios.co/xstats/configuration/## Apply changes with /xstats reload. A bad value falls back to its default with a# warning in the console; xStats never stops over config. All text is MiniMessage:# https://docs.xenastudios.co/start/formatting/
# Managed by the plugin, to carry your settings forward on updates. Don't edit it.config-version: 1
# The look xStats' messages share. The default messages use these as tags, so changing# a colour here restyles them all. Write a style as MiniMessage tags: <gray>,# <#3EC407>, or <gold><bold>.theme: # <prefix> starts the default messages. Make it your server's name, such as # "<dark_gray>[<gradient:#B48CFF:#5EE08A>MyServer</gradient>]</dark_gray> ", or blank for none. prefix: "<#3EC407>»</#3EC407> " # The colour of message text that has no tag of its own. base: "<gray>" # <highlight>: names and values, such as a player or a speed. highlight: "<#3EC407>" # <success>: something turned on or done. success: "<#5EE08A>" # <error>: something refused or turned off. error: "<#FF6B6B>"
# What players are told.messages: error: # The console or a command block ran a command only players can use. player-only: "<prefix><error>Only players can use this command." # The sender lacks the command's permission. no-permission: "<prefix><error>You don't have permission to do that." # No online player has that name. <player> is the name typed. player-not-found: "<prefix><error>No player named <highlight><player></highlight> is online." # The command was typed wrong. <usage> is how to type it. usage: "<prefix><error>Usage:</error> <usage>" # The command hit an error. The console has the details. failed: "<prefix><error>Something went wrong. The console has the details." # /stats. <player> is whose; <first-join> and <last-seen> are when; <playtime> and <kd> # (kills per death) are filled in when the playtime, kills and deaths stats exist. profile-header: "<prefix><highlight><player></highlight>'s stats <dark_gray>·</dark_gray> joined <white><first-join></white>, last seen <white><last-seen></white>" # One stat. <stat>, <value>, and <rank>: their place on the all-time board, or blank. profile-line: " <gray><stat>:</gray> <white><value></white><rank>" # How <rank> looks when they have one. profile-rank: " <dark_gray>#<rank></dark_gray>" # A section another plugin adds. <title> is its heading. profile-section: "<prefix><highlight><title>" # One of its lines: <label> and <value>. profile-section-line: " <gray><label>:</gray> <white><value>" # After the stats, when web.public-url is set. <url> is their page. profile-link: "<prefix><click:open_url:'<url>'><hover:show_text:'Open in your browser'><highlight><underlined>See it on the website</underlined></highlight></hover></click>" # <player> is the name typed. never-joined: "<prefix><error><highlight><player></highlight> has never played here." private-on: "<prefix><success>Your stats are hidden</success> from the website. Leaderboards in game still show you." private-off: "<prefix>Your stats are <highlight>on the website</highlight> again." # /leaderboard. <stat>, <period>. top-header: "<prefix><highlight><stat></highlight> <dark_gray>·</dark_gray> <period>" # <rank>, <player>, <value>. top-line: " <gray><rank>.</gray> <white><player></white> <dark_gray>-</dark_gray> <highlight><value>" # The line for the player reading it, when they're on the page. top-line-self: " <highlight><rank>. <player></highlight> <dark_gray>-</dark_gray> <highlight><value>" top-empty: "<prefix>Nobody's on this leaderboard yet." # <stat> is what was typed; <stats> the ones there are. unknown-stat: "<prefix><error>There's no stat called <highlight><stat></highlight>.</error> Try: <stats>" # <stat> has no daily, weekly or monthly numbers. no-periods: "<prefix><error><highlight><stat></highlight> is only counted all time." # Under a page of /leaderboard. See the docs for <next> and <previous>. page-footer: "<gray>Page <page> of <pages></gray><has_previous> <click:run_command:'<previous>'><hover:show_text:'<previous>'><highlight>« Previous</highlight></hover></click></has_previous><has_next> <click:run_command:'<next>'><hover:show_text:'<next>'><highlight>Next »</highlight></hover></click></has_next>" # Before the database is open, just after startup. not-ready: "<prefix><error>Stats are still loading. Try again in a moment."
# The commands players use. Blank permission means everyone may.commands:
# /stats [player]: a player's stats. /stats private hides your own from the website # (xstats.private, everyone has it). stats: enabled: true aliases: [] permission: ""
# /leaderboard <stat> [daily|weekly|monthly|all] [page]: a leaderboard. Without # xUtilities, whose /top this would clash with, you can add top to its aliases. leaderboard: enabled: true aliases: ["lb"] permission: ""
# The stats xStats keeps, in the order /stats and the website show them. Each has:# name: what players see.# source: where the numbers come from:# one of Minecraft's own stats, as /scoreboard names them: player_kills, jump,# mined:diamond_ore, killed:zombie, crafted:* (every item). Add several with +.# xstats:playtime (time online, not counting time standing still with the camera# unmoved) or xstats:sessions (times joined).# papi:%placeholder%: a PlaceholderAPI value, such as papi:%vault_eco_balance%,# read every save and when the player leaves.# unit: auto, count, time, distance or damage. auto works it out from the source.# decimals: for papi values with decimals, such as 2 for a balance.# periods: also count it per day, week and month, for leaderboards and the website.# Each day a player's stat changes is one row in the database, so only turn it on# for stats you want leaderboards of.# in-game: show it on /stats and /leaderboard. Placeholders always work.# website: show it on the website and in the web API.# An id is 1 to 32 lowercase letters, digits and _. Placeholders use it: %xstats_kills%.stats: playtime: name: "Playtime" source: "xstats:playtime" unit: "auto" decimals: 0 periods: true in-game: true website: true sessions: name: "Sessions" source: "xstats:sessions" unit: "auto" decimals: 0 periods: false in-game: true website: true kills: name: "Player kills" source: "player_kills" unit: "auto" decimals: 0 periods: true in-game: true website: true deaths: name: "Deaths" source: "deaths" unit: "auto" decimals: 0 periods: true in-game: true website: true mob_kills: name: "Mobs killed" source: "mob_kills" unit: "auto" decimals: 0 periods: true in-game: true website: true blocks_mined: name: "Blocks mined" source: "mined:*" unit: "auto" decimals: 0 periods: true in-game: true website: true distance: name: "Distance travelled" source: "walk_one_cm + sprint_one_cm + crouch_one_cm + swim_one_cm + walk_on_water_one_cm + walk_under_water_one_cm + climb_one_cm + fly_one_cm + aviate_one_cm + horse_one_cm + boat_one_cm + minecart_one_cm + pig_one_cm + strider_one_cm + happy_ghast_one_cm + nautilus_one_cm" unit: "auto" decimals: 0 periods: true in-game: true website: true fish_caught: name: "Fish caught" source: "fish_caught" unit: "auto" decimals: 0 periods: true in-game: true website: true jumps: name: "Jumps" source: "jump" unit: "auto" decimals: 0 periods: false in-game: true website: true damage_dealt: name: "Damage dealt" source: "damage_dealt" unit: "auto" decimals: 0 periods: false in-game: true website: true animals_bred: name: "Animals bred" source: "animals_bred" unit: "auto" decimals: 0 periods: false in-game: true website: true villager_trades: name: "Villager trades" source: "traded_with_villager" unit: "auto" decimals: 0 periods: false in-game: true website: true items_enchanted: name: "Items enchanted" source: "enchant_item" unit: "auto" decimals: 0 periods: false in-game: true website: true raids_won: name: "Raids won" source: "raid_win" unit: "auto" decimals: 0 periods: false in-game: true website: true
# How stats are read and saved.collecting: # Minutes between saves. Each save reads online players' stats, a few each tick, # writes what changed, and works out every leaderboard. A crash loses at most this # much of playtime and placeholder stats; Minecraft's own stats are never lost. save-every-minutes: 5 # Players read per tick during a save. Lower spreads a save over more ticks. reads-per-tick: 4 # Leave out of playtime the minutes a player didn't move their camera at all, as when # they're away from the keyboard. Checked at each save, by comparing where they look. afk-aware: true # On first start, read every player's history from the world's stats folder, so # leaderboards aren't empty on day one. /xstats import runs it again. import-on-first-start: true
leaderboards: # Places kept on each leaderboard: for /leaderboard, placeholders and the website. size: 100 # Leave players banned with /ban out of leaderboards. Players with # xstats.leaderboard.exclude are always left out, such as staff; nobody has it unless # given it, operators included. exclude-banned: true # Places on each page of /leaderboard. per-page: 10
# Leaderboards in the world: Paper text displays, placed with /xstats board. boards: # Places each in-world board shows. lines: 10 # The top line. <stat> and <period> are filled in. title: "<#3EC407><bold><stat></bold></#3EC407>\n<gray><period>" # Each place: <rank>, <player>, <value>. line: "<gray><rank>.</gray> <white><player></white> <#3EC407><value>" # When nobody is on it yet. empty: "<gray>Nobody yet"
# Days, weeks and months, for daily, weekly and monthly leaderboards.periods: # The time zone days start in, such as Europe/London or America/New_York. Blank uses # the server's own. timezone: "" # The day weeks start on. week-starts: "monday" # Days to keep each day's numbers. Older days are added into their month, so monthly # and all-time numbers stay right while the database stays small. keep-daily-days: 90
# How periods are named to players. names: daily: "Today" weekly: "This week" monthly: "This month" all: "All time"
# The stats website and its JSON API, served by xStats itself on its own port. Off until# you turn it on: see https://docs.xenastudios.co/xstats/website/ for safe setups,# behind a reverse proxy or a tunnel.web: # Serve the website and the API. enabled: false # The address to listen on. 0.0.0.0 is every network the machine has; 127.0.0.1 only # this machine, for a reverse proxy or tunnel on the same machine. bind: "0.0.0.0" # The port. On a shared host, use a port your host gave the server (an extra # allocation), or put the site behind your own domain with a tunnel. port: 8804 # The site's address as players open it, such as https://stats.example.com. /stats links # to it, and /xstats web export writes it into the files. Blank leaves the link out. public-url: "" # Serve the website itself. Off serves only the JSON API, for a site hosted elsewhere. site: true # Sites hosted elsewhere that may read the API from a visitor's browser, such as # https://example.com. "*" lets any site. cors-origins: ["*"] # Requests one visitor may make each minute. A visit to a page is a few; more are # answered 429 until the minute is up. Players' heads have a limit of their own, five # times this, since a leaderboard shows many. requests-per-minute: 120 # Requests handled at once. More wait for a moment, then get 503. max-concurrent: 32 # Addresses of your reverse proxy or tunnel, or ranges such as 173.245.48.0/20. # Requests from them are counted against the visitor's address the proxy passes on # (in client-ip-header) instead, so the rate limit is per visitor. Leave it empty when # visitors connect directly. trusted-proxies: [] # The header a trusted proxy puts the visitor's address in. X-Forwarded-For suits # nginx, Caddy and most tunnels. CF-Connecting-IP only if Cloudflare is the proxy # listed above, or the one in front of it with nothing reaching yours another way: # visitors can send any header themselves, and only Cloudflare replaces this one. client-ip-header: "X-Forwarded-For" avatars: # Where players' heads come from: {uuid}, {name} and {size} are filled in. The default # is mc-heads.net; https://crafatar.com/avatars/{uuid}?size={size}&overlay works too. url: "https://mc-heads.net/avatar/{uuid}/{size}" # Fetch heads through xStats and keep them, so visitors' browsers never contact the # service above. Heads are kept in memory for a day. proxy: false
# How the site looks. branding: # The site's title, such as your server's name. Blank shows "Server stats". name: "" # A line under the title. Blank for none. tagline: "" # A logo: a link (https://...), or a PNG, JPEG, SVG or WebP file in plugins/xStats/web/, # such as logo.png. Blank for none. logo: "" accent: "#3ec407" background: "#0f1419" surface: "#1a222b" text: "#e6edf3"
# This server's name in the database, for networks: each server's stats are kept apart# under it and added up for the network. Letters, digits, - and _.server-name: "main"
# Where stats are kept. sqlite needs nothing set up. Use mysql for a network, so every# server shares one set of stats and one website. A change here applies on restart.storage: # sqlite keeps everything in one file in the plugin's folder, with nothing to set up. # mysql (or MariaDB) is for networks, or servers with a lot of history. type: "sqlite" # Put in front of every table's name, so plugins and servers can share one database. table-prefix: "xstats_"
# Only for type: mysql. mysql: host: "localhost" port: 3306 database: "minecraft" username: "minecraft" password: "" # Extra connection settings, as in a JDBC URL: useSSL=true&serverTimezone=UTC. properties: ""
# For servers sharing one MySQL database: each server hears about the others' saves# and /stats private, and its leaderboards count the whole network.network: # On when several servers share this plugin's MySQL or MariaDB database, so a change # made on one (a ban, a payment) reaches the others within a few seconds. # Leave it off for a single server: it does nothing on SQLite. enabled: false # Seconds between checks for the other servers' changes. check-every: 3
# Tells you when a new version is out.update-checker: # Ask Modrinth for the newest version at startup and every 24 hours. It sends # only the plugin version, the platform and the Minecraft version. enabled: true # Logged, and shown to admins when they join, when a newer version is out. # <plugin>, <current>, <latest> and <url> are filled in. message: "<prefix><plugin> <highlight><latest></highlight> is out (you have <current>): <click:open_url:'<url>'><hover:show_text:'Open on Modrinth'><highlight><underlined><url>"