SimpleScoreboard

A configurable scoreboard plugin for Paper. Author your sidebar, tab-list, and below-name displays in YAML or edit them in-game from a chest GUI. Multi-board priority selection by world, permission, or gamemode. Frame rotation, horizontal scrolling, and full Adventure MiniMessage formatting.

Features

• All three scoreboard slots: sidebar, tab-list (header + footer), below-name objective
• Multi-board priority list with conditions on world, permission, gamemode (combinable, AND-evaluated, first match wins)
• Animations: frame rotation and horizontal text scrolling, configurable per line and tick-precise
• MiniMessage for all text — colors, gradients, ✨s, click and hover events
• Built-in placeholders for player, world, ping, coords, gamemode, health, online count, max players, TPS
• PlaceholderAPI integration when present — every %papi_*% token just works
• In-game GUI editor (/sb gui) for the impatient: edit boards, conditions, lines, and animations from a chest menu with live preview
• Tab-completion on every /sb subcommand including dynamic board names
• Per-player toggle with persistence (/sb toggle)
• Hot reload without server restart (/sb reload)
• Diff-based render: per-player last-sent cache means packets only fire when output actually changes — static lines never re-send

Quick Example

defaults:
  tick-interval: 1
  scroll-width: 24

boards:
  - name: pvp-arena
    conditions:
      worlds: [pvp_arena]
      permission: server.staff
    sidebar:
      title:
        type: rotate
        interval: 10
        frames:
          - "<gradient:gold:red>STAFF</gradient>"
          - "<gradient:red:gold>STAFF</gradient>"
      lines:
        - "<dark_gray>───────────────"
        - "<gray>Player: <white>%player%"
        - "<gray>Kills: <red>%vault_kills%"
        - ""
        - type: scroll
          width: 24
          interval: 2
          text: "Welcome to the staff PvP arena"
        - "<dark_gray>───────────────"

  - name: default
    sidebar:
      title: "<aqua>My Server"
      lines:
        - "<gray>Online: <white>%online%/%max-players%"
        - "<gray>TPS: <green>%tps%"
    tablist:
      header: "<gold>My Server"
      footer: "<gray>%online%/%max-players% online"

Commands

Command	Permission	Description
/sb gui [board]	simplescoreboard.admin	Open the in-game editor (optionally jumping to a specific board)
/sb reload	simplescoreboard.admin	Reload scoreboard.yml. On parse error the old config keeps running.
/sb list	simplescoreboard.admin	List boards in priority order
/sb show <board>	simplescoreboard.admin	Force-preview a specific board for yourself
/sb show none	simplescoreboard.admin	Clear preview, return to normal selection
/sb toggle	simplescoreboard.toggle	Hide/show your own scoreboard. Preference persists across reconnects.

Aliases: /scoreboard, /simplescoreboard.

Requirements

• Paper (built against API 26.1.2)
• Java 25
• PlaceholderAPI — optional, only needed for %papi_*% tokens

Installation

1. Drop SimpleScoreboard.jar into your plugins/ folder.
2. Start the server. A default scoreboard.yml is created in plugins/SimpleScoreboard/.
3. Edit the YAML or run /sb gui to customize.
4. /sb reload applies YAML changes without restart.

Configuration

plugins/SimpleScoreboard/scoreboard.yml. Top-level structure:

defaults:
  tick-interval: 1     # ticks between renders. 1 = full animation resolution.
  scroll-width: 24     # default character window for scrolling lines

boards:
  - name: <unique-name>
    conditions:        # optional. omit = catch-all (matches everyone)
      worlds: [...]    # optional, any of these worlds
      permission: ...  # optional, player must have this permission
      gamemodes: [...] # optional, any of these gamemodes
    sidebar:           # optional, omit to leave sidebar untouched
      title: <line>
      lines:
        - <line>
    tablist:           # optional
      header: <line>
      footer: <line>
    below-name:        # optional
      title: <line>
      score: "%health%"  # any placeholder that resolves to an integer

Line types

A <line> is either a plain string (Static) or a typed object:

# Static — plain MiniMessage string
"<gold>Hello %player%"

# Rotate — cycle through frames
type: rotate
interval: 10           # ticks per frame
frames: ["Frame A", "Frame B", "Frame C"]

# Scroll — horizontal scroll within a fixed width
type: scroll
interval: 2            # ticks per character shift
width: 24              # visible characters
text: "Long welcome text that scrolls"

In-Game Editor

/sb gui opens a chest-based editor. Navigation:

MainMenu (board list + add)
  └── BoardMenu (rename, delete, conditions, slots)
        ├── ConditionsMenu (worlds, permission, gamemodes)
        ├── SidebarMenu (title + lines, reorder, add, remove)
        │     └── LineEditMenu (Static / Rotate / Scroll switcher)
        │           └── RotateFramesMenu (for Rotate type)
        ├── TablistMenu (header, footer, enable/disable)
        └── BelowNameMenu (title, score expression, enable/disable)

Text content (titles, frame text, scroll text, score expressions) is entered through chat — when you click "Edit text" the menu closes, you type the new MiniMessage value, and the menu reopens. Type !cancel to abort. Inputs time out after 60 seconds.

While editing, your own scoreboard updates live with the unsaved draft so you can see how it looks before committing.

Saving regenerates scoreboard.yml (a one-time .backup is created first), atomically replaces the file, and re-renders for all players. Cancel discards the draft without touching the file.

Note: GUI saves rewrite the YAML through SnakeYAML's standard dumper. Hand-written comments are not preserved. Keep that in mind if you maintain scoreboard.yml by hand and use the GUI on the same file.

Built-in Placeholders

Token	Resolves to
%player%	Player name
%displayname%	Adventure-Component display name (string form)
%world%	Current world name
%gamemode%	SURVIVAL / CREATIVE / ADVENTURE / SPECTATOR
%ping%	Player ping in ms
%x%, %y%, %z%	Integer block coordinates
%health%	Health rounded to integer
%online%	Online player count
%max-players%	Server slot count
%tps%	Server TPS (1 decimal)

Anything else is forwarded to PlaceholderAPI when installed. Unknown tokens (no built-in, no PAPI) stay as raw text — useful for spotting typos visually.

Permissions

Node	Default	Grants
simplescoreboard.admin	op	/sb reload, /sb list, /sb show, /sb gui
simplescoreboard.toggle	true	/sb toggle

Performance

Each player has a per-tick render cycle. The renderer compares the freshly-built component list against a cached last-sent snapshot and only sends an update packet when a line actually differs. Static lines without dynamic placeholders never re-send. Frame-rotation and scrolling lines re-send only when the frame index or scroll offset changes.

scoreboard.yml is parsed once at startup (and on /sb reload). The BoardRegistry uses an atomic reference, so reloads are wait-free for the render loop.

Compatibility Notes

• The Sidebar slot is rendered through the FastBoard library (shaded and relocated). Plays nicely alongside any other scoreboard plugin that touches Tab-list or Below-Name only.
• Two plugins both writing the Sidebar will conflict — disable one or coordinate via permissions.
• Tab-list is set per-player via Paper's Adventure API. Tab-list-modifying plugins (e.g. some prefix systems that write the player-list display name) are independent and won't conflict.