Multiplayer

Guide how to run, configure and join multiplayer servers.

Multiplayer comes in two flavors, both optional at build time:

  • Local splitscreen (WITH_MULTIPLAYER) — two to four players on one machine, no networking. Every game mode can be played this way.
  • Online multiplayer (WITH_ONLINE_MULTIPLAYER, plus WITH_WEBSOCKET for the WebSocket transport) — players connect to a server, either the game itself or a headless dedicated server.

Events a level marks as multiplayer-only are present in every multiplayer session, local splitscreen included, and in no single-player game.

Online sessions are server-authoritative: the server runs the whole game (damage, collectibles, scores, rounds) and clients send input, so the level has to be present on the server. The same executable is both game and server unless built with DEDICATED_SERVER. Multiplayer requires threads (NCINE_WITH_THREADS), see Game-specific parameters.

Game modes

The mode is set by "GameMode" or /set mode, using the name or the short form in brackets. Unless a mode says otherwise, the round is won by reaching the target score ("TotalKills"). If the time runs out first ("MaxGameTimeSecs"), the best score wins. In team modes the players are split into 2 to 4 teams and play for a shared team score.

Every player for themselves

  • Battle (battle, b) — Roast other players, each roast is a point. With "Elimination" on, a player who died "TotalKills" times is out, and the last player left wins.
  • Race (race, r) — The first player to finish all the laps ("TotalLaps") wins.
  • Treasure Hunt (treasurehunt, th) — Collect gems, then reach the level exit with enough treasure ("TotalTreasureCollected"). Getting hurt costs some of it, dying at least half.
  • Roast Tag (roasttag, rt) — The first roast wins the ring. From then on, only the ring holder and the player with the fewest points (the bottom feeder) can roast or be roasted. Every roast in a row earns the holder more points, and whoever roasts the holder takes the ring. A holder who roasts nobody for 90 seconds loses it.
  • Last Rabbit Standing (lastrabbitstanding, lrs) — Everyone has a few lives ("PlayerLives"). Lose them all and you're out. The last player left wins, roasts don't score.
  • Extended Last Rabbit Standing (extendedlastrabbitstanding, xlrs) — Like Last Rabbit Standing, but every roast is a point. The last three players left get their points multiplied by 1.5, 1.25 and 1.125, and the most points win.
  • Pestilence (pestilence, pest) — The first player to die becomes a zombie, and so does everyone who dies after. Zombies and humans can only hurt each other, and zombies hit harder. A zombie scores 1 point per roast, a human 1 point per zombie in the game (up to 3). When the last human falls, the round is over. The last human gets 5 bonus points and starts the next round as a zombie.

Teams

  • Team Battle (teambattle, tb) — Battle in teams, the roasts of all team members add up.
  • Team Race (teamrace, tr) — Race in teams. A team wins when all its players have finished.
  • Team Treasure Hunt (teamtreasurehunt, tth) — Treasure Hunt in teams.
  • Capture The Flag (capturetheflag, ctf) — Steal the enemy flag and bring it to your own base.
  • Death Capture The Flag (deathcapturetheflag, dctf) — Capture The Flag where every roast scores too. A capture is worth 1 point plus 1 for every enemy player, then everybody dies and starts over.
  • Flag Run (flagrun, fr) — One flag, which can be picked up at any capture point. Carry it into an enemy base within 45 seconds, or you blow up. A quick delivery scores 3 points, a slower one 2 or 1, plus a bonus for roasts on the way. Roasting a carrier with under 16 seconds left steals the flag.
  • Jailbreak (jailbreak, jb) — Roasted players go to their team's jail. Teammates free them by freezing a spring of the jail. Put the whole enemy team in jail to score a point, then everybody is released.
  • Team Last Rabbit Standing (teamlastrabbitstanding, tlrs) — Each team shares a pool of lives ("TeamLives"). A player who runs out gets more from the team's reserve while there are any. The last team with lives wins.
  • Domination (domination, dom) — Touch a control point for a second to capture it for your team. Every point your team holds scores again every few seconds.
  • Head Hunters (headhunters, head) — A roasted player drops all their gems plus one, which they can't pick up again. Bring at least 2 gems to your own base to score. More gems at once are worth much more: 2 gems score 1 point, 3 score 3, 4 score 5, 5 score 8.

Together

  • Cooperation (cooperation, coop, c) — Play the story levels together, with no scores. Reaching the exit takes everyone to the next level.

Options

These properties change the rules of the modes above. Like all properties, they can be set for the whole server or per playlist entry (see Jazz2::Multiplayer::ServerConfiguration).

PropertyEffect
"OvertimeSecs"When the time runs out without a winner, the round goes on this many seconds, and in most modes the HUD shows the score that wins it. In a race, the time left after the first player finishes. Left out, it's 60 seconds in races and no overtime elsewhere
"PlayerLives"Lives of every player in the Last Rabbit Standing modes, 5 by default
"TeamLives", "MaxTeamPlayersWithLives"Lives of a team and how many of its players can have lives at once, in Team Last Rabbit Standing
"LateJoinersCanPlay"Lets players who join a running round play. Otherwise they're out (Last Rabbit Standing modes) or zombies (Pestilence)
"AmplifyDamage"Every shot does 1 more heart of damage. Some modes turn it on in overtime by themselves
"ResetAllTeams"After a capture in Death Capture The Flag or a point in Jailbreak, all teams start over, not just the losing ones
"AllowPassing"An injured player hands the flag or the gems to a nearby teammate with full health
"FlagPickupCooldownSecs"How long after spawning a player can't pick up a flag, 5 seconds by default
"ExtraDroppedGems", "TransferDroppedGems"How many extra gems a roasted player drops, and whether they go straight to the killer, in Head Hunters
"PunishSelfDeaths", "SelfDeathCostsTeamPoint", "FriendlyFireCostsTeamPoint"How the score changes when you die by your own fault (a pit, spikes) or roast a teammate

Capture points and control points are events the level marks as Easy or Hard only. The jails of Jailbreak are the areas between two Area ID events. A level without them falls back to spawn points or team bases, so any level can be played, just not as well.

Running a server

Hosting from the game

In the main menu choose Play Multiplayer and then:

  • Create Public Server — announced, see Public and private servers
  • Create Private Server — hidden, joinable only by address
  • Create Local Splitscreen Game — no networking, extra players use gamepads or a shared keyboard

Then pick the level (or the configured playlist) and the game mode (see Game modes). The host plays as a normal player but must be reachable (see Public and private servers for the port to forward). All other settings come from "Jazz2.Server.config" (see Configuring a server), the same file a dedicated server reads. A port that is taken already, such as by another server on the same machine, makes creating the server fail.

Running a dedicated server

Start the executable with /server, optionally followed by the configuration path:

./jazz2 /server Jazz2.Server.config
  • No window, graphics or audio. The simulation runs at a fixed 60 FPS and console commands are read from standard input, so it works over SSH, under a service manager or in a container.
  • /server works on Linux, macOS and, in debug builds only, Windows. A release Windows server is the DEDICATED_SERVER build: it is always a server and takes the configuration path as its first argument, without /server. Client arguments are not available in that build. See Game-specific parameters.
  • It needs the same game files as a normal installation: the original Jazz Jackrabbit 2 data in "Source", converted into "Cache" on first start.
  • It needs a playlist — the starting level comes from the current playlist entry. Without one it refuses to start with "Server cannot be started because of invalid configuration".
  • A relative configuration path is resolved against the directory of the preferences file ("Jazz2.config", movable with /config). An absolute path is used as is. Without the argument, "Jazz2.Server.config" is loaded from that directory.

A line on standard input starting with / is a command (see Server commands), anything else is broadcast as chat from the server. /exit, /quit, Ctrl+C, SIGINT/SIGTERM and the Windows console close events shut it down cleanly (peers disconnected, server delisted). A second signal during shutdown kills the process.

Tip: a server whose playlist has a single entry with "GameMode": "race" traces the race minimap track of an original level into the log right after loading (see Jazz2::Multiplayer::GenerateRaceRouteFromGeometry), without needing a client or a running round.

Running a dedicated server as a container

A multi-architecture container image with the DEDICATED_SERVER configuration is published as well. See Running the dedicated server as a container for the image, its volumes and the docker-compose.yml, including running several instances on one host.

Configuring a server

Configuration file

The server is configured by one JSON file, by default "Jazz2.Server.config" next to the preferences file. Block and single-line comments are allowed, and "$include" merges in another file (recursively, each file only once), so several instances can share common settings. A minimal server rotating two levels:

{
    "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
}

Jazz2::Multiplayer::ServerConfiguration documents every property, its default and a fully annotated example. Overview:

GroupProperties
Identity and reachability"ServerName", "ServerPort", "ServerAddressOverride", "IsPrivate", WebSocket: "WsPort", "WsCertPath", "WsKeyPath"
Access control"ServerPassword", "MaxPlayerCount", "AllowedPlayerTypes", "RequiresDiscordAuth", player ID lists (see Admins, whitelist and bans)
Round rules"GameMode", "InitialPlayerHealth", "TotalKills", "TotalLaps", "TotalTreasureCollected", "MaxGameTimeSecs", "Elimination", game mode options (see Options), team properties, gameplay switches such as "ReforgedGameplay", "AllowLedgeClimb", "PlayerStacking"
Session flow"MinPlayerCount" and "PreGameSecs" (when a round starts), "TotalPlayerPoints" (championship length), "AllowJoinDuringRound", "JoinCooldownSecs", "ReconnectWindowSecs", "IdleSpectateTimeSecs", "IdleKickTimeSecs"
Operations"AllowAssetStreaming" (clients download missing levels from the server), "WebhookUrl" and "WebhookEvents" (post selected events to a Discord channel)

"ServerName" and "WelcomeMessage" accept "{PlayerName}" and "{ServerName}", and support text formatting.

Playlist

"Playlist" is an array of rounds, each with a level name and usually a game mode. Properties an entry doesn't set are inherited from the root, so the root holds common rules and entries only override (see Jazz2::Multiplayer::PlaylistEntry).

  • "LevelName" is a level of no episode ("battle1"), a level of an episode ("prince/castle1"), or an episode with a trailing slash ("prince/"), which starts at its first level. A level of an installed level pack is named with a +, e.g. "+1234/battle1", see Level packs.
  • Play starts at "PlaylistIndex" and advances after each round, wrapping around at the end.
  • "RandomizePlaylist" shuffles the list on start and on every wrap.
  • A Cooperation entry with a story level continues through its episode's next levels with the same settings. The next entry applies only once the episode ends.
  • A server hosted from the menu uses the playlist only if the level selection is left at the playlist. Otherwise "PlaylistIndex" is -1 and the chosen level plays until an admin changes it.

Admins, whitelist and bans

Players are identified by a Unique Player ID generated by each installation. Players find their own in Options → User Profile (the item copies it to the clipboard). Admins can look up a connected player with /ip.

PropertyEffect
"AdminUniquePlayerIDs"Players in this map may use admin commands. The value is reserved for a list of privileges, "*" meaning all
"WhitelistedUniquePlayerIDs"If not empty, only these players can join. The value is a comment
"BannedUniquePlayerIDs"These players are rejected. The value is a comment, e.g. the reason
"BannedIPAddresses"The same for addresses, when the player's ID is not known
  • "ServerPassword" is the simpler alternative to a whitelist: the server stays visible, but only players with the password can enter.
  • "RequiresDiscordAuth" requires a running Discord client, limiting the server to Linux, macOS and Windows players.
  • "AllowCheats" is off by default. When on, admins may cheat in any mode and other players only in Cooperation, always only on themselves.

Anti-cheat

Each client simulates its own player and the server checks that the reported movement is possible. The check is lenient because latency, packet loss and frame rate make both sides drift: distance is measured against server time with an allowance for bursts, either side's view of the player may explain a move, and warps the client took slightly earlier are recognized. Only a clear deviation snaps the player back.

Each violation adds to a suspicion score that fades within about a minute. Escalation:

  1. Every violation is logged with details and the current score
  2. A high score notifies the server console and all connected admins
  3. A sustained pattern (high score from several violations over at least ten seconds) kicks the player, only if "AntiCheatKick" is enabled (the default). Admins are never kicked

Players with a slow connection weigh in less. A player kicked for cheating loses retained progression like any other kicked player.

Applying changes

The file is read on start. /refresh re-reads it and re-applies the welcome message, the game mode and the current playlist entry, so most changes need no restart. /set (see Server commands) changes properties only until the next /refresh or restart and never writes to the file.

Public and private servers

Visibility is set by "IsPrivate" (or the menu item the host used):

BehaviorPublic serverPrivate server
Announced on the local networkYes, answers discovery on UDP port 7439No
Published to the online server listYes, to https://de4th.dev/jazz2/serversNo
Shown in Join ServerYes, in both listsNo, enter the address
Requires a reachable addressYesYes, for everyone given the address
Password, whitelist and bansApplyApply

A public server re-publishes itself every 5 minutes and delists on clean shutdown.

  • Behind NAT or in a container the self-detected address is useless — set "ServerAddressOverride" to the address (and port, if different) internet players should use. It takes one address or an array (e.g. IPv4 and IPv6, or a domain name plus an address), tried in order.
  • A domain name needs no separate entries per protocol: clients resolve it to all its addresses (up to four) and try each, so a name with both A and AAAA records works over either.
  • The port must be reachable: "ServerPort" over UDP, and "WsPort" over TCP if WebSocket is enabled.
  • /endpoints lists the known endpoints, including overrides.

Joining a server

Choose Play Multiplayer → Join Server. The list combines local network discovery and the online list, showing name, player count, version and address. "ws" marks WebSocket support, "R" reforged gameplay and "^" a local network server. Joinable servers are listed first, incompatible versions are highlighted. Private servers must be entered by address.

An endpoint is an IPv4 address, a bracketed IPv6 address or a domain name, optionally with a port (default 7438), or a ws:// / wss:// URL for the WebSocket transport:

192.168.1.10          # Local network, default port
example.com:7438      # Domain name and an explicit port
[2001:db8::1]:7438    # IPv6 address
wss://example.com:443 # WebSocket transport (browsers always use this one)

To connect directly on start (for a server browser or a shortcut), pass the endpoint and an optional password:

./jazz2 /connect example.com:7438 secret123

Joining goes through these steps:

  1. Protocol version check — by default the client's version must match the server's exactly, patch included (see NCINE_PROTOCOL_VERSION_MIN and NCINE_PROTOCOL_VERSION_MAX). Converted levels are versioned per build too (see Jazz2::Formats::LevelFile).
  2. Authentication against the whitelist, ban lists and password. A connection not authenticated within 20 seconds is dropped.
  3. Missing assets (levels, tilesets, music) are downloaded if "AllowAssetStreaming" is on. Otherwise the player must install them manually.
  4. An in-game lobby offers character selection and shows the welcome message.

Reconnecting within "ReconnectWindowSecs" after a dropped connection restores weapons, lives, score, gems and championship points. A player removed by the server (kicked, banned, idle or cheating) always starts over.

Server commands

Type commands into the in-game console (the backquote or T key by default) or a dedicated server's standard input. Anything else is chat. Available to every player:

CommandDescription
/infoServer name, current level and mode, player count, load and uptime
/playersConnected players with ping, points, kills, deaths and idle time
/team <team>Requests blue, red, green, yellow or auto, if the current mode allows it
/killKills your own player
/vote <type>Starts a 60-second poll to restart the playlist, skip the level or reset points
/yesVotes in the active poll

Admin commands require an entry in "AdminUniquePlayerIDs" (a dedicated server's console is always an admin):

CommandDescription
/set mode <mode>Changes the game mode and restarts the round. Same values as "GameMode"
/set level <level>Loads another level and leaves the playlist. Same values as "LevelName", so prince/ starts the first level of the episode
/set name <name>Renames the server. An empty name stops publishing to the online list
/set welcome <message>Changes the lobby welcome message, \n starts a new line
/set kills, /set laps, /set treasure <n>Changes the win target of the current round
/set teamcount <2-4>Changes the number of teams, re-splits them and restarts the round
/set autobalance, /set teamselect, /set friendlyfire <on/off>Team rules of the current round
/set cheats <on/off>Allows or forbids cheats
/set anticheatkick <on/off>Allows or forbids anti-cheat kicks, see Anti-cheat
/set spawning <on/off>Stops or resumes player spawning
/nextEnds the round and continues with the next one
/playlist [<index>]Jumps to a playlist entry, or advances to the next one
/skipSkips the remaining pre-game countdown
/balanceRebalances the teams immediately
/setteam <player#> <team>Moves a player to a team
/reset pointsResets everyone's championship points
/alert <message>Shows a message over every player's HUD
/kick <player>Disconnects a player, by name or by # and index
/kill <player>Kills a player without counting a death
/ip <player>Address and Unique Player ID of a player
/endpointsEndpoints the server is reachable at, including "ServerAddressOverride"
/refreshReloads the configuration file, see Applying changes
/packs [list], /packs install <file>, /packs remove <id>Lists, installs or removes level packs, see Level packs. Installing runs in the background, the result is in the log
/vote cancelCancels the active poll
/exit, /quitShuts the dedicated server down (its own console only)

Command-line arguments

ArgumentDescription
/server [<config>]Runs as a dedicated server, see Running a dedicated server. Also --server. Linux, macOS and debug Windows builds only. Not needed in a DEDICATED_SERVER build, whose first argument is the configuration path
/connect <endpoint> [<password>]Connects to a server on start instead of showing the main menu. Also --connect and -c. Not available in a DEDICATED_SERVER build
/config <path>Path to the preferences file. Relative server configuration paths are resolved against its directory
/logAttaches a console to the process (Windows only, where non-server builds have none)
/log:file[:<name>]Writes the trace log to a file in the preferences directory, "Jazz2.log" by default
--install-pack <file>, --remove-pack <id>, --list-packsManages level packs and exits, or goes on with --server, see Installing from the command line

With the default name, the previous session's log is appended to "Jazz2.log.gz" (one gzip member per session, readable as one file, trimmed to the latest 4 MB or 32 sessions). An explicitly named log file gets no archive.