Jazz2::Multiplayer::ServerConfiguration struct

#include <Jazz2/Multiplayer/ServerInitialization.h>

File format description

The server configuration is read from a JSON file, which may contain the following fields:

• "$include" : string Include configuration from another file by path
  • If the JSON contains a "$include" directive, it will load the referenced files recursively, but only once to avoid infinite loops
• "ServerName" : string Name of the server
• "ServerAddressOverride" : string or array Address override allows to specify one or more alternate addresses
  • The addresses are used only in the public list to be able to connect to the server from the outside
  • IPv4 address, IPv6 address or domain name can be used
  • It is also possible to specify a different port if it is different from the local port
  • An array lists alternative addresses the same server can be reached at (e.g. IPv4 and IPv6), clients try them in order
  • A domain name needs no such list to cover both protocols — a client resolves it to every address it has and tries all of them
• "ServerPassword" : string Password to join the server
• "WelcomeMessage" : string Message displayed to players upon joining
• "MaxPlayerCount" : integer Maximum number of players allowed to join
• "MinPlayerCount" : integer Minimum number of players required to start a round
• "ServerPort" : integer UDP port number on which the server runs
• "WsPort" : integer WebSocket port number on which server runs
  • If specified, the server will also listen on this port for WebSocket connections, which can be used by web browsers and other clients that don't support UDP
  • WebSocket connections have a higher latency and lower performance than UDP, but can be used for better compatibility
• "WsCertPath" : string Path to TLS certificate for WebSocket server
• "WsKeyPath" : string Path to TLS private key for WebSocket server
  • If specified, the WebSocket server will use secure connections (wss://) and require clients to support TLS
• "IsPrivate" : bool Whether the server is private and hidden in the server list (default is false)
• "AllowAssetStreaming" : bool Whether clients are allowed to download assets from the server (default is true)
• "RequiresDiscordAuth" : bool If true, the server requires Discord authentication (default is false)
  • Discord authentication requires a running Discord client
  • Supported platforms are Linux, macOS and Windows, players from other platforms won't be able to join
• "AllowedPlayerTypes" : integer Bitmask for allowed player types (1 - Jazz, 2 - Spaz, 4 - Lori)
• "IdleKickTimeSecs" : integer Time in seconds after idle players are kicked (default is never)
• "ReconnectWindowSecs" : integer Time window in seconds during which a disconnected player can reconnect and resume their progression (weapons, lives, score, gems), 0 or less to disable (default is 300, i.e. 5 minutes); a player kicked, banned, or kicked for inactivity or cheating always starts over
• "AllowCheats" : bool Whether cheats can be used on the server (default is false)
  • Admins can use cheats in any game mode, other players only in Cooperation
  • Cheats are applied only to the player that invoked them
• "AdminUniquePlayerIDs" : object Map of admin player IDs
  • Key specifies player ID, value contains privileges
• "WhitelistedUniquePlayerIDs" : object Map of whitelisted player IDs
  • Key specifies player ID, value can contain a user-defined comment
  • If at least one entry is specified, only whitelisted players can join the server
• "BannedUniquePlayerIDs" : object Map of banned player IDs
  • Key specifies player ID, value can contain a user-defined comment (e.g., reason)
• "BannedIPAddresses" : object Map of banned IP addresses
  • Key specifies IP address, value can contain a user-defined comment (e.g., reason)
• "WebhookUrl" : string URL of a webhook to which selected server events are automatically posted
  • The payload format targets Discord webhooks (https://discord.com/api/webhooks/…), so server events show up as rich notifications in the linked Discord channel
  • Multiple servers can post to the same channel — every notification carries the server name, so the events can be told apart
• "WebhookEvents" : array List of event names posted to the webhook, see WebhookEventType
  • Supported values are "ServerLifecycle", "PlayerConnected", "PlayerDisconnected", "PlayerKicked", "LevelChanged", "RoundStarted", "RoundEnded", "ChampionshipEnded", "ChatMessages", "PlayerRoasted", "PlayerLapFinished", "FlagCaptured" and "All"
  • If not specified, the default set is used (everything except "RoundStarted", "ChatMessages", "PlayerRoasted", "PlayerLapFinished" and "FlagCaptured")
• "ReforgedGameplay" : bool Whether reforged gameplay is enabled
  • Has a higher priority than settings of the player
• "AllowLedgeClimb" : bool Whether players are allowed to climb ledges (default is the value of "ReforgedGameplay")
  • Players can still disable ledge climbing for themselves, but they can never enable it if the server doesn't allow it
• "RandomizePlaylist" : bool Whether to play the playlist in random order
  • If enabled, the list is shuffled when the server is started and when the end of the list is reached
• "TotalPlayerPoints" : integer Total points to win the championship, 0 to disable (default is 50)
  • Player can score a maximum of 20 points per round
• "GameMode" : string Game mode
  • "b" / "battle" - Battle
  • "tb" / "teambattle" - Team Battle
  • "r" / "race" - Race
  • "tr" / "teamrace" - Team Race
  • "th" / "treasurehunt" - Treasure Hunt
  • "tth" / "teamtreasurehunt" - Team Treasure Hunt
  • "ctf" / "capturetheflag" - Capture The Flag
  • "c" / "coop" / "cooperation" - Cooperation
• "TeamCount" : integer Number of teams in team game modes, clamped to 2-4 (default is 2)
• "AutoBalanceTeams" : bool Whether teams are automatically rebalanced when they become uneven (default is true)
• "MaxTeamSizeDiff" : integer Allowed player-count difference between the largest and smallest team before rebalancing (default is 1)
• "AllowTeamSelection" : bool Whether players may pick/change their own team (default is true)
• "FriendlyFire" : bool Whether players on the same team can damage each other (default is false)
• "AllowMinimap" : bool Whether the minimap is available to players
  • In race modes it shows the track, in other modes the way from the start to the level exit (or the boss) — a level whose exit can't be reached has no minimap there
  • Omit it and the game mode decides: the minimap is on for "Race", "TeamRace" and "Cooperation" and off everywhere else
  • Give it explicitly and that value wins in every mode
  • Players can still hide the minimap for themselves, but they can never show it if the server doesn't allow it
• "ColorizePlayersByTeam" : bool Whether players are recolored to their team color in team modes, forcing the first 2 character color sections (default is true)
• "Elimination" : bool Whether elimination mode is enabled
  • If enabled, a player has a limited number of lives given by "TotalKills" property
  • Game ends when only one player remains, or when the conditions of the specified game mode are met
  • Elimination can be combined with any game mode
• "InitialPlayerHealth" : integer Initial health of players
  • If the property is not specified or is less than 1, the player's health is automatically assigned depending on the game mode
  • Default value for Race and Treasure Hunt is unlimited, in all other game modes it's 5
• "MaxGameTimeSecs" : integer Maximum allowed game time in seconds per level (default is unlimited)
• "PreGameSecs" : integer Pre-game duration in seconds (default is 30 seconds)
  • Pre-game is skipped in Cooperation
• "SpawnInvulnerableSecs" : integer Duration of invulnerability after (re)spawning (default is 4 seconds)
  • Invulnerability is skipped in Cooperation
• "TotalKills" : integer Number of kills required to win (Battle)
• "TotalLaps" : integer Number of laps required to win (Race)
• "TotalTreasureCollected" : integer Amount of treasure required to win (Treasure Hunt)
• "OvertimeSecs" : integer Time the remaining players get to finish after the first one does, in seconds (default is 60 seconds, Race)
  • Set to 0 to end the round as soon as the first player finishes
• "EnableSpectate" : bool Whether spectate mode is enabled (default is true)
• "PlayerStacking" : bool Whether players can stand on top of each other (and jump off); if disabled, they bump apart on every axis as before
  • Omit it and the game mode decides: stacking is on for "Cooperation" and off everywhere else
  • Give it explicitly and that value wins in every mode
• "EnableFreeCamera" : bool Whether free camera is enabled in spectate mode (default is true)
• "AllowJoinDuringRound" : bool Whether players can join in the middle of a round (default is true)
• "JoinCooldownSecs" : integer Cooldown duration in seconds for players who join mid-round (default is 0 seconds)
  • Players cannot move or shoot during this cooldown, but other players can hit them
• "Playlist" : array List of game configurations per round, each entry may contain:
  • "LevelName" : string Name of the level in <episode>/<level> format
  • "GameMode" : string Specific game mode for this round
  • "ReforgedGameplay" : bool Whether reforged gameplay is enabled for this round
  • "AllowLedgeClimb" : bool Whether players are allowed to climb ledges in this round (default is the value of "ReforgedGameplay")
  • "TeamCount" : integer Number of teams in this round (2-4)
  • "AutoBalanceTeams" : bool Whether teams are automatically rebalanced in this round
  • "AllowTeamSelection" : bool Whether players may pick/change their own team in this round
  • "FriendlyFire" : bool Whether players on the same team can damage each other in this round
  • "ColorizePlayersByTeam" : bool Whether players are recolored to their team color in this round
  • "Elimination" : bool Whether elimination mode is enabled for this round
  • "InitialPlayerHealth" : integer Initial health of players for this round
  • "MaxGameTimeSecs" : integer Maximum game duration for this round
  • "PreGameSecs" : integer Pre-game duration before this round starts
  • "SpawnInvulnerableSecs" : integer Duration of invulnerability after (re)spawning
  • "TotalKills" : integer Number of kills required to win this round (Battle)
  • "TotalLaps" : integer Number of laps required to win this round (Race)
  • "TotalTreasureCollected" : integer Amount of treasure required to win this round (Treasure Hunt)
  • "OvertimeSecs" : integer Time the remaining players get to finish this round after the first one does, in seconds (Race)
  • "PlayerStacking" : bool Whether players can stand on top of each other in this round (default is decided by the game mode)
  • "AllowMinimap" : bool Whether the minimap is available to players in this round (default is decided by the game mode)
• "PlaylistIndex" : integer Index of the current playlist entry

In Cooperation, reaching the exit of a story level doesn't end the playlist entry: if the level has a next level set, the server continues with it automatically, taking the players' progression along and keeping the entry's settings. The next playlist entry is applied only when the whole episode is at the end, i.e. when the next level is ":end" or ":credits". An admin can still jump to the next entry sooner with /next or /playlist, or the players with /vote skip.

If a property is missing in a playlist entry, it will inherit the value from the root configuration. If a property is missing in the root configuration, the default value is used. {PlayerName} and {ServerName} variables can be used in "ServerName" and "WelcomeMessage" properties. Both properties also support text formatting using the "\f[…]" notation.

{
    /* The file can contain both multi-line comments */
    // and single-line comments
    
    /* "$include" directive can be used to include configuration from another file */
    "$include": "BaseConfig.json",
    
    "ServerName": "{PlayerName}'s Server",
    
    "ServerPort": 7438,
    "WsPort": 7438,
    "WsCertPath": "cert.pem",
    "WsKeyPath": "key.pem",

    /* "ServerAddressOverride" allows to specify alternative public server address,
       an array can be used if the server is reachable at more than one address;
       a domain name needs no array to cover both IPv4 and IPv6, because a client
       resolves it to every address it has and tries all of them */
    /*"ServerAddressOverride": "123.123.123.123",*/
    /*"ServerAddressOverride": [ "123.123.123.123", "[2001:db8::1]:7438", "example.com" ],*/
    
    "WelcomeMessage": "Welcome to the {PlayerName}'s server!",
    "MaxPlayerCount": 16,
    "MinPlayerCount": 1,
    "IsPrivate": false,
    "RequiresDiscordAuth": false,
    "AllowedPlayerTypes": 7, /* Jazz + Spaz + Lori */
    "IdleKickTimeSecs": 600,
    "ReconnectWindowSecs": 600, /* 0 or less disables reconnect resume */

    /* Only whitelisted players can join if the whitelist is specified */
    /*"WhitelistedUniquePlayerIDs": {
        "8C0D:9387:CDE3:F357:8D8B:8667:3123:1645": "User-defined comment 1"
    },*/
    
    /* Admins can use server commands in the console */
    "AdminUniquePlayerIDs": {
        "370D:9320:3785:3216:9876:8843:323C:1401": "*"
    },

    /* Admins can use cheats in any game mode, other players only in Cooperation */
    "AllowCheats": false,
    
    "BannedUniquePlayerIDs": {
        "8C0D:8887:CDE3:F357:8D8B:8837:3123:1645": "User-defined comment 1",
        "990D:9320:3755:3216:9876:8843:323C:1401": "User-defined comment 2"
    },
    "BannedIPAddresses": {
        "192.168.1.2": "User-defined comment 1",
        "111.222.333.444": "User-defined comment 2"
    },

    /* Server events can be posted to a webhook (mainly Discord), so they show up
       as notifications in the linked channel - every notification carries the server
       name, so multiple servers can be aggregated into a single channel */
    /*"WebhookUrl": "https://discord.com/api/webhooks/000000000000000000/XXXXXXXXXXXXXXXXXXXX",*/
    /* If "WebhookEvents" is not specified, the default set below is used, "RoundStarted",
       "ChatMessages", "PlayerRoasted", "PlayerLapFinished" and "FlagCaptured" can also be enabled */
    /*"WebhookEvents": [ "ServerLifecycle", "PlayerConnected", "PlayerDisconnected",
       "PlayerKicked", "LevelChanged", "RoundEnded", "ChampionshipEnded" ],*/

    "ReforgedGameplay": true,
    /* "AllowLedgeClimb" defaults to the value of "ReforgedGameplay", players can still
       disable ledge climbing for themselves, but they can never enable it if the server
       doesn't allow it */
    "AllowLedgeClimb": true,
    "RandomizePlaylist": false,
    "TotalPlayerPoints": 100,
    "PlayerStacking": true,
    
    /* These properties are redundant, because they are overriden by the playlist */
    "GameMode": "battle",
    "Elimination": false,
    "InitialPlayerHealth": -1,
    "MaxGameTimeSecs": 900,
    "PreGameSecs": 60,
    "SpawnInvulnerableSecs": 4,
    "TotalKills": 10,
    "TotalLaps": 3,
    "TotalTreasureCollected": 0,
    "OvertimeSecs": 0,
    
    /* Spectating */
    "EnableSpectate": true,
    "EnableFreeCamera": true,
    "AllowJoinDuringRound": true,
    "JoinCooldownSecs": 0,

    /* Playlist can contain unlimited number of entries */
    "Playlist":
    [
        {
            "LevelName": "arace1",
            "GameMode": "race",
            "Elimination": false,
            "InitialPlayerHealth": -1,
            "MaxGameTimeSecs": 900,
            "PreGameSecs": 60,
            "SpawnInvulnerableSecs": 4,
            "TotalKills": 10,
            "TotalLaps": 3,
            "TotalTreasureCollected": 0,
            "OvertimeSecs": 60
        },
        {
            "LevelName": "battle1",
            "GameMode": "battle",
            "Elimination": false,
            "InitialPlayerHealth": -1,
            "MaxGameTimeSecs": 900,
            "PreGameSecs": 60,
            "SpawnInvulnerableSecs": 4,
            "TotalKills": 10,
            "TotalLaps": 3,
            "TotalTreasureCollected": 0
        }
    ],
    
    "PlaylistIndex": 0
}

Server settings

String ServerName

Server name.

SmallVector<String, 0> ServerAddressOverrides

Server address overrides allow to specify alternate addresses under which the server will be listed.

String ServerPassword

Password of the server.

String WelcomeMessage

Welcome message displayed to players upon joining.

std::uint32_t MaxPlayerCount

Maximum number of players allowed to join.

std::uint32_t MinPlayerCount

Minimum number of players to start a round.

MpGameMode GameMode

Game mode.

std::uint16_t ServerPort

Server port.

std::uint16_t WsPort

WebSocket server port (0 = disabled).

String WsCertPath

Path to the TLS certificate file for secure WebSocket (WSS), empty = insecure WS.

String WsKeyPath

Path to the TLS private key file for secure WebSocket (WSS).

bool IsPrivate

Whether the server is private (i.e. not visible in the server list).

bool AllowAssetStreaming

Whether clients are allowed to automatically download missing assets from the server.

bool RequiresDiscordAuth

Whether Discord authentication is required to join the server.

std::uint8_t AllowedPlayerTypes

Allowed player types as bitmask of PlayerType.

std::int32_t IdleKickTimeSecs

Time after which inactive players will be kicked, in seconds, -1 to disable.

std::int32_t ReconnectWindowSecs

Time window in seconds during which a disconnected player can reconnect and resume their progression, 0 or less to disable.

bool AllowCheats

Whether cheats can be used, admins in any game mode, other players only in Cooperation.

HashMap<String, String> AdminUniquePlayerIDs

List of unique player IDs with admin rights, value contains list of privileges, or * for all privileges.

HashMap<String, String> WhitelistedUniquePlayerIDs

List of whitelisted unique player IDs, value can contain user-defined comment.

HashMap<String, String> BannedUniquePlayerIDs

List of banned unique player IDs, value can contain user-defined reason.

HashMap<String, String> BannedIPAddresses

List of banned IP addresses, value can contain user-defined reason.

String WebhookUrl

URL of a webhook (mainly Discord) to which selected server events are posted, empty to disable.

WebhookEventType WebhookEvents

Events that are posted to the webhook, see WebhookUrl.

Game-specific settings

bool ReforgedGameplay

Whether reforged gameplay is enabled, see PreferencesCache::EnableReforgedGameplay.

bool AllowLedgeClimb

Whether players are allowed to climb ledges, inherits ReforgedGameplay if not specified.

std::uint8_t TeamCount

Number of teams in team game modes (2-4, ignored in non-team modes).

bool AutoBalanceTeams

Whether teams are automatically rebalanced when they become uneven.

std::uint8_t MaxTeamSizeDiff

Maximum allowed difference in player count between the largest and smallest team before rebalancing.

bool AllowTeamSelection

Whether players are allowed to pick/change their own team.

bool FriendlyFire

Whether players on the same team can damage each other.

bool RandomizePlaylist

Whether to play the playlist in random order.

bool AllowMinimap

Whether the minimap is available to players.

bool AllowMinimapSet

Whether AllowMinimap was given explicitly.

bool ColorizePlayersByTeam

Whether players are recolored to their team color in team modes (forces the primary fur section, ignored in non-team modes).

bool Elimination

Whether every player has limited number of lives, the game ends when only one player remains.

std::uint32_t TotalPlayerPoints

Total player points to win the championship.

std::int32_t InitialPlayerHealth

Initial player health, default is unlimited for Race and Treasure Hunt, otherwise 5.

std::uint32_t MaxGameTimeSecs

Maximum number of seconds for a game.

std::uint32_t PreGameSecs

Duration of pre-game before starting a round.

std::uint32_t SpawnInvulnerableSecs

Duration of invulnerability after (re)spawning.

std::uint32_t TotalKills

Total number of kills, default is 10 (Battle).

std::uint32_t TotalLaps

Total number of laps, default is 3 (Race).

std::uint32_t TotalTreasureCollected

Total number of treasure collected, default is 0 for automatic calculation (Treasure Hunt).

std::uint32_t OvertimeSecs

Duration of overtime in seconds after first player finishes (Race only).

bool EnableSpectate

Whether spectate mode is enabled.

bool PlayerStacking

Whether players can stand on top of each other; if disabled, they bump apart on every axis.

bool PlayerStackingSet

Whether PlayerStacking was given explicitly.

bool EnableFreeCamera

Whether free camera is enabled in spectate mode.

bool AllowJoinDuringRound

Whether players can join in the middle of a round.

std::uint32_t JoinCooldownSecs

Cooldown duration in seconds for players who join mid-round.

std::int32_t PlaylistIndex

Index of the current playlist entry.

SmallVector<PlaylistEntry, 0> Playlist

Playlist.

Pure runtime information

String FilePath

Path to the configuration file.

Uuid UniqueServerID

Server unique identifier.

std::uint64_t StartUnixTimestamp

Start time of the server as Unix timestamp.

bool AdhocMode

Whether the server runs over the console's ad hoc (local wireless) mode instead of Wi-Fi.

Variable documentation