Multiplayer

Hosting from the game

Choose Play Multiplayer in the main menu and then one of:

• Create Public Server — the server announces itself, see Public and private servers
• Create Private Server — the server stays hidden and can only be joined by address
• Create Local Splitscreen Game — no networking at all, the additional players use gamepads or a shared keyboard on the same machine

The next screens select the level (or the configured playlist) and the game mode. The host plays as an ordinary player, but its process is the authority for everyone else, which also means it has to be reachable — see Public and private servers for the port to forward. Everything else comes from the very same configuration file the dedicated server reads ("Jazz2.Server.config", see Configuring a server), only the game mode, the level and the public/private choice are taken from the menu instead of from the file.

Running a dedicated server

A dedicated server is the same executable started with the /server argument, optionally followed by the path to its configuration file:

./jazz2 /server Jazz2.Server.config

In this mode the application opens no window and initializes neither graphics nor audio, runs the simulation at a fixed rate of 60 frames per second, and reads console commands from standard input, so it can be run over SSH, from a service manager or in a container. The argument is available on Linux, macOS and — in a debug build only — on Windows; a release server for Windows is the DEDICATED_SERVER build, where the executable is always a server and takes the configuration path as its first argument without /server. See Game-specific parameters for both build parameters.

A dedicated server needs the same game files as a normal installation — the original Jazz Jackrabbit 2 data in the "Source" directory, which it converts into "Cache" on the first start — and it needs a playlist: the level it starts with is taken from the current playlist entry, so a configuration without one is refused with "Server cannot be started because of invalid configuration". The configuration path is relative to the directory of the preferences file (the same directory "Jazz2.config" lives in, which /config can move elsewhere); an absolute path is used as it is, and if the argument is omitted, "Jazz2.Server.config" is loaded from there.

Everything typed on standard input is sent to the server: a line starting with / is a command (see Server commands), anything else is broadcast as a chat message from the server. /exit or /quit stops the server, and so do Ctrl+C and a termination signal (SIGINT and SIGTERM; on Windows the console close events) — all of them shut it down cleanly, disconnecting the peers and delisting the server from the online list before the process exits. A second signal during an already running shutdown terminates the process the usual way.

Running a dedicated server as a container

The dedicated server is also published as a multi-architecture container image, which needs nothing to be built and comes with the DEDICATED_SERVER configuration already applied. See Running the dedicated server as a container for the image, the volumes it expects and the docker-compose.yml that describes the whole setup, including running several instances on a single host.

Configuration file

The server is configured by a single JSON file, by default "Jazz2.Server.config" next to the preferences file. Comments are allowed in it, both the block and the single-line form, and the "$include" directive merges another file into it (recursively, but each file only once, so an include loop is harmless) — which is how several instances can share their common settings and only differ in a few properties. A minimal configuration of a server that rotates two levels looks like this:

{
    "ServerName": "{PlayerName}'s Server",
    "ServerPort": 7438,
    "MaxPlayerCount": 16,
    "MinPlayerCount": 2,

    "Playlist": [
        { "LevelName": "battle1", "GameMode": "battle", "TotalKills": 15 },
        { "LevelName": "arace1", "GameMode": "race", "TotalLaps": 3 }
    ],
    "PlaylistIndex": 0
}

See Jazz2::Multiplayer::ServerConfiguration for the description of every supported property, their default values and a fully annotated example configuration. The properties fall into a few groups:

• Identity and reachability — "ServerName", "ServerPort", "ServerAddressOverride", "IsPrivate" and the WebSocket transport ("WsPort", "WsCertPath", "WsKeyPath")
• Access control — "ServerPassword", "MaxPlayerCount", "AllowedPlayerTypes", "RequiresDiscordAuth" and the player ID lists, see Admins, whitelist and bans
• Rules of a round — "GameMode", "InitialPlayerHealth", "TotalKills", "TotalLaps", "TotalTreasureCollected", "MaxGameTimeSecs", "Elimination", the team properties and the gameplay switches such as "ReforgedGameplay", "AllowLedgeClimb" or "PlayerStacking"
• Session flow — "MinPlayerCount" and "PreGameSecs" decide when a round starts, "TotalPlayerPoints" how long a championship of several rounds lasts, "AllowJoinDuringRound", "JoinCooldownSecs", "ReconnectWindowSecs" and "IdleKickTimeSecs" how players enter and leave it
• Operations — "AllowAssetStreaming" lets clients download levels they don't have from the server, and "WebhookUrl" with "WebhookEvents" post selected server events to a Discord channel

"{PlayerName}" and "{ServerName}" can be used in "ServerName" and "WelcomeMessage", and both properties also support text formatting.

Playlist

"Playlist" is an array of rounds, each of them at least a level name and usually a game mode. Every property a playlist entry doesn't specify is inherited from the root of the configuration, so the root can carry the common rules and an entry only override what makes its round different — see Jazz2::Multiplayer::PlaylistEntry for the properties an entry may contain. The entry that is played first is "PlaylistIndex", and once a round ends, the server advances to the next entry, wrapping around at the end. With "RandomizePlaylist" the list is shuffled when the server starts and again on every wrap.

A Cooperation entry with a story level is played to the end of its episode: when the level has a next level set, reaching the exit continues with it automatically, still with the same entry's settings, and the next entry is applied only once the whole episode is at the end.

The playlist is also the only way for a dedicated server to know which level to load at all (see Running a dedicated server). A server hosted from the menu uses it only when the level selection is left at the playlist, otherwise "PlaylistIndex" is -1 and the chosen level is played until an admin changes it.

Admins, whitelist and bans

Players are identified by a Unique Player ID, which every installation generates for itself. A player finds their own in Options → User Profile (the item copies it to the clipboard), and an admin can look up a connected one with the /ip command. Four properties of the configuration take these IDs:

"ServerPassword" is the simpler alternative to a whitelist — the server is visible to everybody, but only a player who knows the password can enter it. "RequiresDiscordAuth" additionally requires a running Discord client, which limits the server to players on Linux, macOS and Windows. "AllowCheats" is off by default; when it's on, admins may use cheats in any game mode and other players only in Cooperation, and always only on themselves.

Applying changes

The configuration file is read when the server starts. An admin can reload it at runtime with the /refresh command, which re-reads the file and re-applies the welcome message, the game mode and the current playlist entry, so most changes don't require a restart. Individual properties can also be changed temporarily with /set (see Server commands) — those changes live only until the next /refresh or restart, they are never written back to the file.