BlazeBans/Integrations

PlaceholderAPI

BlazeBans registers the `blazebans` expansion automatically when PlaceholderAPI is installed on Paper or Folia. It is built into the jar, so there is no eCloud download and nothing to install.

How current the data is

Placeholder data refreshes every five seconds. Rendering a placeholder never touches the database, so a scoreboard updating twenty times a second costs your database nothing.

The tradeoff is that a new punishment can take up to five seconds to show up, and so can one issued on another server in the network. If a refresh fails, the last good values keep being shown rather than everything going blank.

Five seconds is the right price for a scoreboard. If you need the current answer immediately, use /history or /checkban.

Player state

Placeholder	Returns
`%blazebans_is_banned%`	Whether the player has an active ban or IP ban here
`%blazebans_is_muted%`	Whether the player has an active mute or IP mute here
`%blazebans_is_voice_muted%`	Whether the player has an active voice mute here
`%blazebans_has_active_warning%`	Whether the player has an active warning here

These use PlaceholderAPI's current player context, so they resolve against whoever the placeholder is being rendered for.

Active punishment details

Four families, each supporting the same eight fields:

%blazebans_active_ban_<field>%
%blazebans_active_mute_<field>%
%blazebans_active_voice_mute_<field>%
%blazebans_active_warning_<field>%

Field	Returns
`type`	The stored type, such as `BAN`, `IP_BAN`, or `VOICE_MUTE`
`id`	The punishment ID
`reason`	The stored reason
`staff`	Who issued it
`remaining`	Compact remaining time such as `2d 4h`, or the configured permanent value
`is_permanent`	Whether it has no expiry
`scope`	`global` or `server`
`server`	The server ID, or the configured empty value for a global punishment

txt

%blazebans_active_mute_remaining%
%blazebans_active_ban_reason%
%blazebans_active_ban_staff%

Latest kick

Placeholder	Returns
`%blazebans_latest_kick_id%`	The ID
`%blazebans_latest_kick_reason%`	The reason
`%blazebans_latest_kick_staff%`	Who issued it
`%blazebans_latest_kick_age%`	Compact time since it happened
`%blazebans_latest_kick_scope%`	`global` or `server`
`%blazebans_latest_kick_server%`	The server ID, or the empty value

Kicks are historical events, not active punishments, which is why they get their own family rather than appearing under the active ones.

Player history

Placeholder	Returns
`%blazebans_history_total%`	Every record stored for the player
`%blazebans_ban_count%`	Ban and IP-ban records
`%blazebans_mute_count%`	Mute and IP-mute records
`%blazebans_voice_mute_count%`	Voice-mute records
`%blazebans_warning_count%`	Warning records
`%blazebans_kick_count%`	Kick records

These cover the player's complete stored history across every server scope, and include active, expired, and revoked records. They are lifetime totals, not current state.

Server state

Placeholder	Returns
`%blazebans_active_bans%`	Active ban and IP-ban records applicable here
`%blazebans_active_mutes%`	Active mute and IP-mute records applicable here
`%blazebans_active_voice_mutes%`	Active voice-mute records applicable here
`%blazebans_active_warnings%`	Active warning records applicable here
`%blazebans_lockdown%`	Current server lockdown state
`%blazebans_chat_lockdown%`	Current chat lockdown state
`%blazebans_version%`	Installed BlazeBans version

Active totals count records, not distinct players. Someone with both a ban and an IP ban counts twice.

Controlling the output

yaml

placeholder-api:
  values:
    "true": "true"
    "false": "false"
    none: ""
    permanent: "Permanent"

Key	Used for
`"true"`	What boolean placeholders return when true
`"false"`	What they return when false
`none`	A missing player context or unavailable detail
`permanent`	The remaining time on a permanent punishment

Change these to match the surface you are rendering into:

yaml

placeholder-api:
  values:
    "true": "<red>Yes</red>"
    "false": "<green>No</green>"
    none: "-"
    permanent: "Forever"

Changes apply after /blazebans reload.

Return values

A valid player with no history returns false for state placeholders and 0 for counts.

A missing player context, or a detail that does not exist, returns whatever placeholder-api.values.none is set to. That is why none defaults to an empty string: an unset value should render as nothing rather than as the word "none".

Examples

A tab list showing mute state:

txt

%player_name% %blazebans_is_muted%

A staff scoreboard:

txt

Bans: %blazebans_active_bans%
Mutes: %blazebans_active_mutes%
Lockdown: %blazebans_lockdown%

A join message for a player with history:

txt

%player_name% joined. Warnings: %blazebans_warning_count%

A mute countdown in a chat plugin's blocked message:

txt

You are muted for %blazebans_active_mute_remaining%. Reason: %blazebans_active_mute_reason%

Troubleshooting

A placeholder renders as its own text. PlaceholderAPI is not installed, or BlazeBans started before it. Check /papi list for blazebans.

It renders blank. No value is available, and placeholder-api.values.none is an empty string. That is the configured behaviour, not a fault.

It is out of date. Values refresh every five seconds. Wait, then check again.

Voice mute placeholders always say false. The voice chat addon is not installed. Without it, no voice mute records exist.