FoliaBoard-API

FoliaBoard
A Folia-native, packet-level scoreboard API for Paper & Folia. It removes the single hardest part of scoreboards on Folia — knowing which thread may touch a player's board and not racing when they move between regions — and gives you a fluent, MiniMessage-first API where every call is safe from any thread.

• Zero threading work. Call from the main thread, an async task, a region thread — anywhere.
• Zero third-party deps. Packets are built and sent directly. No ProtocolLib, no MegaVex.
• MiniMessage everywhere. Any String argument is parsed as MiniMessage (gradients, hover, click…).
• Runs on Paper too. The same jar works on plain Paper (everything just runs on the main thread).
• Validated live on Folia 1.21.11.

─────────────────────────────────────────────
Why it exists
Packet scoreboard libraries are excellent but warn that their board/team objects are not thread-safe. On Folia that warning is the whole game: there is no main thread, players tick on region threads, they migrate between regions, and join/quit fires on region threads.
FoliaBoard's core idea: confine every mutation of a player's board to that player's EntityScheduler — Folia's scheduler that follows the entity across regions and runs its tasks strictly sequentially. That yields thread-safety with zero locks, and it's all hidden. You describe what to show; FoliaBoard handles where and when it's safe to send the packets.
─────────────────────────────────────────────
Requirements

• Paper or Folia 1.20.6+ (modern per-score display components).
• Java 21.

─────────────────────────────────────────────
Installation
Two ways to use it:

• Shade foliaboard-core into your plugin (self-contained; ships no plugin.yml so it can't clobber yours) — shown below.
• Install the standalone FoliaBoard plugin (the Modrinth download) and softdepend: [FoliaBoard] — one shared jar for all your plugins; then ScoreboardAPI.get()...

1. Depend on the core library:
2. Shade + relocate it (so two plugins bundling it can't collide):
3. Mark your plugin Folia-ready — required or it won't load on Folia:
─────────────────────────────────────────────
Quick start
Two styles — pick one.
A. Instance (recommended):
B. Static handle (if you'd rather not pass the instance around):
All examples below use a board (a FoliaBoard); with the static handle just write ScoreboardAPI or ScoreboardAPI.get().
Add import static net.foliaboard.api.text.Text.mini; (or use Text.mini(...)) when you want a Component from a MiniMessage string.
─────────────────────────────────────Sidebars
The right-hand board. There are four ways to drive one — from most convenient to most manual.
1. Fluent builder
If any content is a placeholder string, an Animation, or a supplier, the board is dynamic and FoliaBoard auto-refreshes it on the player's own thread — you never write a scheduler. Everything else is painted once.
Titles and lines accept String (MiniMessage), Component, or Animation<Component>. Lines may also carry a number format.
2. Manual control
Full control, still safe from any thread:
Only genuinely-changed lines produce packets, so frequent updates never flicker.
3. Global provider — one description for everyone
Or implement the interface for visible(player) control. FoliaBoard attaches a sidebar to every player, refreshes it per player on the right thread, and cleans up on quit.
4. Global layout — same shape, per-player content
─────────────────────────────────────────────
Layout profiles
A layout is a reusable, named board template you can apply to any player and switch between instantly (lobby ↔ minigame, per-world boards, …). It's just a recorded recipe of builder calls.

• Applying a layout replaces the previous board cleanly (no stale leftover lines).
• Leaving a world-layout world for one with no layout clears the board.
• Fires a cancellable LayoutApplyEvent so other plugins can override per rank/region.

─────────────────────────────────────────────
Nametags
Control the text around a player's name (above their head and in the tab list): prefix, suffix, name colour, visibility, collision, and tab-list sort — sent as a scoreboard team, so it doesn't fight Bukkit teams. Updates use team- modify, so they never flicker.
Per-viewer nametags
Show a target's name differently to different viewers — classic ally/enemy colouring:
The resolver runs per viewer on that viewer's thread; it starts from the global defaults. Call .apply() again whenever relationships change (e.g. on a timer, or on a team-join event).
[HR][/HR]
Below-name & tab-list numbers
Shared objectives that show a number below every player's name, or beside their tab-list entry.
Per-viewer numbers
Quit players are cleaned up automatically (no leaks, no phantom scores).
[HR][/HR]
Tab-list header & footer
Accepts String (MiniMessage) or Component. Sent on the player's region thread.
Tab-list entry styling & sorting
Style how a player appears in the tab list, independently of their above-head nametag, and sort the list — with no scoreboard team, so it doesn't conflict with other team-based plugins.

• Tab vs. above-head are separate. The above-head prefix comes from a nametag (a team); the tab prefix comes from tabName(...) (no team). Use either or both.
• Flicker-free, dynamic sorting. tabOrder(...) changes instantly with no team-name trick. (On 1.21.1 and older, fall back to nametag tabSort.)
• Team-conflict friendly. Because tab styling needs no team, a server that already runs a team-based nametag/prefix plugin can use FoliaBoard purely for the tab list (and sidebars) without fighting over teams. Above-head prefixes still require a team — that's a vanilla limitation — so simply don't create FoliaBoard nametags if another plugin owns the above-head text.

tabName/ tabOrder are per-target (shown the same to everyone), built on stable Paper API.
Per-viewer tab names
To show a target a different tab name to different viewers, use the packet-level API:
This is a manual send (no automatic lifecycle): re-apply it when you need it, e.g. on the viewer's join or after the server resends player info. It's built on ClientboundPlayerInfoUpdatePacket and fails safe — if the server build doesn't support it, perViewerTabSupported() returns false and the calls no-op rather than erroring.
─────────────────────────────────────────────
Number formats
Control the red score number the client draws on the right of each entry (1.20.3+). Sidebars hide it by default; override per line or on shared objectives.
─────────────────────────────────────────────
Animations
Self-timed — no ticking or registration. Call current() and return it; the frame is derived from the clock.
cycle, scrollText, pulseColor, and typewriter are code-point safe (won't split emoji). Animations are global wall-clock phase (every player sees the same frame at the same instant).
─────────────────────────────────────────────
Placeholders
A fast engine that replaces %tokens% using, in order: your resolvers → built-ins → PlaceholderAPI (if installed; bridged reflectively, no hard dependency).
Built-ins: %player% / %player_name% / %name%, %displayname%, %world%, %online%, %max_players%, %ping%, %health%, %x% / %y% / %z%.
Injection-safe: in component(...), placeholder values are escaped before parsing, so a value like a display name containing <red> or a PAPI value with <click:...> renders literally and can't inject formatting or click events into your board.
─────────────────────────────────────────────
MiniMessage & text
Text is the one-stop helper.
Every String argument across the API goes through MiniMessage, so you rarely need Text directly.
─────────────────────────────────────────────
Events & hooks
Line processor — rewrite every line/title of every board just before it's sent:
Bukkit events:
Both fire on the player's region thread (synchronous Folia-safe events).
─────────────────────────────────────────────
Async utilities
Folia-safe helpers for your surrounding work (FoliaBoard's own calls are already thread-safe):
─────────────────────────────────────────────
Threading model

• Public API is callable from any thread. Mutations to a player's board are queued and applied on that player's region thread, in order, so nothing races.
• On Paper (non-Folia) everything runs on the main thread — the same code, no branches.
• You never schedule anything for scoreboard work. For your own logic, use AsyncUtil.

Internally: each Sidebar keeps desired state (written under a lock from any thread) and sent state (touched only on the region thread inside a debounced flush that diffs and emits minimal packets).
─────────────────────────────────────────────
Performance
FoliaBoard is built to stay cheap even with many players and fast, animated boards:

• Minimal packets. Sidebars diff desired-vs-sent state and send only changed lines. Below-name/tab score updates skip the broadcast entirely when the value is unchanged.
• No re-parsing. Dynamic placeholder lines cache their parsed MiniMessage and only re-parse when the resolved string actually changes.
• Cheap conversions. The (very common) empty component — blank spacer lines, empty titles — is converted to its vanilla form once and reused. Score-holder names are interned.
• Fast send path. Packets go out through cached MethodHandles (with a reflection fallback).
• No busy loops. Nothing polls; work is event- and scheduler-driven, and refresh loops stop the instant a board closes or a player leaves.

Practical guidance: pick a refreshEvery(...) that matches your content — 2–4 ticks for smooth animations, 10–20 for mostly-static boards. Static content isn't refreshed at all.
Observability
board.stats() returns a snapshot for profiling TPS impact:
FoliaBoard also warns (once) when a board exceeds the 15-line client limit or a single line/title is unusually large (likely accidental payload bloat).
─────────────────────────────────────────────
Remembering a player's layout
Optionally persist which layout a player was on, so it's re-applied on their next join with no join-listener glue. Back the store with anything (a map, a config, a database, a storage plugin):
When set, applyLayout(...) records the layout name, and FoliaBoard re-applies it on join (unless a global or per-world layout already drives that player's board).
─────────────────────────────────────────────
Lifecycle, cleanup & /reload

• Create once in onEnable, call board.close() in onDisable. close() cancels every task, unregisters the listener, and tears down all boards, nametags and objectives.
• Auto-cleanup on quit, world-change and plugin-disable — no ghost players, no leaks.
• /reload is discouraged (on Paper/Folia generally). Because FoliaBoard registers a listener and scheduler tasks, prefer a full restart. A clean disable→enable cycle won't leak (guarded against scheduling while disabled), but /reload remains unsupported as a reload mechanism.

─────────────────────────────────────────────
API reference

• FoliaBoard — create(plugin), createBoard(p), createNametag(p), sidebar(p), removeSidebar(p), setGlobalSidebar(provider|layout), clearGlobalSidebar(), registerLayout/unregisterLayout/layout/applyLayout, setWorldLayout/clearWorldLayout, setLayoutStore, nametag(p), belowName(), tabList(), tabName/resetTabName/tabOrder, tabNameFor/resetTabNameFor/perViewerTabSupported, tabHeaderFooter/clearTabHeaderFooter, addLineProcessor, placeholders(), stats(), close()
• ScoreboardAPI — init(plugin), get(), shutdown(), createBoard(p), createNametag(p), sidebar(p)
• BoardBuilder — placeholders(bool), refreshEvery(ticks), title(...), line(...), lines(...), blankLine(), build()
• Sidebar — title(...), line(...), lines(...), removeLine, clearLines, visible(...), title(), lines(), lineCount(), close()
• NametagBuilder — prefix/suffix/color/nametagVisibility/collision, tabSort(int), perViewer(resolver), apply()
• Nametag — prefix/suffix/color/…, perViewer(resolver), apply(), remove()
• ScoreObjective — title(...), score(player|entry, v), remove(entry), scoreFor/removeFor(viewer,…), hide(), show()
• SidebarProvider — title(p), lines(p), visible(p), refreshIntervalTicks(), of(...)
• Layout — named(name, recipe), applyTo(board, p)
• NumberFormat — blank(), fixed(c), styled(style), defaultFormat()
• Animations — cycle, scrollText, pulseColor, typewriter, mini
• Placeholders — register(...), apply(p,text), component(p,text)
• Text — mini(...), toMini(c)
• AsyncUtil — async, asyncLater, onPlayer, global, isFolia
• events / hooks — SidebarCreateEvent, LayoutApplyEvent, LineProcessor

─────────────────────────────────────────────
Version support & the honest caveat

• Requires Paper/Folia 1.20.6+, Java 21. Targets the Mojang-mapped runtime and modern per-score display-component packets. Validated live end-to-end on Folia 1.21.11.
• The packet layer (NmsPacketAdapter) reaches into server internals by reflection, and adapts at load to whether score-packet fields are Optional<…> or [USER=241773]@Nullable[/USER]. It's the only version-specific file, and it fails loudly at load (never mid-game) if a handle can't resolve. If a future Minecraft release moves a field or changes a packet's shape, that one file is where you adjust it.

─────────────────────────────────────────────
Building from source

• foliaboard-core/target/foliaboard-core-1.0.0.jar — the library (depend on this).
• foliaboard-demo/target/FoliaBoard-1.0.0.jar — a standalone demo plugin. Drop it into plugins/, join, and use /fbdemo lobby|minigame to see everything at once. Add -Dfoliaboard.debug=true to log every scoreboard packet.