All documentation
Documentation

StrikeBoards

A StrikePractice addon that runs a full leaderboard website from inside your Minecraft server, with profiles, live fights, seasons and in-game stats.

v2.0.1 Spigot or Paper 1.8.8 or newer (built against 1.8.8, tested on Paper 1.21.8)Java 8 or newerStrikePractice (required)PlaceholderAPI (optional)One free TCP port for the website (default 8123)

Quick start

  1. Put StrikeBoards-2.0.1.jar in plugins/ next to StrikePractice and restart the server.
  2. Open http://<your-server-ip>:8123/ in a browser. If it does not load, open TCP port 8123 in your firewall.
  3. Set your branding in game: /sb set server-name My Server and /sb set server-ip play.myserver.net.
  4. Pick a look with /sb set theme neon (9 built-in themes) and add a logo with /sb set logo <image url>.
  5. For a domain or HTTPS, put Nginx, Caddy or Cloudflare in front and set web.public-url in config.yml.
  6. Players type /sb stats, /sb top and /web in game. Play a few ranked fights and watch the boards fill.

#What it does

StrikeBoards is an addon for StrikePractice. It starts a small web server inside your Minecraft server process and shows your StrikePractice stats on a real website: leaderboards for every stat and every ranked kit, player profiles with ELO charts, a Compare page, a Live fights page, a Kits page and seasons. There is no web host, PHP or database to set up.

It also adds in-game commands (/sb stats, /sb top, /leaderboardsite), PlaceholderAPI placeholders, announcements for new #1 players and win streaks, an optional Discord webhook, and a JSON API.

Read-only

StrikeBoards only reads StrikePractice stats. It never changes them. Resetting a season only clears what the website shows; a stats reset inside StrikePractice stays your job.

#Installation and requirements

Requirements

  • Spigot or Paper 1.8.8 or newer. The plugin is built against the 1.8.8 API and tested on Paper 1.21.8.
  • Java 8 or newer.
  • StrikePractice, installed and working. StrikeBoards will not load without it.
  • PlaceholderAPI is optional and only needed for the placeholders.
  • One free TCP port for the website. The default is 8123.

Install

  1. Put StrikeBoards-2.0.1.jar in your plugins/ folder and restart the server.
  2. Open http://<your-server-ip>:8123/ in a browser.
  3. Set your server name and IP with /sb set server-name My Server and /sb set server-ip play.myserver.net.
  4. For a domain or HTTPS, put Nginx, Caddy or Cloudflare in front of the site and set web.public-url. See the Domain and HTTPS section.
Port not reachable?

Many hosts only open the game port. Ask your host for a second port, or open 8123 in your firewall. You can change the port with web.port in config.yml.

Files the plugin creates

Path in plugins/StrikeBoards/What it is
config.ymlAll settings. Your edits are kept on update; new keys are added automatically.
messages.ymlEvery in-game message (game:) and every website string (site:).
web/The extracted website files.
themes/<name>/theme.cssYour own themes (you create these).
data/matches.ymlRecorded fight history.
data/elo-history.ymlELO chart data.
data/skins.ymlSkins captured when players join.
data/seasons.yml and data/seasons/Season counter and archived seasons.

#The website

Every page works on desktop and mobile. Press / anywhere on the site to jump to the player search, then use the arrow keys and Enter to pick a result.

PageURLWhat it shows
Home/Podium, status strip (online, in fights, in queue, players ranked, fights recorded), trending this week, recent fights and kit champions.
Leaderboards/#/leaderboard/<board>One board with tier badges, a 7 day ELO change column, a Find box and paging.
Kits/#/kitsEvery ranked kit with its top 5 players.
Player profile/player/<name>ELO history chart, rank and top percent, win rate, recent form, ELO per kit, match history and season history.
Compare/#/compare/<a>/<b>Two players side by side with bars for each stat and kit, plus their head-to-head record from recorded fights.
Live fights/#/liveDuels happening right now, with both players, the kit, a ranked tag, a fight timer and the queue counts. Updates by itself.
Embed/embed/<board>?rows=10&theme=<name>A compact board without the menu, for iframes and OBS.

Shared /player/<name> links show the player's tier, ELO, wins and K/D in link previews such as Discord. Real skins work even on offline-mode servers, because StrikeBoards saves each player's skin when they join.

Turn home page parts on or off under site.sections (podium, status widget, search, top 3, quick links, footer links, recent fights, trending, kit champions).

#Boards, kits and tiers

Boards

Board ids you can use with /sb top, placeholders and the API: global-elo, kills, deaths, kd, wins, losses, wl, winstreak, eventwins, brackets, lms, sumo, juggernaut, party-vs-party, and kit:<KitName> for each ranked kit. ELO kits from StrikePractice are added automatically.

site:
  boards:
    order:
      - global-elo
      - kills
      - kd
      - wins
      - wl
      - winstreak
      - eventwins
      - brackets
      - lms
      - sumo
      - juggernaut
      - party-vs-party
      - deaths
      - losses
    # Hide boards by id (e.g. "deaths" or "kit:NoDebuff").
    hidden: []
    # Friendly display names, e.g. "party-vs-party": "2v2 Events"
    display-names: {}
    # Tab icons: board id or kit name -> emoji or image URL.
    icons: {}
    rows-per-page: 25

Kit names and icons

Map the raw kit id exactly as StrikePractice reports it (for example elo_gappleelo) to a friendly name. Legacy & codes and hex like &#ffaa00 work.

  kits:
    display-names:
      elo_gappleelo: "&6&lGapple"
      elo_nodebuffelo: "&#00e5ffNoDebuff"
    icons: {}
    default-icon: "⚔️"
    hide-unplayed: true

hide-unplayed: true hides kit ELO that is still at the StrikePractice starting ELO, so a player's kit bars only show kits they actually played.

ELO tiers

Players get the highest tier whose min-elo they reach (Global ELO, or the kit ELO on kit boards). Tiers show as colored badges on the site, in /sb stats and in %strikeboards_tier%. Rename, add or recolor tiers freely. To turn a built-in tier off, set its min-elo to -1, because deleted built-in tiers are added back on update.

tiers:
  enabled: true
  list:
    bronze:
      name: "Bronze"
      min-elo: 1
      color: "#c98a5a"
      chat-color: "&6"
    silver:
      name: "Silver"
      min-elo: 1050
      color: "#c8d3e8"
      chat-color: "&7"

The defaults continue with Gold (1150), Platinum (1250), Diamond (1400), Master (1600) and Champion (1800). color is the website color and chat-color is the in-game color code.

Hiding players

/sb hide <player> removes a player from every board, search and profile page. /sb unhide <player> brings them back after a refresh. The list is stored in site.hidden-players.

#Seasons

A season reset archives the current standings and starts the next season. Old seasons stay on the site for browsing, and each player profile keeps an end-of-season snapshot.

  • /sb season shows the current season and the finished ones.
  • /sb season reset [name] archives the top 100 rows of every board and starts a new season. The name can contain spaces.

If announcements.season-end.chat is on, the final top 3 of the configured boards is posted in chat. Archives are saved in data/seasons/season-<n>.yml.

This does not reset StrikePractice

The reset clears the cached boards on the website only. StrikeBoards never writes to StrikePractice. If you also want everyone's real ELO reset, do that in StrikePractice yourself.

#In-game commands for players

  • /sb stats [player] shows tier, ELO and rank, ELO change this week, wins and losses, K/D, win streak, event wins and the best 3 kits, with a clickable link to the profile.
  • /sb top [board] shows the top rows of a board (10 by default, set with commands.top-size, between 3 and 20). Click a name to see that player's stats. It also shows your own rank if you are outside the list. Press TAB for board names.
  • /leaderboardsite [player] (aliases /lbsite, /web) sends a clickable link to the site, or to a player's profile.
  • /sb info shows the site URL, cached player count, board count and season.

All of these messages are editable under game: in messages.yml.

#Announcements and Discord webhook

StrikeBoards can announce three things in chat and, optionally, to a Discord webhook: a new #1 on a board, a win streak milestone, and the final top 3 when a season ends. No announcements are sent while stats are still loading after a restart or a season reset.

announcements:
  new-leader:
    # Someone takes #1 on one of these boards.
    enabled: true
    chat: true
    boards:
      - global-elo
  streaks:
    # A player reaches one of these win streaks.
    enabled: true
    chat: true
    milestones: [10, 25, 50, 100]
  season-end:
    # /sb season reset posts the final top 3 of these boards.
    chat: true
    boards:
      - global-elo

Discord webhook

  1. In Discord: Server Settings, Integrations, Webhooks, create one and copy its URL.
  2. Run /sb set webhook <url> (or paste it into discord.webhook-url).
  3. Run /sb webhook test and check your channel.
discord:
  webhook-url: ""
  username: ""
  color: "#7c5cff"
  avatar-provider: "https://mineskin.eu/head/{name}/100"
  events:
    new-leader: true
    season-end: true
    streaks: false

Each embed has the player's head and a profile link. Streak messages to Discord are off by default (events.streaks: false).

#Branding and themes

Most branding is one command. Changes apply live, with no restart.

/sb set server-name My Server
/sb set server-ip play.myserver.net
/sb set tagline Practice. Fight. Climb.
/sb set theme neon
/sb set primary-color #7c5cff
/sb set logo https://example.com/logo.png
/sb set logo none

Use none or clear to empty a value. Color keys must be a hex value like #7c5cff. When you set a logo or favicon, StrikeBoards checks in the background that the URL really serves an image and tells you if not (hosts like imgur often return a web page instead).

Built-in themes

esports (default), neon, light, glass, sunset, ocean, midnight, crimson, emerald. Preview one in your own browser by adding ?theme=<name> to the site link. The server theme stays the same for everyone else.

Your own theme

  1. Create plugins/StrikeBoards/themes/<name>/theme.css.
  2. Add a [data-theme="<name>"] block of --sb-* variables. The built-in web/assets/css/theme.css shows the variables to copy.
  3. Run /sb set theme <name>.
Do not edit the built-in web files

The files in plugins/StrikeBoards/web/ are replaced whenever the jar's website changes. Your custom themes and files you add yourself are kept. Use custom themes, site.custom-css-url or site.custom-js-url for changes instead.

Theme settings in config.yml

site:
  theme:
    default: "esports"
    allow-toggle: true
    colors:
      primary: ""
      accent: ""
      background: ""
      card: ""
      text: ""
      muted: ""
    gradient-a: ""
    gradient-b: ""
    radius: "14px"
    font: "Inter"
    heading-font: "Chakra Petch"
    background-image: ""
    background-video: ""
  animations:
    enabled: true
    entrance: true
    hover: true
    idle: true
    particles: true
    speed: 1.0
Colors override the theme

Leave the colors entries empty so the selected theme colors everything. A value forces that color across every theme, which also stops the theme switch from changing it.

Fonts are Google Fonts family names. Leave font and heading-font empty to use the system font stack, so the site loads no external fonts. Every word on the website is in the site: section of messages.yml.

#Embeds and the JSON API

Embed a board

Put a compact board on your own website, a Discord bot page or an OBS overlay:

<iframe src="https://boards.yourserver.com/embed/global-elo?rows=10"></iframe>

Add &theme=<name> to force a theme inside the frame. Turn the embed page off with site.embed.enabled: false.

JSON API

EndpointReturns
/api/statusLive status: online, in fights, in queue, live fights, players ranked, fights recorded and season.
/api/configBranding, theme, boards and site language.
/api/leaderboard/<board>One board, paginated. Add ?player=<name> to get the page that holds that player.
/api/leaderboard/kit/<kit>One ranked kit board.
/api/player/<name>Full profile including ELO history, ELO change, percentile and recent form.
/api/search?q=Player name autocomplete.
/api/compareTwo players side by side.
/api/kitsRanked kits with their top players.
/api/moversThe biggest ELO gains of the week.
/api/live, /api/seasons, /api/matchesLive fights, archived seasons and recent matches.

To protect the API, set web.api-key. Clients then send it as ?key= or an X-Api-Key header. Leave it empty and the API is public. API and image proxy calls are rate limited per IP (see the Configuration section).

#Domain, HTTPS and reverse proxy

The simplest setup is Nginx, Caddy or Cloudflare in front of the plugin, which gives you your own domain and HTTPS.

  1. Set web.bind-address to "127.0.0.1" so only the proxy can reach the plugin.
  2. Set web.behind-proxy: true so the visitor IP for rate limiting comes from X-Forwarded-For.
  3. Set web.public-url to your public address, for example https://boards.yourserver.com. This is the link used in game and in shared links.
  4. Run /sb reload.

To serve the site under an existing domain, set web.base-path (for example "/stats") and proxy that path to the plugin.

The plugin can also serve HTTPS itself from a Java keystore (web.ssl.enabled, keystore, keystore-password). Most owners should use a proxy instead and leave this off.

No public-url set?

The in-game link is built from the server IP, the web port and the base path, for example http://1.2.3.4:8123/. If server-ip is not set in server.properties it falls back to 127.0.0.1, so set web.public-url if your links look wrong.

#Optional SQL mode

By default StrikeBoards reads stats through the StrikePractice API, walking offline players in small background batches. If you run StrikePractice on MySQL or MariaDB you can instead load leaderboard stats straight from its table. It is read-only: only SELECT statements are sent.

sql:
  enabled: false
  url: "jdbc:mysql://127.0.0.1:3306/strikepractice?useSSL=false"
  username: ""
  password: ""
  driver: ""
  table: "strikepractice_stats"
  page-size: 500
  columns:
    uuid: "uuid"
    name: "name"
    global-elo: "elo"
    kills: "kills"
    deaths: "deaths"
    wins: "wins"
    losses: "losses"
    win-streak: "winstreak"
    brackets-wins: ""
    lms-wins: ""
    sumo-wins: ""
    juggernaut-wins: ""
    party-vs-party-wins: ""
    event-wins: ""
  • The table layout is never assumed. At startup the plugin checks your table and logs which configured columns it found. Missing columns show as 0.
  • Leave a column value empty if your table does not have it.
  • Kit ELO is not loaded in SQL mode. Kit boards always come from the StrikePractice API.
  • driver can stay empty to use the JDBC driver that comes with your server.
  • Check /sb status to see which data source is active.

#Commands

The main command is /strikeboards with the alias /sb. Typing just /sb shows a help list that only includes commands you have permission for. Tab completion covers players, boards, theme names and /sb set keys.

Keys for /sb set: server-name, server-ip, tagline, theme, footer, discord, store, website, primary-color, accent-color, font, heading-font, logo, favicon, page-title, public-url, webhook.

CommandWhat it doesPermission
/leaderboardsite [player]Sends a clickable link to the website or to a player's profile. Aliases: /lbsite, /web.strikeboards.use
/sb infoShows the site URL, cached players, boards and season.strikeboards.use
/sb stats [player]Shows tier, ELO, rank, W/L, K/D, streak and best kits. Viewing another player needs the .others permission.strikeboards.stats
/sb top [board]Shows the top players of a board (default global-elo). Click a name for their stats.strikeboards.top
/sb reloadReloads config and messages, rebuilds boards and restarts the website without a server restart.strikeboards.admin
/sb set <key> <value>Changes a branding or site setting and applies it live. Use none to clear a value.strikeboards.admin
/sb seasonShows the current season and finished seasons.strikeboards.admin
/sb season reset [name]Archives the current standings and starts the next season.strikeboards.admin
/sb hide <player>Hides a player from every board, search and profile.strikeboards.admin
/sb unhide <player>Shows a hidden player again (their stats return after a refresh).strikeboards.admin
/sb refreshStarts a full re-read of every player's stats now.strikeboards.admin
/sb statusShows StrikePractice hook, website state, data source, last sweep, cache sizes and webhook state.strikeboards.admin
/sb webhook testSends a test message to the Discord webhook.strikeboards.admin

#Permissions

strikeboards.admin includes all the player permissions below.

PermissionWhat it allowsDefault
strikeboards.use/leaderboardsite and /sb info.everyone
strikeboards.stats/sb stats for your own stats.everyone
strikeboards.stats.others/sb stats <player> for other players.everyone
strikeboards.top/sb top [board].everyone
strikeboards.admin/sb reload, set, season, hide, unhide, refresh, status and webhook. Also receives update notices on join.op

#Placeholders

These need PlaceholderAPI. The expansion registers itself as strikeboards. <board> is a board id from the Boards section. Placeholders marked "viewer" use the player the placeholder is shown to. Values with decimals are rounded to 2 places.

PlaceholderValue
%strikeboards_site%The public website URL.
%strikeboards_players%Players online right now.
%strikeboards_fights%Players currently in fights.
%strikeboards_queue%Players currently in queue.
%strikeboards_top_<board>_<rank>%Player name at that rank, for example %strikeboards_top_global-elo_1%. Empty if the rank is not reached.
%strikeboards_topvalue_<board>_<rank>%The value at that rank, for example the ELO.
%strikeboards_rank_<board>%Viewer's own rank on a board.
%strikeboards_stat_<board>%Viewer's own value on a board.
%strikeboards_tier%Viewer's ELO tier name.
%strikeboards_tier_color%Viewer's tier color code, to put in front of text.
%strikeboards_tier_colored%Viewer's tier name with its color code.
%strikeboards_profile%Link to the viewer's profile page.
%strikeboards_elo_week%Viewer's Global ELO change over 7 days, such as +24.
%strikeboards_elo_month%Viewer's Global ELO change over 30 days.
%strikeboards_season%Current season number.
%strikeboards_live_fights%Number of live fights being tracked.
%strikeboards_tracked%Number of players in the cache.

#Configuration

Everything is in plugins/StrikeBoards/config.yml. Your edits are never overwritten by updates, and new default keys are added automatically. Apply changes with /sb reload, no restart needed.

Cache and performance

cache:
  full-sweep-interval-minutes: 5
  online-refresh-seconds: 30
  status-refresh-seconds: 5
  names-per-tick: 1000
  batch-size: 100
  batch-delay-ms: 400

A full sweep reads every known player in small async batches so the main thread never lags. Lower the interval for fresher boards at the cost of more database load. Online players and players whose fight just ended are re-read every online-refresh-seconds.

Web server

web:
  enabled: true
  port: 8123
  bind-address: "0.0.0.0"
  base-path: "/"
  threads: 2
  behind-proxy: false
  public-url: ""
  ssl:
    enabled: false
    keystore: "keystore.jks"
    keystore-password: "changeit"
  api-key: ""
  rate-limit:
    enabled: true
    requests-per-minute: 120

Skins

  skins:
    enabled: true
    provider: "https://mineskin.eu/head/{name}/100"
    fallback-providers:
      - "https://minotar.net/helm/{name}/100"
      - "https://mc-heads.net/avatar/{name}/100"
    body-provider: "https://mineskin.eu/armor/body/{name}/100.png"

Lookup is by name first, so offline-mode servers and proxies work. Disable skins for a fully offline site; a built-in fallback face is used.

History and ELO chart

history:
  enabled: true
  max-matches: 100
  per-player: 50

elo-history:
  enabled: true
  max-points: 90

history records duel results and powers Recent fights, match history, recent form and head-to-head records. elo-history records each player's Global ELO when it changes and powers the profile chart, Trending this week and %strikeboards_elo_week%.

Live fights

live:
  enabled: true
  poll-seconds: 5

Extra StrikePractice events

bridge:
  extra-fight-end-events: []

DuelEndEvent and FightEndEvent are hooked automatically. If your StrikePractice build has another fight end event, add its fully qualified class name so stats refresh right after those fights. Unknown classes are skipped with a console warning.

Other site options

  • site.page-title: browser tab title, {server} is replaced with the server name.
  • site.footer-text and site.links.website, discord, store: footer and hero links.
  • site.refresh-seconds: how often open pages refresh.
  • site.custom-css-url and site.custom-js-url: your own CSS or JS injected into every page.
  • commands.top-size: rows shown by /sb top.

Updater

updater:
  enabled: true
  check-on-startup: true
  check-interval-hours: 24
  auto-download: false
  notify: true
  shared-token: ""
  resource-id: ""

#Troubleshooting and FAQ

The plugin does not load.

StrikePractice must be installed, because StrikeBoards depends on it. Check the console for the first error. Run /sb status to see whether StrikePractice is hooked and whether the website is running.

The website does not open from outside my network.

The port must be reachable. Open TCP 8123 (or your web.port) in your firewall or ask your host to allocate it. If you use a reverse proxy, point it at the plugin and set web.public-url. Check that web.bind-address is 0.0.0.0 if you want direct access.

The boards are empty.

Stats come from StrikePractice and need a moment after a restart. Run /sb refresh to start a full read and /sb status to see the cached player count. Kits a player never played are hidden when site.kits.hide-unplayed is true.

A ranked kit has no board.

Kit boards are created for StrikePractice kits that use ELO. Make sure the kit is an ELO kit and that it is not listed in site.boards.hidden.

Wins and losses are 0.

On flatfile storage StrikePractice does not keep wins and losses, so StrikeBoards counts them from the duels it records. They start counting from the moment StrikeBoards is installed.

My logo does not show.

The URL must be a direct link to an image file. /sb set logo tells you if the host returned a web page instead. Use /sb set logo none to go back to the built-in mark.

Changing the theme did nothing.

If you filled in site.theme.colors, those colors override every theme. Leave them empty. Also check that the theme name is spelled correctly and, for a custom theme, that themes/<name>/theme.css exists.

Player skins show a default face.

The skin site may be rate limiting or down. StrikeBoards tries the fallback providers in order and uses a built-in face as a last resort. Skins are also saved when players join, so they improve over time.

Visitors get blocked for making too many requests.

The per-IP limit is web.rate-limit.requests-per-minute. Behind a proxy, set web.behind-proxy: true so each visitor is counted separately instead of all sharing the proxy's IP.

Can I run it without StrikePractice?

No. It is a StrikePractice addon and reads its data.

A player wants to be off the boards.

Run /sb hide <player>.

#Updating

  1. Replace the jar in plugins/ with the new version and restart.
  2. Your config.yml, messages.yml, seasons, match history and captured skins are kept. New settings are added to your files on the first start.

The built-in website files in plugins/StrikeBoards/web/ are refreshed when they change; custom themes and files you added are kept.

Update checker

StrikeBoards checks BuiltByBit on startup and every 24 hours (off the main thread) and tells the console, and admins with strikeboards.admin when they join, when a new version is out. With updater.auto-download: true the verified update is downloaded into the server's update folder (plugins/update/), the current jar is backed up to plugins/StrikeBoards/backup/, and the new version installs on the next restart. Auto-download needs a valid BuiltByBit purchase.