GroupeZ Docs
Modules

Scoreboard Module

Dynamic per-player scoreboards with animations and conditional display

File: modules/scoreboard/config.yml

The Scoreboard module provides a dynamic, per-player scoreboard system with support for event-driven line updates, color animations, and conditional scoreboard switching based on permissions or placeholders. It uses the FastBoard library for packet-based scoreboard rendering, ensuring high performance and flicker-free updates.

Source Configuration

enable: true
join-conditions:
  - priority: 0
    scoreboard: default
  - priority: 1
    scoreboard: admin
    requirements:
      - type: permission
        permission: "zessentials.scoreboard.admin"
enable-task-conditions: false
task-conditions-interval: 2
task-conditions:
  - scoreboard: event
    requirements:
      - type: placeholder
        placeholder: "%player_world%"
        value: "event"
        action: EQUALS_STRING
scoreboards:
  default:
    default: true
    title: "#53edd6zEssentials"
    lines:
      - line: 1
        text: ""
      - line: 2
        text: "&7Balance: &a%zessentials_user_formatted_balance_money%"
        event: "fr.maxlego08.essentials.api.event.events.user.UserEconomyPostUpdateEvent"
      - line: 3
        text: "&7Coins: &a%zessentials_user_formatted_balance_coins%"
        event: "fr.maxlego08.essentials.api.event.events.user.UserEconomyPostUpdateEvent"
      - line: 4
        text: ""
      - line: 5
        text: "play.essentials.fr"
        animation: COLOR_WAVE
        fromColor: "#5599ff"
        toColor: "#ffffff"
        length: 5
        delayBetween: 5000
        animationSpeed: 30
  admin:
    title: "#53edd6zEssentials"
    lines:
      - line: 1
        text: ""
      - line: 2
        text: "&7Balance: &a%zessentials_user_formatted_balance_money%"
        event: "fr.maxlego08.essentials.api.event.events.user.UserEconomyPostUpdateEvent"
      - line: 3
        text: "&7Coins: &a%zessentials_user_formatted_balance_coins%"
        event: "fr.maxlego08.essentials.api.event.events.user.UserEconomyPostUpdateEvent"
      - line: 4
        text: "&7Rank: &cAdmin"
      - line: 5
        text: ""
      - line: 6
        text: "play.essentials.fr"
        animation: COLOR_WAVE
        fromColor: "#5599ff"
        toColor: "#ffffff"
        length: 5
        delayBetween: 5000
        animationSpeed: 30

Options

General Options

OptionTypeDefaultDescription
enableBooleantrueEnable or disable the Scoreboard module
enable-task-conditionsBooleanfalseEnable periodic condition checks that can dynamically switch a player's scoreboard while they are online
task-conditions-intervalInteger2Interval in seconds between task condition checks (only used when enable-task-conditions is true)

Join Conditions

The join-conditions list determines which scoreboard a player receives when they join the server. Entries are evaluated in priority order (lowest first). The first matching condition is used; if none match, the scoreboard marked as default: true is applied.

OptionTypeDefaultDescription
join-conditions[].priorityInteger-Evaluation priority. Lower values are checked first
join-conditions[].scoreboardString-The name of the scoreboard to assign (must match a key under scoreboards)
join-conditions[].requirementsList(optional)A list of zMenu-style requirements that must be met. If omitted, the condition always matches
join-conditions[].requirements[].typeString-The requirement type, e.g., permission or placeholder
join-conditions[].requirements[].permissionString-The permission node to check (when type is permission)

Task Conditions

The task-conditions list allows the plugin to periodically re-evaluate conditions and switch a player's scoreboard at runtime (e.g., when they enter a specific world).

OptionTypeDefaultDescription
task-conditions[].scoreboardString-The scoreboard to switch to when the requirements are met
task-conditions[].requirementsList-A list of requirements to evaluate
task-conditions[].requirements[].typeString-The requirement type, e.g., placeholder
task-conditions[].requirements[].placeholderString-The placeholder to evaluate (when type is placeholder)
task-conditions[].requirements[].valueString-The expected value to compare against
task-conditions[].requirements[].actionString-The comparison action, e.g., EQUALS_STRING, EQUALS_NUMBER, SUPERIOR, INFERIOR

Scoreboard Definitions

Each entry under scoreboards defines a named scoreboard with a title and lines.

OptionTypeDefaultDescription
scoreboards.<name>.defaultBooleanfalseIf true, this scoreboard is used as the fallback when no join condition matches
scoreboards.<name>.titleString-The scoreboard title displayed at the top. Supports color codes and hex colors (e.g., #53edd6)
scoreboards.<name>.linesList-The list of line entries displayed on the scoreboard

Line Options

OptionTypeDefaultDescription
lines[].lineInteger-The line number (position on the scoreboard, starting from 1)
lines[].textString-The text content of the line. Supports color codes and PlaceholderAPI placeholders
lines[].eventString(optional)A fully-qualified Bukkit/zEssentials event class name. When this event fires, the line is refreshed. This avoids unnecessary tick-based updates
lines[].animationString(optional)The animation type to apply to this line. Currently supports COLOR_WAVE
lines[].fromColorString(optional)The starting hex color for the animation (e.g., #5599ff)
lines[].toColorString(optional)The ending hex color for the animation (e.g., #ffffff)
lines[].lengthInteger(optional)The length (in characters) of the color wave effect
lines[].delayBetweenInteger(optional)Delay in milliseconds between animation cycles
lines[].animationSpeedInteger(optional)Speed of the animation in milliseconds per frame

Key Features

Event-Driven Updates

Instead of updating every line on a fixed timer, you can bind individual lines to specific events. For example, binding a balance line to UserEconomyPostUpdateEvent ensures that line only refreshes when the player's balance actually changes. This drastically reduces unnecessary packet traffic.

- line: 2
  text: "&7Balance: &a%zessentials_user_formatted_balance_money%"
  event: "fr.maxlego08.essentials.api.event.events.user.UserEconomyPostUpdateEvent"

Event-driven lines are the recommended approach for data that changes infrequently (balances, ranks, stats). Only use timer-based updates for truly dynamic content.

COLOR_WAVE Animation

The COLOR_WAVE animation creates a smooth gradient wave effect across text, transitioning between two hex colors.

- line: 5
  text: "play.essentials.fr"
  animation: COLOR_WAVE
  fromColor: "#5599ff"
  toColor: "#ffffff"
  length: 5
  delayBetween: 5000
  animationSpeed: 30
ParameterDescription
fromColorThe starting color of the wave
toColorThe ending color of the wave
lengthHow many characters the gradient spans at once
delayBetweenPause in milliseconds before the animation restarts
animationSpeedTime in milliseconds between each animation frame

Conditional Scoreboard Switching

Using join-conditions and task-conditions, you can display different scoreboards to different players based on permissions, worlds, or any placeholder value. This integrates with the zMenu requirements system.

The task-conditions system must be explicitly enabled with enable-task-conditions: true. When disabled, scoreboards are only assigned on join and do not change dynamically.

How It Works

  1. When a player joins, the plugin evaluates join-conditions in priority order.
  2. The first matching condition determines which scoreboard the player sees. If no condition matches, the scoreboard marked default: true is used.
  3. Lines with an event property are registered as event listeners and only update when that event fires.
  4. Lines with an animation property run on their own animation loop.
  5. If enable-task-conditions is true, the plugin periodically checks task-conditions and may switch the player's scoreboard at runtime.
CommandPermissionDescription
/sbessentials.scoreboardToggle the scoreboard visibility for the player

For the full command list, see Commands & Permissions.

FastBoard Library

This module uses the FastBoard library for rendering scoreboards via packets. This means:

  • No flickering when updating lines.
  • No interference with other plugins that use the vanilla scoreboard API.
  • High performance even with many players online.

Since FastBoard operates at the packet level, other plugins that also send scoreboard packets may conflict with this module. If you experience visual issues, check for conflicting scoreboard plugins.

Sanction Module

Complete moderation system with bans, mutes, kicks, freezes, and sanction history

Spawn Module

Server spawn management with configurable respawn behavior

On this page

Source ConfigurationOptionsGeneral OptionsJoin ConditionsTask ConditionsScoreboard DefinitionsLine OptionsKey FeaturesEvent-Driven UpdatesCOLOR_WAVE AnimationConditional Scoreboard SwitchingHow It WorksRelated CommandsFastBoard Library
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.