Configuration Guide ⚙️

The main configuration for VelocityPteroPower is located in the config.yml file within the plugins/VelocityPteroPower/ folder. This file is automatically generated with default values the first time you run the plugin.

Always Backup!

Before making significant changes to your configuration, it's always a good practice to create a backup of your config.yml file.

This guide explains each configuration option available.

General Settings

`fileversion`

Description: Internal version number for the configuration file. This is used by the plugin to automatically manage updates to the config structure between plugin versions.
Action: Do not change this value manually.
Default: (Automatically set by the plugin, e.g., 8)

`checkUpdate`

Description: If true, the plugin will check for new versions of VelocityPteroPower on startup. If an update is found, a message will be displayed in the console.
Type: Boolean
Default: true
Example: checkUpdate: true

`loggerLevel`

Description: Controls the verbosity of messages logged by VelocityPteroPower to the Velocity console.
Type: Integer
Accepted Values:
- 10: DEBUG (Most detailed information, useful for troubleshooting issues)
- 20: INFO (Standard operational messages, recommended for production)
- 30: WARNING (Potential issues or non-critical errors)
- 40: ERROR (Critical errors that may impair functionality)
Default: 20
Example: loggerLevel: 20
For Troubleshooting
When reporting issues, setting loggerLevel: 10 can provide valuable diagnostic information. Remember to set it back to 20 for normal operation to avoid excessive console spam.

`apiThreads`

Description: Threads for the plugin's HTTP/API executor. VPP auto-scales the pool to roughly 2 x (number of managed servers), clamped to a minimum of 4 and a maximum of 64. If you set apiThreads higher than this auto baseline, your configured value overrides the baseline and will be used instead.
Type: Integer
Default: 10
Action: Requires a reload/restart to take effect.
Formula: baseline = clamp(servers * 2, 4, 64); final = max(apiThreads, baseline)
Examples:
- 3 servers → baseline 6 → final uses max(apiThreads, 6)
- 20 servers → baseline 40 → final uses max(apiThreads, 40)
- 40 servers → baseline 64 (clamped) → final uses max(apiThreads, 64)
- You set apiThreads: 100 → final 100 (overrides baseline)
Command: Use /ptero apithreads (permission: ptero.info) to display the configured value, server count, baseline, and the value currently in use.

`printRateLimit`

Description: If true, the plugin will log information about the current API rate limit status (limit, remaining requests) received from the panel after API calls. This is useful for diagnosing if API rate limiting is affecting the plugin's operation.
Type: Boolean
Default: false
Example: printRateLimit: false

`languageOverride`

Description: Override the language used for plugin messages. Set to a locale like "en_US" or "de_DE" to force a specific language. Use "auto" to follow the environment (system/Velocity) language.
Type: String
Default: auto
Example: languageOverride: en_US
Notes: Message files are stored under plugins/VelocityPteroPower/messages/<lang>.yml. A legacy single messages.yml file is no longer used.

Server Status & Behavior

`serverStatusCheckMethod`

Description: Determines how VPP checks if a managed Minecraft server is online and ready.
Type: String
Accepted Values:
- "VELOCITY_PING": Uses Velocity's built-in server pinging mechanism.
  - Pros: Less resource-intensive on the panel API; doesn't consume API rate limit quotas.
  - Cons: Requires the server to be correctly registered in velocity.toml and network-accessible from the proxy. Might report a server as "online" slightly before it's fully joinable (e.g., before all backend plugins load). Some very minimal limbo servers might not respond to pings correctly.
- "PANEL_API": Directly queries the Pterodactyl/Pelican/MC Server Soft panel API for the server's current state (e.g., "running", "offline").
  - Pros: Generally more accurate regarding the actual state of the server process as reported by the panel.
  - Cons: Uses an API request for each check, contributing to rate limit usage. Can be slightly slower due to API call latency.
Default: "VELOCITY_PING"
Example: serverStatusCheckMethod: "VELOCITY_PING"

`pingTimeout`

Description: If serverStatusCheckMethod is set to "VELOCITY_PING", this is the maximum time (in milliseconds) VPP will wait for a ping response from a backend server before considering it offline or unreachable.
Type: Integer (milliseconds)
Default: 1000 (1 second)
Example: pingTimeout: 1000

`shutdownRetries`

Description: If VPP sends a "stop" signal to a server and the server doesn't appear to shut down (based on subsequent status checks), VPP will retry sending the "stop" signal this many times.
Type: Integer
Default: 3
Example: shutdownRetries: 3

`shutdownRetryDelay`

Description: The time (in seconds) VPP will wait between failed shutdown attempts before retrying.
Type: Integer (seconds)
Default: 300 (5 minutes)
Example: shutdownRetryDelay: 300

`idleStartShutdownTime`

Description: If a server is started by VPP (either by a player connecting or via command) but no player successfully joins it within this duration (in seconds), VPP will automatically shut it down. This prevents servers from staying online indefinitely if they were started but never actually used.
Type: Integer (seconds)
Set to -1 to disable this feature.
Default: 300 (5 minutes)
Example: idleStartShutdownTime: 300

`playerStartCooldown`

Description: The cooldown period (in seconds) a player must wait before they can initiate the start of another server, does not work for the /ptero start command.
Type: Integer (seconds)
Default: 10
Example: playerStartCooldown: 10

Limbo servers

Use the lobbyBalancer.limbos list to define one or more limbo servers (by their Velocity names) where players can wait while a target server is starting.
Any previous limboServer setting is deprecated and will be automatically migrated to lobbyBalancer.limbos when the plugin loads.
Tips:
- Keep limbo servers lightweight and always accessible (or quick to start).
- If a limbo is managed by VPP (listed under servers: with an id), configure its timeout as needed (e.g., -1 to keep it always online).

`startupInitialCheckDelay`

Description: After VPP sends a "start" signal to a server, it will wait this many seconds before performing the first status check to see if the server has come online.
Type: Integer (seconds)
Default: 10
Example: startupInitialCheckDelay: 10
Note
The per-server startupJoinDelay is applied after this initial check confirms the server is online, before a player is connected.

`stopIdleIgnore`

Description: A list of server names (as defined in velocity.toml and VPP's servers section) that will be ignored by the /ptero stopidle command. These servers will not be shut down by this specific command even if they are empty.
Type: List of String
Default: ["hub", "lobby", "limbo"]
Example:
yaml
```
stopIdleIgnore:
  - lobby1
  - lobby2
  - hub
```
Important
This list only affects the /ptero stopidle command. It does not prevent automatic shutdown based on a server's timeout setting or the global idleStartShutdownTime. It also does not affect the /ptero forcestopall command.

`serverNotFoundMessage`

Description: If true, when a player attempts to connect to a server name that is registered in velocity.toml but not configured in VPP's servers section, the player will receive a "server not found in configuration" message. A message is always logged to the console regardless of this setting.
Type: Boolean
Default: false
Example: serverNotFoundMessage: false

`maxOnlineServers`

Description: Limits how many managed servers may be online concurrently. 0 means unlimited.
Type: Integer
Default: 0
Example: maxOnlineServers: 3

`maxOnlineAllowBypass`

Description: If true, players with the ptero.maxcap.bypass permission can bypass the maxOnlineServers cap.
Type: Boolean
Default: true
Example: maxOnlineAllowBypass: true

`maxOnlineExempt`

Description: A list of server names that are exempt from the maxOnlineServers cap.
Type: List of String
Default: ["hub", "lobby", "limbo"]

Example:

yaml

maxOnlineExempt:
  - hub
  - lobby
  - limbo

`countLobbiesInMaxOnline`

Description: If true, lobbies defined under lobbyBalancer.lobbies are counted toward the global maxOnlineServers cap. If false, those lobbies are excluded automatically when enforcing the cap.
Type: Boolean
Default: false
Notes: Only managed servers (listed under servers:) are counted by the cap at all. If lobbiesToUse > 0, only the first N lobbies are affected by this setting.

`countLimbosInMaxOnline`

Description: If true, limbos (from lobbyBalancer.limbos) are counted toward maxOnlineServers. If false, they are excluded automatically when enforcing the cap.
Type: Boolean
Default: false

`alwaysOnline`

Description: A list of server names that VPP should keep online at all times. The plugin will periodically check and start them if offline. This setting outranks per-server timeout, i.e., such servers will not be auto-shutdown.
Type: List of String
Default: ["limbo"]
Example:
yaml
```
alwaysOnline:
  - limbo
```

`alwaysOnlineCheckInterval`

Description: How often to check/enforce the alwaysOnline list (in seconds).
Type: Integer (seconds)
Default: 60
Example: alwaysOnlineCheckInterval: 60

`resourceCacheSeconds`

Description: How long to cache resource usage responses from the panel (in seconds). Set to 0 to disable caching.
Type: Integer (seconds)
Default: 10
Example: resourceCacheSeconds: 10

`resourcePrefetchEnabled`

Description: If true, VPP will periodically prefetch resource usage for all managed servers every resourceCacheSeconds, keeping the cache warm so commands like /ptero list and /ptero info feel snappy.
Type: Boolean
Default: true
Example: resourcePrefetchEnabled: true

`idleShutdownCheckInterval`

Description: Periodic failsafe sweep interval (in seconds). VPP scans all managed servers and schedules idle shutdowns for empty ones (respecting alwaysOnline, per-server timeout, and only when the server is online). Set to 0 or a negative number to disable.
Type: Integer (seconds)
Default: 60
Example: idleShutdownCheckInterval: 60

Lifecycle

`lifecycle.shutdownOnProxyExit`

Description: Defines which servers should be force-stopped when the Velocity proxy shuts down. This setting overrides alwaysOnline during shutdown.
Type: List of String
Accepted values:
- all — stop all managed servers
- or a list of specific server names to stop
Default: disabled (empty list)

Example:

yaml

lifecycle:
  shutdownOnProxyExit:
    - lobby
    - survival

or to stop everything:

yaml

lifecycle:
  shutdownOnProxyExit:
    - all

Always-online on startup

Servers listed in alwaysOnline will be started automatically on proxy startup (once) and then kept online by periodic maintenance.

Whitelist Settings

`whitelistAllowBypass`

Description: If true, players with the ptero.bypass permission can bypass VPP's whitelist check when attempting to start/connect to a server that has whitelist: true in its per-server configuration.
Type: Boolean
Default: true
Example: whitelistAllowBypass: true
Important Distinction
This setting only bypasses VPP's pre-connection check. It does not allow players to bypass the actual whitelist.json enforced by the backend Minecraft server itself. If a player bypasses VPP's check but is not on the backend server's whitelist, they will still be unable to join.

`whitelistCheckInterval`

Description: The interval (in minutes) at which VPP will periodically attempt to re-fetch the whitelist.json file from servers that have whitelist: true configured. This helps keep VPP's internal whitelist cache up-to-date.
Type: Integer (minutes)
Set to 0 or a negative value to disable periodic automatic updates. Whitelists will still be fetched on plugin load/reload and via /ptero whitelistReload.
Default: 10
Example: whitelistCheckInterval: 10
MC Server Soft Limitation
The whitelist fetching feature (and thus this interval) is not supported if your panel is MC Server Soft due to API differences.

Panel Connection (`pterodactyl`)

INFO

This section of the config is still named pterodactyl for compatibility reasons, even if you are using Pelican or MC Server Soft. The plugin will automatically detect the panel type based on the API key format.

This section contains the crucial details for connecting to your panel url.

`pterodactyl.url`

Description: The full base URL of your panel.
Type: String
Required: Yes
Format: Must include the protocol (http:// or https://). It's generally recommended to ensure it ends with a / if your panel requires it for API access (most do).
Example: url: "https://panel.yourdomain.com/"
Cloudflare & Proxies
If you are using Cloudflare, a reverse proxy, or a tunnel in front of your panel, ensure that the URL points to the accessible endpoint and that any necessary IP bypass or security rules are configured to allow VPP to reach the API.

`pterodactyl.apiKey`

Description: Your Client API Key for the panel.
Type: String
Required: Yes
Format:
- For Pterodactyl Panel: The key should start with ptlc_.
- For Pelican Panel: The key should start with pacc.
Location: You can generate/find this key in your account settings on the panel, usually under "API Credentials" or a similar section.
Example: apiKey: "ptlc_YOUR_CLIENT_API_KEY_HERE"
Critical: Use Client API Keys Only!
You must use a Client API Key. Application API Keys (which might start with ptla_ for Pterodactyl or peli_ for Pelican) are NOT supported by VPP and will result in connection failures. The Client API Key grants permissions on behalf of your user account.
Information for MC Server Soft Users
Mc Server Soft doesnt have any kind of distinction between types of Api Keys. There is just one type.

Per-Server Configuration (`servers`)

This section is where you define each individual Minecraft server that VelocityPteroPower should manage. Each entry is a sub-section named after the server as it appears in your velocity.toml.

`servers.<serverName>`

Description: This is the block for a specific server. Replace <serverName> with the actual name of your server (e.g., lobby, survival, minigames). This name must exactly match the server name defined in your Velocity velocity.toml file (case-sensitive).
Inside each <serverName> block, you define the following:
id
- Description: The unique identifier of this server on your panel.
- Type: String
- Required: Yes
- How to find:
  - Pterodactyl: Look at the URL when viewing the server in the panel. If the URL is https://panel.example.com/server/a1b2c3d4, then the ID is a1b2c3d4.
  - Pelican: This is typically the "Short UUID" found in the server's details page on the panel.
- Example: id: "a1b2c3d4"
timeout
- Description: The time (in seconds) VPP will wait after the last player leaves this specific server before automatically sending a "stop" signal.
- Type: Integer (seconds)
- Set to -1 to disable automatic shutdown for this server when it becomes empty.
- Set to 0 to attempt to stop the server immediately after the last player leaves.
- Default (if not specified for a server, though it's good practice to specify): The plugin might have an internal default, but explicitly set it.
- Example: timeout: 300 (5 minutes)
startupJoinDelay
- Description: After VPP detects that this server has successfully started and is "online" (according to serverStatusCheckMethod), it will wait an additional period (in seconds) defined by this value before attempting to connect waiting players to it. This delay allows backend server plugins and worlds to fully load and initialize.
- Type: Integer (seconds)
- Default (if not specified): 10 (as seen in the example config)
- Example: startupJoinDelay: 15 (wait 15 seconds after server reports online)
whitelist
- Description: If true, VPP will attempt to fetch the whitelist.json file for this server from the panel and enforce it for players attempting to start or connect to this server (unless bypassed by permission).
- Type: Boolean
- Default: false
- Example: whitelist: true
  MC Server Soft Limitation
  As mentioned previously, the whitelist fetching feature is not supported if your panel is MC Server Soft. Setting this to true for an MC Server Soft panel will likely result in VPP logging warnings and the whitelist check being ineffective.

Example config.yml (fileversion: 13)

yaml


###########################################################
#                    VelocityPteroPower                  #
#                       by TubYoub                      #
###########################################################

# Version of the configuration file
fileversion: '13'

checkUpdate: true

# Override the language used for plugin messages.
# Set to a locale like "en_US" or "de_DE" to force a specific language.
# Use "auto" to follow the environment (system/Velocity) language.
# default: auto
languageOverride: auto

# Choose which logging level should be used
# It depends on how much you want you're console to be filled with information from VPP
# For production you can safely set it to a higher level but for development/testing it is recommended to use a lower level
# 10 = Debug
# 20 = Info
# 30 = Warning
# 40 = Error
#default: 20
loggerLevel: 10

# How many Threads should be used to check the server status
# The more threads the more requests can be handled at the same time
# more threads = more resources used
# restart the server so changes take effect
# default: 10
apiThreads: 10

# print updated Rate Limit from the API response to console
# default: false
printRateLimit: false

# Choose the method to check if a managed server is online and ready.
# "VELOCITY_PING": Uses Velocity's built-in ping functionality. Requires the server
#                  to be registered in Velocity's config and accessible from the proxy.
#                  Less resource-intensive, doesn't use API rate limits. Might report
#                  online slightly before the server is fully joinable.
#                  Some simple Limbo servers might not report any Ping back suing this method.
# "PANEL_API": Uses the Pterodactyl/Pelican panel API to check the server's state.
#                    More accurate for actual server state ("running"), but uses API
#                    requests and counts towards rate limits.
# Default: "VELOCITY_PING"
serverStatusCheckMethod: PANEL_API

# How long the ping to the server lasts, to check if its is online, until it times out (in milliseconds)
# default: 1000
pingTimeout: 5000

# How many retrys to shut down the server if the previous one failed
# default: 3
shutdownRetries: 3

# How long to wait before retrying to shut down the server (in seconds)
# default: 30
shutdownRetryDelay: 30

# How long to wait before shutting down the server if no player joined the server(in seconds)
# default: 300
# -1 = disabled
idleStartShutdownTime: 300

# How long to wait before allowing a player to start a server again (in seconds)
# default: 10
playerStartCooldown: 10

# How long (in seconds) the plugin should wait for the first check if the server is online
# The joinDelay (configured for each server) is still applied when the server is online before a
# player is automatically connected (so it doesn't affect this)
# Maybe consider changing this to a lower value if you have for example a
# limbo which is lightweight and starts fast
# default: 10
startupInitialCheckDelay: 10

# Servers to ignore when the stopIdle command is used
# THIS DOES NOT AFFECT forceStop
stopIdleIgnore:
- hub
- limbo

# If a player should receive a message when a server is not found in the config
# message will always be send to console
# default: false
serverNotFoundMessage: false

# Allow players with the permission "ptero.bypass" to bypass the whitelist when starting a server.
# This does not work to get around a whitelist because it is enforced by the backend server itself.
# default: true
whitelistAllowBypass: false

# How long (in minutes) VPP should wait in between checks for a new whitelist and enforce it (if enabled)
# default: 10
whitelistCheckInterval: 10

# Limit how many managed servers may be online concurrently. 0 = unlimited
# default = 0
maxOnlineServers: 0

# Allow players with the permission "ptero.maxcap.bypass" to bypass the maxOnlineServers cap when starting servers.
# default: true
maxOnlineAllowBypass: true

# Servers excluded from the above cap (by Velocity server name)
maxOnlineExempt:
- hub
- limbo

# Whether to include lobbyBalancer lobbies in the maxOnlineServers count
# default: false
countLobbiesInMaxOnline: false

# Whether to include lobbyBalancer limbos in the maxOnlineServers count
# default: false
countLimbosInMaxOnline: false

# Servers that should always be kept online. The plugin will periodically check and start them if offline.
alwaysOnline:
- hub
- limbo

# How often to check/enforce the alwaysOnline list (in seconds)
# default = 60
alwaysOnlineCheckInterval: 60

# Resource usage caching for panel queries
# How long to cache resource usage responses (in seconds). Set to 0 to disable caching.
# default = 10
resourceCacheSeconds: 10

# If enabled, the plugin will periodically prefetch resource usage for all managed servers
# every 'resourceCacheSeconds' to keep the cache warm and make commands snappy.
# default = true
resourcePrefetchEnabled: true

# Automatic idle shutdown sweep (failsafe)
# Periodically checks all managed servers and schedules idle shutdowns if they are empty.
# This safeguards against missed events or errors preventing scheduling.
# Set to 0 or negative to disable.
# default = 60
idleShutdownCheckInterval: 60

# Lifecycle related behavior
lifecycle:
  # When the proxy shuts down, stop these servers.
  # Use "all" to stop all managed servers, or provide a list of specific server names.
  # This overrides 'alwaysOnline' during shutdown.
  shutdownOnProxyExit: []

# Multi-lobby/limbo balancer settings
lobbyBalancer:
  # A list of lobby servers to use for player transfers and first-join routing (if you route players there).
  # Order matters if lobbiesToUse is set; only the first N will be considered active.
  lobbies:
  - hub
  
  # Optional list of limbo servers to use while target servers are starting.
  limbos:
  - limbo
  
  # How many lobbies from the list above should be considered for balancing (0 = use all listed)
  # default = 0
  lobbiesToUse: 0
  
  # Balancer strategy: ROUND_ROBIN, LEAST_PLAYERS, or LEAST_CPU
  # default = ROUND_ROBIN
  strategy: ROUND_ROBIN
  
  # Periodic health check interval in seconds for verifying reachability and planning scale-ups
  # default = 15
  healthCheckInterval: 15
  
  # Keep at least this many lobby servers online (0 = no minimum)
  # default = 1
  minOnline: 1
  
  # Do not keep more than this many lobby servers online (0 = unlimited)
  # default = 0
  maxOnline: 0
  
  # Approximate players-per-lobby capacity used to decide when to scale up
  # default = 80
  playersPerServer: 80
  
  # Only used with LEAST_CPU strategy. If any lobby exceeds this CPU percent, consider scaling up
  # default = 85.0
  cpuScaleUpThreshold: 85.0
  
  # If true, balancer will auto-start additional lobbies when needed
  # default = true
  autoScaleEnabled: true
  
  # Start another lobby before capacity is completely full.
  # When total players across online lobbies reach this percent of capacity, VPP starts another lobby (if available).
  # default = 80 (means start a new lobby at ~80% of total lobby capacity)
  preStartThresholdPercent: 80
  
  # If a lobby was started but doesn't come online within this many seconds, VPP will try starting a different lobby.
  # default = 60
  startFailureFallbackSeconds: 60
  
  # After a failed start, wait this many seconds before trying that same lobby again.
  # default = 120
  startFailureCooldownSeconds: 120
  
  # When a target server is starting, send players to a limbo (if available) and auto-queue them.
  # If false, players will stay on their current server (or be disconnected if coming from proxy) while queued.
  # default = false
  sendToLimboOnStart: true
  
  # Behavior for forced-host joins when the target backend is offline
  # DISCONNECT       → disconnect (default)
  # LOBBY_OR_LIMBO  → try a lobby first, then a limbo; if none, disconnect
  # LIMBO_ONLY      → only try limbo; if none, disconnect
  forcedHostOfflineBehavior: LOBBY_OR_LIMBO

# Pterodactyl configuration
pterodactyl:
  # The URL of your pterodactyl panel
  # If you use Cloudflare Tunnel, you need to allow the ip in the bypass setting.
  url: https://panel.domain.tld/
  # Your API Key should start with "ptlc_" or "pacc" if you are using the Ptero or Peli Panel
  # You can find the client api key in the "API Credentials" tab of the "Account" page.
  apiKey: ptlc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

# Per server configuration
servers:
  lobby: # Example server 1
    id: "a1b2c3d4"
    timeout: -1 # Never auto-stop lobby
    startupJoinDelay: 5
    whitelist: false
  survival: # Example server 2
    id: "e5f6g7h8"
    timeout: 600 # Stop after 10 minutes empty
    startupJoinDelay: 15
    whitelist: true
  minigame-1: # Example server 3
    id: "i9j0k1l2"
    timeout: 120 # Stop after 2 minutes empty
    startupJoinDelay: 10
    whitelist: false

Multi-Lobby and Limbo Balancer

VelocityPteroPower supports multiple lobbies and limbos for player redirection and waiting rooms while target servers are starting. This feature is fully configurable via the lobbyBalancer section in config.yml.

Why use multiple lobbies/limbos?

Distribute players evenly (round-robin) or intelligently (least players, least CPU)
Keep a defined number of lobbies online and auto-start more when load increases
Provide redundancy: if one lobby/limbo is offline, others can still be used

Configuration (`lobbyBalancer`)

yaml

lobbyBalancer:
  # A list of lobby servers to use for player transfers and first-join routing (if you route players there).
  # Order matters if lobbiesToUse is set; only the first N will be considered active.
  lobbies:
    - lobby
    - hub

  # Optional list of limbo servers to use while target servers are starting.
  limbos:
    - limbo

  # How many lobbies from the list above should be considered for balancing (0 = use all listed)
  lobbiesToUse: 0

  # Balancer strategy: ROUND_ROBIN, LEAST_PLAYERS, or LEAST_CPU
  strategy: "ROUND_ROBIN"

  # Periodic health check interval in seconds for verifying reachability and planning scale-ups
  healthCheckInterval: 15

  # Keep at least this many lobby servers online (0 = no minimum)
  minOnline: 1

  # Do not keep more than this many lobby servers online (0 = unlimited)
  maxOnline: 0

  # Approximate players-per-lobby capacity used to decide when to scale up
  playersPerServer: 80

  # Only used with LEAST_CPU strategy. If any lobby exceeds this CPU percent, consider scaling up
  cpuScaleUpThreshold: 85.0

  # If true, balancer will auto-start additional lobbies when needed
  autoScaleEnabled: true

  # Start another lobby before capacity is completely full
  preStartThresholdPercent: 80

  # If a lobby doesn't come online in time, try a different one
  startFailureFallbackSeconds: 60

  # Cooldown before retrying a failed lobby
  startFailureCooldownSeconds: 120

Fine-tuning (optional)

sendToLimboOnStart: When a target server is starting, send players to a limbo (if available) and auto-queue them to be moved once the server is ready. If false, players will remain on their current server (or be disconnected if they came from proxy) while queued. Default: false.
forcedHostOfflineBehavior: Controls what happens when a player connects via a forced host and the target backend is offline. Options: DISCONNECT (default), LOBBY_OR_LIMBO (try lobby first, then limbo), LIMBO_ONLY (only try limbo). Works independently of sendToLimboOnStart so you can keep that false but still avoid disconnects for first-join players.
preStartThresholdPercent: Start another lobby a bit earlier so players don’t pile up when you’re close to full. Example: 80 means “start new at ~80% capacity”.
startFailureFallbackSeconds: If a lobby was started but still isn’t online after this many seconds, VPP will try starting a different lobby.
startFailureCooldownSeconds: After a failed start, VPP will wait this long before trying that same lobby again.

How it works

Selection:
- Lobbies are preferred over limbos if available; otherwise a limbo is used.
- Strategy determines which specific server is chosen:
  - ROUND_ROBIN: cycles through available servers
  - LEAST_PLAYERS: picks the server with the fewest connected players
  - LEAST_CPU: uses panel resource endpoint to choose the lowest CPU server
Health and scaling:
- Periodically checks reachability of configured lobbies.
- Ensures at least minOnline lobbies are running (auto-starts if necessary).
- If overall lobby capacity is >90% full (players vs playersPerServer) or LEAST_CPU threshold is exceeded, auto-starts an additional lobby if possible.
If no limbos are usable, players may be disconnected or kept where they are until the target starts.

Notes

For auto-start/CPU-based decisions VPP can only control servers that are listed under the servers: section with valid panel IDs. Unmanaged servers must already be online to be considered usable.
Logging respects your global loggerLevel; set 10 for detailed debugging during setup.

Configuration

Important note about server IDs under servers:

Always wrap the id value in quotes. YAML can parse values like 91e62747 as a number in scientific notation. This may overflow to Infinity, causing the plugin to misread the ID.
Correct: servers: mc-vanilla-6: id: "91e62747"
Incorrect (will be parsed as a number): servers: mc-vanilla-6: id: 91e62747

If the plugin reports an error like "Invalid type for 'id' ... Quote the ID in YAML", edit your config to quote the id and reload the plugin.

Messages & Localization

VPP’s player- and console-facing texts are stored in simple YAML “message files.” This lets you translate or customize wording without changing the plugin JAR.

Location on disk: plugins/VelocityPteroPower/messages/
File naming: <locale>.yml (for example en_US.yml, de_DE.yml)
Shipped locales: en_US (English), de_DE (German)
Fallbacks: If a key is missing in your selected locale, VPP falls back to en_US for that key.

Choosing the language

Global override: Set languageOverride in config.yml
- auto (default): Uses the environment (Velocity/system) locale when available
- en_US, de_DE, or another locale code: Forces that language for all messages

yaml

# In config.yml
languageOverride: auto  # or "en_US" / "de_DE"

Editing messages safely

Format: Messages use MiniMessage formatting (Velocity). You can use colors, bold, and simple tags like <green>, <bold>, etc.
Placeholders: Some messages include placeholders like <server>, <time>, <player>, <reason>. Keep these placeholders intact or your message may miss important data.
Multi-line: YAML strings can be quoted or written as | block scalars if you prefer multi-line text.

Quick reload

After editing files in plugins/VelocityPteroPower/messages/, run /ptero reload to apply changes without restarting Velocity.

Adding a new language

Copy en_US.yml to a new file named with your locale code (for example fr_FR.yml).
Translate the values on the right-hand side, keeping any placeholders (e.g., <server>) unchanged.
Set languageOverride: fr_FR (or leave auto if your environment uses that locale).

Keeping up with updates

When VPP adds new messages in updates, compare your custom file with the latest en_US.yml and add missing keys.
If a key is removed upstream, keeping it in your custom file won’t break anything, but it will no longer be used.
If a message doesn’t exist in your file, VPP uses the en_US default for that key.

Configuration Guide ⚙️ ​

General Settings ​

fileversion ​

checkUpdate ​

loggerLevel ​

apiThreads ​

printRateLimit ​

languageOverride ​

Server Status & Behavior ​

serverStatusCheckMethod ​

pingTimeout ​

shutdownRetries ​

shutdownRetryDelay ​

idleStartShutdownTime ​

playerStartCooldown ​

Limbo servers ​

startupInitialCheckDelay ​

stopIdleIgnore ​

serverNotFoundMessage ​

maxOnlineServers ​

maxOnlineAllowBypass ​

maxOnlineExempt ​

countLobbiesInMaxOnline ​

countLimbosInMaxOnline ​

alwaysOnline ​

alwaysOnlineCheckInterval ​

resourceCacheSeconds ​

resourcePrefetchEnabled ​

idleShutdownCheckInterval ​

Lifecycle ​

lifecycle.shutdownOnProxyExit ​

Whitelist Settings ​

whitelistAllowBypass ​

whitelistCheckInterval ​

Panel Connection (pterodactyl) ​

pterodactyl.url ​

pterodactyl.apiKey ​

Per-Server Configuration (servers) ​

servers.<serverName> ​

id ​

timeout ​

startupJoinDelay ​

whitelist ​

Multi-Lobby and Limbo Balancer ​

Why use multiple lobbies/limbos? ​

Configuration (lobbyBalancer) ​

Fine-tuning (optional) ​

How it works ​

Notes ​

Configuration ​

Messages & Localization ​

Choosing the language ​

Editing messages safely ​

Adding a new language ​

Keeping up with updates ​

Configuration Guide ⚙️

General Settings

`fileversion`

`checkUpdate`

`loggerLevel`

`apiThreads`

`printRateLimit`

`languageOverride`

Server Status & Behavior

`serverStatusCheckMethod`

`pingTimeout`

`shutdownRetries`

`shutdownRetryDelay`

`idleStartShutdownTime`

`playerStartCooldown`

Limbo servers

`startupInitialCheckDelay`

`stopIdleIgnore`

`serverNotFoundMessage`

`maxOnlineServers`

`maxOnlineAllowBypass`

`maxOnlineExempt`

`countLobbiesInMaxOnline`

`countLimbosInMaxOnline`

`alwaysOnline`

`alwaysOnlineCheckInterval`

`resourceCacheSeconds`

`resourcePrefetchEnabled`

`idleShutdownCheckInterval`

Lifecycle

`lifecycle.shutdownOnProxyExit`

Whitelist Settings

`whitelistAllowBypass`

`whitelistCheckInterval`

Panel Connection (`pterodactyl`)

`pterodactyl.url`

`pterodactyl.apiKey`

Per-Server Configuration (`servers`)

`servers.<serverName>`

`id`

`timeout`

`startupJoinDelay`

`whitelist`

Multi-Lobby and Limbo Balancer

Why use multiple lobbies/limbos?

Configuration (`lobbyBalancer`)

Fine-tuning (optional)

How it works

Notes

Configuration

Messages & Localization

Choosing the language

Editing messages safely

Adding a new language

Keeping up with updates