Configuration

Default configuration file contents

Click to reveal

{
  "paper": {
    "use-mini-messages": false
  },
  "database": {
    "enabled": false,
    "driver": "SQLite",
    "drivers": [
      {
        "name": "SQLite",
        "class": "SQLiteImplementation",
        "download-driver": true,
        "download-url": "https://repo1.maven.org/maven2/org/xerial/sqlite-jdbc/3.49.1.0/sqlite-jdbc-3.49.1.0.jar",
        "file": "players-data.db",
        "args": {
          "journal_mode": "WAL",
          "synchronous": "NORMAL"
        },
        "timeout": 5000,
        "save-interval": 10,
        "max-batch-size": 25
      },
      {
        "name": "JSON",
        "class": "JsonImplementation",
        "compact": false,
        "keep-loaded": false,
        "file": "players-data.json",
        "split": {
          "enabled": false,
          "file": "player-data/{uuid}.json"
        }
      },
      {
        "name": "Memory",
        "class": "MemoryCacheImplementation"
      }
    ],
    "debug": false
  },
  "online-authentication": {
    "enabled": false,
    "allow-offline-players": false,
    "use-service": "PlayerDB",
    "fallback-services": [
      "MojangAPI"
    ],
    "fallback-service-remember-time": 21600,
    "max-timeout": 6000,
    "min-timeout": 1000,
    "check-for-online-unique-id": true,
    "send-messages-to-console": true,
    "send-error-messages-to-console": true,
    "service-connection-throttle": 5000,
    "service-connection-throttled-message": "UUID service connection throttled, wait {time-left} seconds until you can connect again!",
    "service-defaults": {
      "expect-status-code": 200,
      "custom-placeholders": {
        "failed": "Failed to get your online profile",
        "contact": "contact server's administrator!",
        "try-again": "try again later!"
      },
      "default-disconnect-message": "&c{custom.failed}",
      "bad-unique-id-disconnect-message": "&c{custom.failed} (bad unique ID), {custom.contact}",
      "connection-error-disconnect-message": "&c{custom.failed} (connection error), {custom.contact}",
      "bad-status-disconnect-message": "&c{custom.failed} (service returned {http.status}), {custom.contact}",
      "unknown-error-disconnect-message": "&c{custom.failed} (unknown error), {custom.contact}",
      "timeout-disconnect-message": "&c{custom.failed} (service timed out), {custom.try-again}",
      "rate-limited-disconnect-message": "&c{custom.failed} (service rate limited), {custom.try-again}",
      "properties-failed-disconnect-message": "&c{custom.failed} (bad properties), {custom.try-again}",
      "custom-status-code-disconnect-messages": {},
      "timeout": 3000,
      "debug": false,
      "allow-database-caching": true,
      "cache-keep-time": 7200,
      "cache-in-memory": false,
      "use-fallbacks": [
        "ON_CONNECTION_ERROR",
        "ON_INVALID_UUID",
        "ON_BAD_UUID_PATH",
        "ON_UNKNOWN_ERROR",
        "ON_BAD_STATUS",
        "ON_BAD_PROPERTIES",
        "ON_SERVICE_RATE_LIMITED",
        "ON_SUB_SERVICE_RATE_LIMITED",
        "ON_SERVICE_TIMEOUT",
        "ON_SUB_SERVICE_TIMEOUT"
      ],
      "headers": {
        "Accept": "application/json"
      },
      "query-data": {},
      "post-data": {}
    },
    "services": [
      {
        "name": "PlayerDB",
        "endpoint": "https://playerdb.co/api/player/minecraft/{username}",
        "json-path-to-uuid": "data.player.id",
        "json-path-to-properties": "data.player.properties",
        "expect-status-code": null,
        "response-handlers": [
          {
            "event": "POST_REQUEST",
            "allow-player-to-join": true,
            "conditions": {
              "response.code": "minecraft.invalid_username"
            }
          }
        ]
      },
      {
        "name": "MojangAPI",
        "endpoint": "https://api.mojang.com/users/profiles/minecraft/{username}",
        "json-path-to-uuid": "id",
        "expect-status-code": null,
        "request-services-for-properties": ["MojangSessionServer"],
        "require-properties": true,
        "response-handlers": [
          {
            "event": "POST_REQUEST",
            "allow-player-to-join": true,
            "conditions": {
              "::response.errorMessage": true
            }
          }
        ],
        "max-requests-per-minute": 60
      },
      {
        "name": "MojangSessionServer",
        "endpoint": "https://sessionserver.mojang.com/session/minecraft/profile/{response.id}",
        "query-data": {
          "unsigned": false
        },
        "max-requests-per-minute": 60,
        "json-path-to-properties": "properties"
      }
    ]
  },
  "player-randomizer": {
    "enabled": false,
    "use-properties": true,
    "fetch-properties-from-services": true,
    "username": {
      "randomize": true,
      "out-of-usernames-disconnect-message": "&cWe seem to hit the limit of random available usernames!",
      "save": false,
      "expire": -1,
      "from-length": 3,
      "to-length": 16,
      "characters": "qwertyuiopasdfghjklzxcvbnmQWERTYUIOPASDFGHJKLZXCVBNM123456789_"
    },
    "unique-id": {
      "randomize": true,
      "save": false,
      "expire": -1
    }
  },
  "swapped-unique-ids": {
    "enabled": false,
    "swap": {
      "Notch": "00000000-0000-0000-0000-000000000000",
      "00000000-0000-0000-0000-000000000000": "00000000-0000-0000-0000-000000000001"
    }
  },
  "swapped-player-names": {
    "enabled": false,
    "swap": {
      "Notch": "Herobrine",
      "00000000-0000-0000-0000-000000000000": "jeb_"
    }
  },
  "command-messages": {
    "prefix": "&b[UUIDSwapper] &r",
    "no-arguments": [
      "{prefix} Available sub-commands:",
      "&eReload configuration&r",
      "  /{command} reload",
      "&eSet player's new username, properties and UUID on next login. Resets after second re-login!",
      "UUID is optional, if not defined, we will try to fetch the UUID from existing services, offline UUID otherwise.&r",
      "  /{command} pretend <new username> [fetch properties?] [new UUID]",
      "&eTest service. UUID is optional, if empty - offline UUID will be made based on the username.&r",
      "  /{command} test <service> <username> [UUID]"
    ],
    "reload-success": "{prefix}&aPlugin successfully reloaded! (took {took}ms",
    "reload-database-driver-failed": "{prefix}&rFailed to load {driver} driver from configuration! Database will be disabled.",
    "reload-failed": [
      "{prefix}&cFailed to reload configuration, check console for full error!",
      "{prefix}  Error: &4{exception_message}",
      "{prefix} &fOld configuration reverted."
    ],
    "player-pretend-success": [
      "{prefix}Your player data was changed:",
      "{prefix}  New username -> &a{new_username}",
      "{prefix}  New UUID -> &a{new_uuid}",
      "{prefix}Relog in order to log as that player. &cIf you log out from that player, you will get logged back in your original player!"
    ],
    "player-pretend-failed": "{prefix}&cFailed to pretend a player, check console for full error"
  }
}

! Options with prefixed star (*) are required !

Paper Configuration

This only works on paper and velocity!

Option	Description	If undefined
use-mini-messages	Should plugin use Paper's MiniMessages (color codes with & won't work if this is enabled)	false

Database Configuration

Database is used for caching fetched player data.

Option	Description	If undefined
*enabled	Should database be enabled	false
*driver	Which driver to use from drivers array	SQLite
debug	Should debug message to console be enabled (shows when connection was open/close etc.)	false
drivers	Defined drivers implementations (SQLiteImplementation, JsonImplementation, MemoryCacheImplementation)

(Database Driver) SQLite Implementation

SQLite (JDBC) file-based driver to use for caching player data. The driver is not bundled with the plugin but you have the ability to automatically download it and load it.

Option	Description
*name	Name of the driver
*class	(Do not edit unless you are implementing your own driver!!!) Driver class path to load and initiate for later use, if class is defined without a package, it's treated as built-in one
save-interval	Interval in minutes between automatic saves to file or database
max-batch-size	The maximum number of data saved to the database in one go before moving on to the next batch/group
download-driver	Should SQLite driver be downloaded
download-url	Download URL to download driver from
file	File to store SQLite database
timeout	Database timeout in milliseconds
args	SQLite arguments

(Database Driver) JSON Implementation

JSON file-based driver to use for caching player data. JSON example:

{
  "7d65089d-61cc-3566-8b18-be38e4cb73f1": {
    "random": {
      "username": "pFOdjSDK",
      "unique-id": "0946c8b4-79cd-3039-86c3-5a704381cd23",
      "created-at": 1757972403939
    },
    "online": {
      "unique-id": "0946c8b4-79cd-3039-86c3-5a704381cd23",
      "properties": [
        // Properties here
      ],
      "created-at": 1757972403939
    }
  }
}

Sections random and online are dependant on randomizer/online authentication settings. To clear those sections up, execute the main command with modify-data del-section all online (or random). If JSON driver is set to split to separate files, then UUID won't be specified in the JSON itself but rather the file name.

Option	Description
*name	Name of the driver
*class	(Do not edit unless you are implementing your own driver!!!) Driver class path to load and initiate for later use, if class is defined without a package, it's treated as built-in one
*keep-loaded	Should JSON be always loaded
*compact	Should JSON be compacted or pretty
*file	File to store JSON (directories supported)
*split.enabled	Should player data be saved separately for each player
*split.file	File with sub-folder to store separate player data (if no folder is specified, player-data/ will be prefixed)

(Database Driver) Memory Cache Implementation

Memory-based driver to use for caching player data, be aware that data does not persist between restarts!

Option	Description
*name	Name of the driver
*class	(Do not edit unless you are implementing your own driver!!!) Driver class path to load and initiate for later use, if class is defined without a package, it's treated as built-in one

Online Authentication Configuration

Request services to get player's UUID (unique id) or online properties, player can get disconnected if something fails, unless response handlers are specified in the service's configuration.

Option	Description	If undefined
*enabled	Should online authentication be enabled
allow-offline-players	Should offline players be allowed on online/secure server (Velocity/BungeeCord only)	false
*use-service	Which service to use
*fallback-services	Which services to use next (in order) if above one fails (array)
fallback-service-remember-time	For how much time should last used successful service be remembered	21600
max-timeout	Max timeout for all requests summed up (-1 to disable)	6000
min-timeout	Min timeout for a single request (0 to disable)	1000
check-for-online-unique-id	Check if player connects with online UUID (skips service requests). This works by comparing generated offline UUID to player's UUID	true
send-messages-to-console	Send plugin messages to console (e.g., when successfully fetched)	true
send-error-messages-to-console	Send plugin error messages	true
service-connection-throttle	How much time to wait (milliseconds) before requesting already used service	5000
*service-connection-throttled-message	Connection throttled disconnect message	null
*service-defaults	Everything that is defined here will be copied over all services (unless some service override that value)
*services	Service list (array)

Default Service Options

Whatever is defined in this section is also going to be available in service's configuration.

Option	Description	If undefined
request-method	Request method to use (GET or POST)	GET
expect-status-code	Expected status code from service's endpoint	200
default-disconnect-message	Default disconnect message	null
bad-unique-id-disconnect-message	Disconnect message when service failed to get UUID from specified JSON path	null
connection-error-disconnect-message	Unknown connection error disconnect message	null
bad-status-disconnect-message	Unexpected request's returned status code disconnect message	null
unknown-error-disconnect-message	Internal unknown/overlooked error disconnect message	null
timeout-disconnect-message	Service timed-out disconnect message	null
rate-limited-disconnect-message	Service rate limited disconnect message	null
properties-failed-disconnect-message	Failed to get properties disconnect message	null
custom-status-code-disconnect-messages	Custom disconnect messages (key -> value) based on returned service's status code. For example: "500": "Failed to get your online UUID because service returned internal error!"	Empty
max-requests-per-minute	Max request per minute for the service
timeout	Service's time-out time in milliseconds
allow-database-caching	Should service's fetched player data be cached in database (if enabled)	true
require-properties	Should properties be required (disconnect otherwise)	false
custom-placeholders	Custom placeholders (key -> value) to use in disconnect messages and response handlers
debug	Should debug messages to console be enabled	false
use-fallbacks	On which circumstances should next (fallback) service be used	Empty
post-data	Post (key -> value) data for service's request to the endpoint	Empty
query-data	Query (key -> value) data for service's request to the endpoint	Empty
headers	Headers (key -> value) for service's request to the endpoint	Empty

Service Configuration

A service is used for fetching player's data.

Option	Description	If undefined
enabled	Should this service be enabled	true
*name	Name for the service that can be used in use-service or fallback-services
*endpoint	Endpoint to where request should be sent
json-path-to-uuid	JSON path to player's unique ID (support dashless UUIDs too), leave empty if response is suppose to be text only	null
json-path-to-properties	JSON path to player's properties	null
request-services-for-properties	Which services should be used for fetching player's properties, json-path-to-properties is also included if defined	Empty
response-handlers	Custom response handlers	Empty

Response Handler

Handle request's response - allow player to join/disconnect them, set properties required and etc., based on conditions. Response handlers are checked one by one until it finds the matching one, and executes it.

Option	Description	If undefined
*order	In which order should this response handler be executed (ascending)	9999
*event	At what event should this response handler be executed. Available events: PRE_REQUEST - action before request POST_REQUEST - action after request FETCHED_UUID - action when UUID was fetched PRE_PROPERTIES_FETCH - action when properties are about to be fetched (and checked if they should be fetched) FETCHED_PROPERTIES - action when properties were fetched PRE_FALLBACK_USE - action on before any fallback use PLAYER_DATA_FETCHED - last action when player's UUID and/or properties were fetched
allow-player-to-join	Should the player be allowed to join (this is forceful option, meaning if it's true, no matter what, the player will be able to join, if false - instant disconnect, null - allow plugin to decide internally)	null
apply-properties	Should properties be applied for the player	true
require-properties	Should properties be required to be requested and applied (disconnect if no properties or fallback could be used)	null
disconnect-message	Custom disconnect message if allow-player-to-join is set to false	null
message-to-console	Send custom message to console (extra debugging?)	null
console-message-type	Message type to send to console (INFO/WARNING/ERROR)	INFO
conditions-mode	Message type to send to console (AND / OR)	AND
ignore-conditions-case	Should conditions ignore placeholder value casing	false
force-string-on-conditions	When comparing, should placeholder's value and specified value be converted to string for comparison	false
conditions	Conditions (placeholder -> value) to check if response handler should be executed. Note that not everything can be a text (in "" quotes), comparison is done checking if both objects are equal, or if you really want simplicity, enable above setting	Empty

Randomizer Configuration

Randomize player's username and UUID. This will be prioritized if online authentication is enabled (it also depends if fetch-properties-from-services is enabled)!

Option	Description
*enabled	Should randomizer be enabled
*use-properties	Should properties be applied (skin textures)
*fetch-properties-from-services	Should properties first be fetched from services (doesn't matter if online authentication is disabled
*username.randomize	Should plugin randomize player's username
*username.save	Should player's random username be remembered.
*username.expire	When should saved username expire (seconds)
*username.characters	Random characters to pick from
*username.from-length	Minimum length of randomized username
*username.to-length	Maximum length of randomized username
*unique-id.randomize	Should plugin randomize player's unique ID (UUID)
*unique-id.save	Should player's random unique ID be remembered
*unique-id.expire	When should saved unique ID expire (seconds)

Swapped Unique IDs Configuration

Swap player's unique id/username to another unique id.

Option	Description
*enabled	Should player unique id swapping be enabled
*swap	A map (uuid/username -> uuid) for swapped unique ids

Swapped Player Names Configuration

Swap player's UUID/username to a new username.

Option	Description
*enabled	Should player username swapping be enabled
*swap	A map (uuid/username -> username) for swapped unique ids

Command Messages Configuration

Messages for command outputs. Placeholders available in all messages: {command} - command name {prefix} - prefix defined in prefix

Option	Description
*prefix	Command's prefix
*no-arguments	Message when no arguments
*reload-success	Message when reload was successful. Available placeholders: {took} - how many milliseconds took to
*reload-database-driver-failed	Message when database driver failed to load. Available placeholders: {driver} - driver's name that failed to load
*reload-failed	Message when plugin failed to reload. Available placeholders: {error.class} - exception's full (with package) class {error.class-name} - exception's class name {error.message} - exception's message
*player-pretend-success	Message when player successfully pretends to be another player on next server join. Available placeholders: {new_username} - player's new username {new_uuid} - player's new unique ID
*player-pretend-failed	Message when plugin wasn't able to fake another player

This file was auto-generated by an annotation processor.