Jazz2::Multiplayer::ServerConfiguration struct
#include <Jazz2/Multiplayer/ServerInitialization.h>

Server configuration.

This structure contains the server configuration, which is usually loaded from a file and partially also transferred to connected clients.

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 Address override allows to specify an alternate address
    • The address is used only in the public list to be able to connect to the server from the outside
    • It is also possible to specify a different port if it is different from the local port
  • "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
  • "IsPrivate" : bool Whether the server is private and hidden in the server list
  • "RequiresDiscordAuth" : bool If true, the server requires Discord authentication
    • 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)
  • "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)
  • "ReforgedGameplay" : bool Whether reforged gameplay is enabled
    • Has a higher priority than settings of the player
  • "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 (default is 0)
    • 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
  • "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 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 60 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 Number of treasures required to win (Treasure Hunt)
  • "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
    • "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 Total treasure required to win this round (Treasure Hunt)
  • "PlaylistIndex" : integer Index of the current playlist entry

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.

Example server configuration

{
    /* 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",

    /* "ServerAddressOverride" allows to specify alternative public server address */
    /*"ServerAddressOverride": "123.123.123.123",*/
    
    "WelcomeMessage": "Welcome to the {PlayerName}'s server!",
    "MaxPlayerCount": 16,
    "MinPlayerCount": 1,
    "ServerPort": 7438,
    "IsPrivate": false,
    "RequiresDiscordAuth": false,
    "AllowedPlayerTypes": 7, /* Jazz + Spaz + Lori */
    "IdleKickTimeSecs": 600,
    
    /* 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": "*"
    },
    
    "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"
    },

    "ReforgedGameplay": true,
    "RandomizePlaylist": false,
    "TotalPlayerPoints": 100,
    
    /* 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": 60,

    /* 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": 60
        },
        {
            "LevelName": "battle1",
            "GameMode": "battle",
            "Elimination": false,
            "InitialPlayerHealth": -1,
            "MaxGameTimeSecs": 900,
            "PreGameSecs": 60,
            "SpawnInvulnerableSecs": 4,
            "TotalKills": 10,
            "TotalLaps": 3,
            "TotalTreasureCollected": 60
        }
    ],
    
    "PlaylistIndex": 0
}

Server settings

String ServerName
Server name.
String ServerAddressOverride
Server address override allows to specify an alternate address 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.
bool IsPrivate
Whether the server is private (i.e. not visible in the server list)
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.
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.

Game-specific settings

bool ReforgedGameplay
Whether reforged gameplay is enabled, see PreferencesCache::EnableReforgedGameplay.
bool RandomizePlaylist
Whether to play the playlist in random order.
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 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 60 (Treasure Hunt)
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.
std::uint64_t StartUnixTimestamp
Start time of the server as Unix timestamp.