This page documents every configuration option available in config.yml, including what each option does and how its value affects StaffManager.

• debug
  • debug.text-render-engine
  • debug.database-operations
  • debug.text-elements-generation
  • debug.tab-completion
• staff
  • staff.warn-unverified-staff
  • staff.auto-verify-staff-when-has-lpgroup
  • staff.max-players-per-page-list
  • staff.do-staff-hierarchy
  • staff.max-staff-count
• behaviour
  • behaviour.promote
  • behaviour.suspend
  • behaviour.demote
  • behaviour.staffban
  • behaviour.approve
  • behaviour.activate
  • behaviour.warn
• moderation
  • moderation.add-to-offenses-on-manual-moderation
  • moderation.time-punishment-calculation-method
  • moderation.moderation-provider
• afk
  • afk.threshold-seconds
  • afk.fulfill-requirement-with-afk
• performance
  • performance.tick-ms
  • performance.autosave-secs
  • performance.cache-timeout-secs
  • performance.max-count-player-tab-completion
• messages
  • messages.error-message-format
  • messages.info-message-format
• ranks
  • ranks.linked
  • ranks.default
  • ranks.trainee
• text-render-engine
  • text-render-engine.chat-width-px
  • text-render-engine.do-week-duration-display
• status
• listplayers
• apply
• banscreen

The debug section contains options useful when developing or troubleshooting StaffManager.

Most users should leave these options disabled unless they are specifically trying to diagnose an issue.

Type: boolean
Default: false

What does it do?
Controls whether StaffManager logs output generated by the text renderer and placeholder engine.

If true: Logs text-renderer and placeholder-engine output.

If false: Does not log text-renderer or placeholder-engine output.

Type: boolean
Default: false

What does it do?
Controls whether StaffManager logs database operations performed by the plugin.

If true: Database operations are logged for debugging.

If false: Database operations are not logged.

Type: boolean
Default: true

What does it do?
Controls whether StaffManager logs information about the generation of configurable text elements.

If true: Text-element generation is logged.

If false: Text-element generation is not logged.

Type: boolean
Default: false

What does it do?
Controls debug logging related to command tab completion.

If true: Tab-completion debug information is logged.

If false: Tab-completion debug information is not logged.

The staff section contains general settings that control how StaffManager identifies and manages staff members.

Type: boolean
Default: false

What does it do?
Controls whether StaffManager warns a player when their LuckPerms staff group does not match their StaffManager staff status.

If true: Players are warned when their staff LuckPerms group has been tampered with or no longer matches their StaffManager status.

If false: No warning is shown.

Type: boolean
Default: true

What does it do?
Automatically verifies players who already have a configured staff LuckPerms group.

This is useful when StaffManager is installed on a server that already has an established staff team.

If true: A player with a recognized staff LuckPerms group can be automatically verified as staff.

If false: Staff verification must be performed through the normal StaffManager process.

Type: integer
Default: 10

What does it do?
Sets the maximum number of players displayed on each page of /listplayers.

For example, a value of 10 displays up to 10 players per page.

Type: boolean
Default: false

What does it do?
Controls whether StaffManager checks the staff hierarchy when performing staff management actions.

When enabled, a staff member cannot manage another staff member with an equal or higher staff rank.

Every registered staff rank must have a LuckPerms weight for hierarchy checks to work correctly.

Only players with the required permission are affected by these hierarchy checks.

If true: Staff hierarchy rules are enforced.

If false: Staff hierarchy checks are disabled.

Type: integer
Default: -1

What does it do?
Sets the maximum number of active staff members allowed at one time.

If set to a positive number: StaffManager prevents the server from exceeding that number of active staff members.

If set to -1: No global staff count limit is enforced.

The behaviour section controls the behavior of individual StaffManager commands and staff-management actions.

Settings related to /promote.

Type: boolean
Default: false

What does it do?
Controls whether a player's Discord account must be linked before they can be promoted to staff.

If true: The player must have a linked Discord account before being promoted.

If false: Discord linking is not required for promotion.

Settings related to staff suspensions.

Type: boolean
Default: false

What does it do?
Controls whether a reason is required when manually suspending a staff member.

If true: A reason must be provided when manually suspending a player.

If false: A reason is optional.

Settings related to staff demotions.

Type: boolean
Default: false

What does it do?
Controls whether a player's accumulated staff playtime is reset when they are demoted.

If true: Staff playtime is reset when the player is demoted.

If false: The player's staff playtime is preserved.

Type: boolean
Default: false

What does it do?
Controls whether a reason is required when manually demoting a staff member.

If true: A reason must be provided.

If false: A reason is optional.

Settings related to staff bans.

Type: boolean
Default: false

What does it do?
Controls whether a player's accumulated staff playtime is reset when they receive a staff ban.

If true: Staff playtime is reset when the player is staff-banned.

If false: The player's staff playtime is preserved.

Type: boolean
Default: false

What does it do?
Controls whether a reason is required when manually staff-banning a player.

If true: A reason must be provided.

If false: A reason is optional.

Settings related to staff approval.

Type: boolean
Default: true

What does it do?
Controls whether a staff member must be approved before they can activate their staff status.

If true: An administrator must approve the player before they can activate their staff permissions.

If false: Approval is not required.

Settings related to /activate.

Type: boolean
Default: false

What does it do?
Controls whether StaffManager checks that the player's Discord account is linked when they activate their staff status.

If true: The player must have a linked Discord account when activating staff.

If false: Discord linking is not required during activation.

You can enable both this option and behaviour.promote.require-player-discord-linked if you want the Discord-link requirement to be checked during both stages.

Settings related to warnings.

Type: boolean
Default: false

What does it do?
Controls whether a reason is required when manually warning a player.

If true: A reason must be provided.

If false: A reason is optional.

The moderation section controls how StaffManager handles moderation actions and punishments.

Type: boolean
Default: true

What does it do?
Controls whether manual moderation actions such as /demote, /suspend, /staffban, and /warn add an offense to the player's offense history.

If true: Manual moderation actions add an offense.

If false: Manual moderation actions do not add an offense.

Type: string
Default: MAX

What does it do?
Controls how /punish calculates the duration of timed punishments such as suspensions, staff bans, mutes, and server bans.

Available values:

• MAX — Uses the longest punishment duration.
  • 1s, 10s, 5s → 10s
• LAST — Uses the latest punishment duration.
  • 1s, 10s, 5s → 5s
• SUM — Adds all punishment durations together.
  • 1s, 10s, 5s → 16s

Type: string
Default: STAFFMANAGER

What does it do?
Determines which moderation system handles punishments such as bans and mutes when /punish is used.

Available values:

• STAFFMANAGER — StaffManager handles the moderation itself. To pardon these moderations, use /pardon <player> moderation <moderation>.
• ESSENTIALSX — EssentialsX handles bans and mutes. StaffManager still records additional context that EssentialsX does not provide.
• LITEBANS — LiteBans handles bans and mutes. StaffManager still provides its own /warn command.

For additional context recorded by StaffManager when using an external moderation provider, see /sm printPlayerData <player>.

The afk section controls how AFK time is handled.

Type: integer
Default: 180

What does it do?
Sets how long a player must remain inactive before StaffManager considers them AFK.

The value is measured in seconds.

For example, 180 means the player is considered AFK after 3 minutes of inactivity.

Type: boolean
Default: false

What does it do?
Controls whether time spent AFK counts toward staff playtime requirements.

If true: AFK time counts toward staff playtime requirements.

If false: AFK time does not count toward staff playtime requirements.

The performance section contains settings that affect StaffManager's resource usage and background operations.

Most users should not need to change these values.

Type: integer
Default: 1000

What does it do?
Sets the interval between iterations of StaffManager's main loop.

The value is measured in milliseconds.

Lower values make the main loop run more frequently, while higher values make it run less frequently.

Type: integer
Default: 60

What does it do?
Sets how frequently StaffManager automatically saves data.

The value is measured in seconds.

Type: integer
Default: 900

What does it do?
Sets how long cached player data is kept before it can be removed from the cache.

The value is measured in seconds.

Lower values: Use less RAM, but can cause more database queries and CPU usage when StaffManager commands are used frequently.

Higher values: Use more RAM, but reduce database queries and CPU usage. This can also be useful if you want to reduce hard-drive/database activity.

Type: integer
Default: 15

What does it do?
Sets the maximum number of players that can be returned by StaffManager's player tab completion.

If set to a positive number: At most that many players are shown.

If set to -1: There is no limit.

The messages section controls the format used for StaffManager's informational and error messages.

Text supports Minecraft & color codes and StaffManager placeholders.

Type: string
Default: &b&lStaff &3&lManager &8» {default_color}{type} : {message}

What does it do?
Sets the format used for StaffManager error messages.

Type: string
Default: &b&lStaff &3&lManager &8» {default_color}{message}

What does it do?
Sets the format used for StaffManager informational messages.

The ranks section defines certain LuckPerms groups used by StaffManager.

Type: string
Default: ''

Status: Deprecated

This option is no longer used and is planned for removal.

Type: string
Default: default

Status: Deprecated

This option is no longer used and is planned for removal.

Type: string
Default: trainee

What does it do?
Sets the LuckPerms group assigned to a player when they are first promoted using /promote.

If empty: The initial trainee rank is disabled.

The text-render-engine section controls how StaffManager renders configurable text.

Type: integer
Default: 320

What does it do?
Sets the pixel width used by the text chat renderer.

Most users should not need to change this value.

Type: boolean
Default: false

What does it do?
Controls whether relative time displays can use weeks.

If true: Relative durations can be displayed using weeks.

If false: Relative durations do not use weeks.

The status section controls the configurable layout of /status.

It contains two main parts:

• elements — Reusable pieces of text that can be inserted into screens.
• screens — The actual screens displayed by /status.

Text supports Minecraft & color codes and StaffManager placeholders.

Most text values can contain multiple lines.

Reusable elements can be referenced from screens using their corresponding placeholder.

Controls the progress bar used by {staff-playtime-progress-bar}.

The character or text used for completed progress.

Default: {staff-playtime-progress-color}=

The character or text used for incomplete progress.

Default: &8-

The text placed at the beginning of the progress bar.

Default: &7[

The cursor used to indicate the current progress position.

Default: >

The text placed at the end of the progress bar.

Default: &7]

Type: integer
Default: 32

Sets the length of the progress bar.

Controls the color of the progress bar based on its percentage.

Default:

This means the progress bar transitions from red to yellow to green as progress increases.

Controls the small status bar used by {status-bar}.

Default: &a#

Text used for completed status-bar positions.

Default: &8-

Text used for incomplete status-bar positions.

Default: &7[

Text placed at the beginning of the bar.

Default: &7]

Text placed at the end of the bar.

Type: integer
Default: 4

Sets the length of the status bar.

Controls the text shown based on the player's current staff progression status.

This element is available through:

{promotion-section}

The following conditions can be configured:

Shown when the player is currently working toward becoming staff.

Shown when the player has completed the required playtime and can activate their staff status.

Shown when the player is already staff.

Shown when the player is not currently staff.

Controls the summary of active punishments.

This element is available through:

{punishments-summary}

Text placed before the punishment list.

Defines the text used for each punishment type.

Available conditions include:

• if-mute
• if-server-ban
• if-suspension
• if-staff-ban

Default: ,

Text placed between multiple punishments.

Text placed after the punishment list.

Text displayed when the player has no active punishments.

Default:

&aClean

Controls the player's current StaffManager status.

This element is available through:

{status-text}

StaffManager automatically selects the matching condition.

Available conditions include:

• if-unverified-staff
• if-permanently-banned
• if-banned
• if-ban-expired
• if-permanently-staff-banned
• if-staff-banned
• if-staff-ban-expired
• if-suspended
• if-suspension-expired
• if-non-staff
• if-active-staff-pending-promotion
• if-pending-staff
• if-ready-to-activate-staff
• if-active-staff

Controls how warnings and recorded offenses are displayed.

This element is available through:

{warnings}

Text displayed before the warning list.

Controls the header of each warning/offense entry.

Available placeholders include:

• {rule-name}
• {rule-internal-name}
• {rule-description}
• {rule-offenses}

Controls the display of individual recorded offenses.

Text displayed after each warning/offense entry.

Text displayed after the complete warning list.

Text displayed when the player has no warnings.

Controls the footer added to the bottom of every /status screen.

The default is:

&8:{fill|=|1}:

Controls which /status screens are displayed by default and their order.

The default order is:

1. status
2. punishments

Defines the actual screens available to /status.

The main status screen.

The default configuration displays:

• The STATUS header
• The player's current status
• Their current staff rank
• Their promotion/progression information

The punishment screen.

The default configuration displays:

• The PUNISHMENTS header
• Active punishments
• Warnings

The listplayers section controls the appearance of /listplayers.

Controls the header displayed at the top of the player list.

Controls how each player is displayed.

The default configuration shows:

• Their staff rank
• Their name
• Their playtime

Controls the bottom of the player list.

It includes:

• Previous/next page buttons
• Current page
• Maximum page
• Displayed player range
• Total number of listed players

Contains reusable elements used by /listplayers.

Controls the previous-page button.

Used when a previous page exists.

• text-contents — Text displayed by the button.
• text-hover — Text displayed when hovering over the button.

Used when the player is already on the first page.

• text-contents — Text displayed by the disabled button.
• text-hover — Hover text explaining why it is disabled.

Controls the next-page button.

Used when another page exists.

• text-contents — Text displayed by the button.
• text-hover — Text displayed when hovering over the button.

Used when the player is already on the last page.

• text-contents — Text displayed by the disabled button.
• text-hover — Hover text explaining why it is disabled.

The apply section controls the appearance of /apply.

Controls the instructions displayed at the top of /apply.

The default configuration is:

- '&8:{fill|=|1}&8< &6APPLY &8>{fill|=|1}:'
- ''
- '&71. &fMust be &e13+ years old'
- '&72. &fJoin our Discord &7(/discord)'
- '&73. &fAnswer all questions honestly'
- '&74. &fMeet the playtime requirement'
- ''
- '&eRank Requirements'

Controls how each configured staff rank is displayed.

One entry is generated for each configured staff rank.

Available placeholders include:

• {rank-extended-name}
• {rank-required-playtime-formatted}

The Default configuration is:

- '&8» &b{rank-extended-name} &7- &f{rank-required-playtime-formatted}'

Controls the notes displayed at the bottom of /apply.

The default configuration is:

- ''
- '&eNotes'
- '&8» &7You may apply before reaching the required playtime'
- '&8» &7Denied applications may be submitted again'
- '&8» &7Use &f/status &7to view staff status'
- '&8:{fill|=|1}:'

The banscreen section controls the ban screen shown when STAFFMANAGER is used as the moderation provider.

This section is only used when moderation.moderation-provider is set to STAFFMANAGER.

If another moderation plugin handles bans, such as EssentialsX or LiteBans, its own ban-screen configuration should be used instead.

Controls the text displayed on the ban screen.

Available placeholders include:

• {expiry-date} — The date and time when the ban expires.
• {reasons} — The formatted punishment reasons.

Controls how multiple punishment reasons are formatted.

Text placed before the reasons.

Text placed between multiple reasons.

Default: |

Text placed after the reasons.