TAB and PlaceholderAPI integration

McProgression works on its own. Its native bossbar and chat announcements do not require TAB or PlaceholderAPI. When PlaceholderAPI (PAPI) is installed, McProgression registers the mcprogression expansion and makes rank and skill values available to TAB and other PAPI consumers. TAB controls the layout, colors, visibility, toggle commands, and refresh behavior.

This guide covers a standalone Paper server first, then notes for proxy networks. The examples use TAB 6.2.0 and McProgression's current placeholder names. TAB's YAML is versioned and can change, so merge the relevant section into the plugins/TAB/config.yml generated by your installed TAB version rather than replacing the entire file.

What you need

For a standalone Paper server, install these jars in plugins/:

1. McProgression.
2. PlaceholderAPI.
3. TAB (optional, only needed for TAB displays).

Restart the server after installing them. McProgression declares PlaceholderAPI as a soft dependency: it remains usable without PAPI, and registers its expansion automatically when PAPI is present and integrations.placeholder-api.enabled is true in plugins/McProgression/config.yml.

Check startup logs for McProgression's PlaceholderAPI integration message. Then run:

/papi parse me %mcprogression_global_rank%
/papi parse me %mcprogression_skill_mining_level%

Replace mining with an enabled skill ID from plugins/McProgression/skills.yml. Each command should return a value rather than the original %...% token. TAB reads the same PAPI values; no TAB-specific expansion needs to be registered.

After editing TAB's config, apply it with /tab reload and check the server console for YAML or placeholder errors. McProgression has no config-reload command: restart Paper after changing its files. Reloading TAB does not reload McProgression.

Placeholder reference

Use these inside another plugin's normal PlaceholderAPI syntax, including the percent signs:

Replace <skill-id> with the configured skill key, lowercased. The built-in IDs are mining, farming, woodcutting, combat, cooking, smithing, fishing, crafting, agility, and herblore. For example, use %mcprogression_skill_woodcutting_level%. An unknown or disabled skill does not produce a usable value. Numeric XP placeholders are formatted as whole numbers. The bar uses █ for filled segments and ░ for empty ones, with §a/§8 colors.

The legacy plugin's generic %lekkerleveling_level%, %lekkerleveling_xp%, and similar names imply a single progression track. McProgression has ten independent skills plus General XP, so use the explicit skill_<id>_* family for skill-specific values and %mcprogression_general_xp% for uncategorized progression. %mcprogression_global_score% is a combined rank-point value, not XP; %mcprogression_global_skill_score% isolates the skill-level component.

Scope: the current skill placeholders read the player's global progression profile. global_* is also server-wide. World and world-group scopes currently apply to leaderboard views, not to separate XP, level, or rank tracks, and there are no world-specific PAPI placeholders yet. Do not label these values as a world-specific rank unless that behavior is added in a future version.

Optional LuckPerms Global Rank prefix

To store Global Rank as a LuckPerms user prefix, install LuckPerms and enable the integration in plugins/McProgression/config.yml:

integrations:
  luckperms-global-rank-prefix:
    enabled: true
    priority: 1
    format: "&7[{rank}] "

McProgression activates this only when both the option and LuckPerms are present. It synchronizes the player's localized Global Rank on join and when the rank changes. priority is LuckPerms' prefix priority; a higher-priority prefix can take precedence, and configured LuckPerms stacking may show multiple prefixes. A chat-formatting plugin still needs to read and render LuckPerms prefixes in chat. For TAB or another PlaceholderAPI consumer, %mcprogression_global_rank% remains available without storing a LuckPerms prefix.

The integration stores a private marker meta node with the exact prefix and priority it last wrote. On subsequent synchronization, it removes only that recorded prefix and its marker, then adds the updated prefix. It never changes group membership or clears other prefixes. Disabling the integration stops further writes but leaves the last saved prefix in LuckPerms; inspect /lp user <player> meta info and remove that one with LuckPerms' meta removeprefix command if desired. Avoid clearing all user prefixes.

TAB examples

The TAB examples below show focused config sections. Keep unrelated settings from your generated TAB config. Each TAB feature has its own enabled setting; enable only the display surfaces you intend to use.

Bossbar: Global Rank progress

Merge this into the existing bossbar: section in plugins/TAB/config.yml:

bossbar:
  enabled: true
  toggle-command: /progressbar
  remember-toggle-choice: true
  hidden-by-default: false
  bars:
    McProgressionGlobalRank:
      style: "PROGRESS"
      color: "GREEN"
      progress: "%mcprogression_global_progress%"
      text: "&6%mcprogression_global_rank% &7| Global rank points: &f%mcprogression_global_score%"

TAB bossbar progress expects a number from 0 to 100, which is exactly what %mcprogression_global_progress% returns. The toggle command is handled by TAB and requires TAB's tab.bossbar.toggle permission. TAB displays can coexist with other plugin bossbars, but Minecraft clients show only a limited number at a time; the visible order depends on when bars are sent. TAB bossbar guide

To show a skill's current-level progress instead, use e.g. progress: "%mcprogression_skill_mining_level_progress%" and change the text to include the matching skill. global_progress and skill_*_level_progress are separate progress measures.

Sidebar: Global Rank and a selected skill

Merge this into the existing scoreboard: section. The section name under scoreboards is just an identifier and can be changed:

scoreboard:
  enabled: true
  toggle-command: /progress
  remember-toggle-choice: true
  hidden-by-default: false
  delay-on-join-milliseconds: 0
  scoreboards:
    progression:
      title: "&6Progression"
      lines:
        - "&7Overall rank"
        - "&f%mcprogression_global_rank%"
        - "&7Global rank points: &f%mcprogression_global_score%"
        - ""
        - "&bMining &7Lv. &f%mcprogression_skill_mining_level%"
        - "&7XP into level: &f%mcprogression_skill_mining_xp_into_level% &8| &7XP left: &f%mcprogression_skill_mining_xp_remaining%"
        - "&7Mining progress: &f%mcprogression_skill_mining_level_progress%%%"

The final line has three percent signs at the end: the first two close the placeholder, and the last is the displayed percent character. Copy TAB's version-specific scoreboard example if you use advanced line splitting or multiple layouts. TAB scoreboard syntax and client-version behavior are documented in its scoreboard guide.

Playerlist: show Global Rank beside player names

On Minecraft 1.20.3 and newer, TAB can show arbitrary text in the playerlist objective. Merge into playerlist-objective::

playerlist-objective:
  enabled: true
  value: "0"
  fancy-value: "&6%mcprogression_global_rank% &7| Lv &f%mcprogression_skill_mining_level%"
  title: "Progression"
  render-type: INTEGER
  disable-condition: "%world%=disabledworld"

value remains numeric for older-client compatibility; fancy-value is the text displayed by supported 1.20.3+ clients. If you support older clients, they show the numeric value rather than the rank text. TAB notes that another plugin can also claim the playerlist objective, in which case the displayed objective may depend on which plugin sends it. See TAB's playerlist objective guide.

Below player names: show a skill level

On 1.20.3+ clients, TAB can show text below player names. This affects the view of every player entity, including NPCs, so consider that before enabling it:

belowname-objective:
  enabled: true
  value: "0"
  fancy-value: "&bMining %mcprogression_skill_mining_level%"
  fancy-value-default: ""
  title: "Mining"
  disable-condition: "%world%=disabledworld"
  view-distance: 10

Use a short label because this appears above the player's head. On clients older than 1.20.3, TAB uses the numeric value. The below-name objective is shared with other plugins and can conflict if another plugin also sets it. See TAB's below-name guide.

Sort the tablist by Global Rank score

TAB's scoreboard-teams.sorting-types controls player ordering. Add the numeric score after any group priorities you already use:

scoreboard-teams:
  enabled: true
  sorting-types:
    - "GROUPS:owner,admin,mod,default"
    - "PLACEHOLDER_HIGH_TO_LOW:%mcprogression_global_score%"
    - "PLACEHOLDER_A_TO_Z:%player%"

Players are first ordered by the configured group order, then by Global Rank score from highest to lowest, then alphabetically. If you want progression to determine ordering across all groups, remove the GROUPS: line. The score is numeric; the rank name is text and should not be used with numeric sorting. TAB documents its sorting modes in the sorting guide.

Choosing between TAB and the native HUD

McProgression's native bossbar is controlled under player-display.overlay in plugins/McProgression/config.yml. Leave it enabled to show it alongside TAB layouts, or set this to false if TAB should own the progression HUD:

player-display:
  overlay:
    enabled: false

The player HUD commands (/mcprogression hud on|off|toggle) apply to McProgression's native HUD, not TAB's bossbar or scoreboard. TAB's toggle commands and permissions control TAB features. McProgression chat announcements are configured separately under player-display.announcements; they work regardless of whether either HUD is enabled.

Styling progression announcements

Skill and Global Rank announcements have a configurable format around their message. The default adds a colored [Levels] or [Global Rank] tag and the player's name. Use legacy & color/style codes, and change recipient to player, server, or permission as needed:

player-display:
  announcements:
    player-icon: "" # Optional symbol or resource-pack glyph before the name.
    skill-level-up:
      format: "&8[&bLevels&8] {player_icon}&f{player} &7{message}"
      message: "&a{skill} reached level {level}!"
    global-rank-up:
      format: "&8[&6Global Rank&8] {player_icon}&f{player} &7{message}"
      message: "&6{player} advanced to global rank {rank}!"

format supports {player}, {player_icon}, and {message}. The message body keeps its existing progression placeholders: skill announcements support {skill}, {old_level}, {new_level}, {level}, {amount}, {old_xp}, {new_xp}, {source}, {world}, and {score}; Global Rank announcements support {old_rank}, {rank}, {old_score}, and {score}. A blank message uses the configured language text. Vanilla Minecraft chat cannot display a live skin head inline; {player_icon} can hold a text symbol or a private-use glyph supplied by a server resource pack.

Proxy networks

McProgression and its progression data run on the Paper backend, so install McProgression and PlaceholderAPI on each backend where TAB needs to resolve a player's progression. TAB can be installed on the backend or on a supported proxy. If TAB runs on a proxy, follow TAB's proxy setup and install its TAB-Bridge component on the backend as required by TAB; configuring the proxy alone does not install McProgression's expansion there. See TAB's PlaceholderAPI support documentation.

For several Paper servers sharing a database, check McProgression's storage and multi-server limitations before enabling writes: a shared database does not by itself synchronize live progression caches. The PlaceholderAPI expansion exposes the profile seen by that backend.

Troubleshooting

TAB parses many placeholders asynchronously by default and documents a %sync:<placeholder>% wrapper for integrations that specifically require the main server thread. McProgression's expansion is intended to be read-only display data; if you encounter a platform-specific threading issue, first update to the supported plugin versions and consult TAB's PlaceholderAPI guide before changing refresh behavior.

Optional integration

PlaceholderAPI and TAB are not bundled with McProgression. Without either one, McProgression's skills, ranks, commands, item rules, announcements, and native HUD continue to work. The integration can be switched off with:

integrations:
  placeholder-api:
    enabled: false

For other plugins, use the placeholder reference above and follow that plugin's instructions for PAPI support. The expansion is registered as mcprogression and persists through PlaceholderAPI reloads.