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: The number of threads allocated in a dedicated thread pool for handling asynchronous API requests to your panel. Increasing this might improve responsiveness if you manage a very large number of servers and experience API-related delays, but it also consumes more system resources.
Type: Integer
Default: 10
Action: Changes to this value require a full restart of the Velocity proxy.
Example: apiThreads: 10

`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

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

`limboServer`

Description: The name of a server (as defined in your velocity.toml) to which players will be temporarily redirected while their target VPP-managed server is starting up. This provides a waiting area instead of disconnecting the player.
Type: String
Action: If set to "changeMe" or an invalid/unregistered server name, the limbo functionality is effectively disabled, and players might be disconnected if their target server is offline.
Default: "changeMe"
Example: limboServer: "lobby"
Limbo Server Considerations
- The limbo server should be lightweight and always accessible.
- If the limbo server itself is managed by VPP, ensure its timeout setting (in the servers section) is configured appropriately (e.g., -1 to prevent auto-shutdown, or a very short timeout if it's designed to be ephemeral but quick to start).

`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

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 plcn_.
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: 8)

yaml

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

# Version of the configuration file
fileversion: 8

# Check for updates
checkUpdate: true

# Choose which logging level should be used
# 10 = Debug, 20 = Info, 30 = Warning, 40 = Error
loggerLevel: 20

# How many Threads should be used for API requests
apiThreads: 10

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

# Choose the method to check if a managed server is online
# "VELOCITY_PING" or "PANEL_API"
serverStatusCheckMethod: "VELOCITY_PING"

# Timeout for VELOCITY_PING (in milliseconds)
pingTimeout: 1000

# Retries for shutdown if previous failed
shutdownRetries: 3

# Delay before retrying shutdown (in seconds)
shutdownRetryDelay: 300

# Time before shutting down a server if no player joined after start (in seconds)
# -1 = disabled
idleStartShutdownTime: 300

# Cooldown for players starting a server (in seconds)
playerStartCooldown: 10

# Limbo server name (from velocity.toml)
# "changeMe" = disabled
limboServer: changeMe

# Initial delay before first online check after starting a server (in seconds)
startupInitialCheckDelay: 10

# Servers to ignore for /ptero stopIdle command
stopIdleIgnore:
  - hub
  - lobby
  - limbo

# Send message to player if server not in VPP config
serverNotFoundMessage: false

# Allow players with ptero.bypass to bypass VPP's whitelist check
whitelistAllowBypass: true

# Interval for periodic whitelist checks (in minutes)
# 0 or less = disabled
whitelistCheckInterval: 10

# Panel configuration
pterodactyl:
  url: "https://panel.example.com/"
  apiKey: "ptlc_000000000000000000000000000000000000000000"

# Per server configuration
# Server names must match velocity.toml
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

Configuration Guide ⚙️

General Settings

`fileversion`

`checkUpdate`

`loggerLevel`

`apiThreads`

`printRateLimit`

Server Status & Behavior

`serverStatusCheckMethod`

`pingTimeout`

`shutdownRetries`

`shutdownRetryDelay`

`idleStartShutdownTime`

`playerStartCooldown`

`limboServer`

`startupInitialCheckDelay`

`stopIdleIgnore`

`serverNotFoundMessage`

Whitelist Settings

`whitelistAllowBypass`

`whitelistCheckInterval`

Panel Connection (`pterodactyl`)

`pterodactyl.url`

`pterodactyl.apiKey`

Per-Server Configuration (`servers`)

`servers.<serverName>`

`id`

`timeout`

`startupJoinDelay`

`whitelist`

Configuration Guide ⚙️ ​

General Settings ​

fileversion ​

checkUpdate ​

loggerLevel ​

apiThreads ​

printRateLimit ​

Server Status & Behavior ​

serverStatusCheckMethod ​

pingTimeout ​

shutdownRetries ​

shutdownRetryDelay ​

idleStartShutdownTime ​

playerStartCooldown ​

limboServer ​

startupInitialCheckDelay ​

stopIdleIgnore ​

serverNotFoundMessage ​

Whitelist Settings ​

whitelistAllowBypass ​

whitelistCheckInterval ​

Panel Connection (pterodactyl) ​

pterodactyl.url ​

pterodactyl.apiKey ​

Per-Server Configuration (servers) ​

servers.<serverName> ​

id ​

timeout ​

startupJoinDelay ​

whitelist ​

Configuration Guide ⚙️

General Settings

`fileversion`

`checkUpdate`

`loggerLevel`

`apiThreads`

`printRateLimit`

Server Status & Behavior

`serverStatusCheckMethod`

`pingTimeout`

`shutdownRetries`

`shutdownRetryDelay`

`idleStartShutdownTime`

`playerStartCooldown`

`limboServer`

`startupInitialCheckDelay`

`stopIdleIgnore`

`serverNotFoundMessage`

Whitelist Settings

`whitelistAllowBypass`

`whitelistCheckInterval`

Panel Connection (`pterodactyl`)

`pterodactyl.url`

`pterodactyl.apiKey`

Per-Server Configuration (`servers`)

`servers.<serverName>`

`id`

`timeout`

`startupJoinDelay`

`whitelist`