Jazz2::Multiplayer::MpLevelHandler class
#include <Jazz2/Multiplayer/MpLevelHandler.h>

Level handler of a multiplayer game session (online or local splitscreen).

Subclass of LevelHandler that runs a multiplayer match on top of a NetworkManager. It is the authoritative server in two configurations: an online session (NetworkState::Listening), where it spawns and remotes actors to connected clients and processes their packets and commands, and a socket-less local splitscreen session (NetworkState::Local) with only local players and no networking. As a client it applies state updates and forwards local input. It also manages the game mode, round flow, asset validation/streaming and the in-game lobby.

Base classes

class Jazz2::LevelHandler: Level handler of a local game session.
class IServerStatusProvider: Interface to provide current status of the server.
class IGameModeContext: Services a game mode needs from its host level handler.

Public types

struct PlayerScore: Single row of the multiplayer scoreboard.
struct RoundResult: Single row of the final round standings.
enum class LevelState { Unknown, InitialUpdatePending, PreGame, WaitingForMinPlayers, Countdown3, Countdown2, Countdown1, Running, Ending, Ended }: Level state.
enum class AssetType { Unknown, Level, TileSet, Music, Script }: Asset type.

Public static variables

static std::uint32_t SpectateFreeCamera constexpr: Actor ID reported by GetSpectateFollowActorId() when the spectator flies the camera itself.

Public static functions

static auto GetWeaponOwner(Actors::ActorBase* actor) -> Actors::Multiplayer::MpPlayer*: Returns owner of the specified object or the player itself.
static auto GetAssetFullPath(AssetType type, StringView path, StaticArrayView<Uuid::Size, Uuid::Type> remoteServerId = {}, bool forWrite = false) -> String: Returns full path of the specified asset.

Constructors, destructors, conversion operators

MpLevelHandler(IRootController* root, NetworkManager* networkManager, LevelState levelState): Creates a new instance.
~MpLevelHandler() override

Public functions

auto Initialize(const LevelInitialization& levelInit) -> bool override: Initializes the level handler from LevelInitialization.
auto Initialize(Stream& src, std::uint16_t version) -> bool override: Initializes the level handler from resumable state.
auto IsLocalSession() const -> bool override: Returns true if the level handler is on a local session.
auto IsServer() const -> bool override: Returns true if the level handler is on a server or a local session.
auto GetPlayerFurColor(const Actors::Player* player, std::uint32_t furColor) const -> std::uint32_t override: Returns the fur color a player should actually be recolored with.
auto IsPlayerColorForced(const Actors::Player* player) const -> bool override: Returns whether the level handler forces a fur color on the player, overriding local color preferences.
auto IsPausable() const -> bool override: Returns true if the level handler is pausable.
auto CanPlayersCollide() const -> bool override: Returns true if players can collide with each other.
auto CanActivateSugarRush() const -> bool override: Returns true if sugar rush can be activated.
auto CanEventDisappear(EventType eventType) const -> bool override: Returns true if event can be safely despawned.
auto GetHurtInvulnerableTime() const -> float override: Returns default invulnerable time when a player is hurt.
auto GetActiveBossHealth(std::int32_t& health, std::int32_t& maxHealth) const -> bool override: Returns true if a boss health bar should be shown, together with the boss' health.
auto GetDefaultAmbientLight() const -> float override: Returns default ambient light intensity.
void SetAmbientLight(Actors::Player* player, float value) override: Sets current ambient light intensity.
void OnBeginFrame() override: Called at the beginning of each frame.
void OnEndFrame() override: Called at the end of each frame.
void OnInitializeViewport(std::int32_t width, std::int32_t height) override: Called when the viewport needs to be initialized (e.g., when the resolution is changed).
auto OnConsoleCommand(StringView line) -> bool override: Called when a console command is entered.
void OnTouchEvent(const TouchEvent& event) override: Called when a touch event is triggered.
void AddActor(std::shared_ptr<Actors::ActorBase> actor) override: Adds an actor (object) to the level.
auto PlaySfx(Actors::ActorBase* self, StringView identifier, AudioBuffer* buffer, const Vector3f& pos, bool sourceRelative, float gain, float pitch) -> std::shared_ptr<AudioBufferPlayer> override: Plays a sound effect for a given actor (object).
auto PlayCommonSfx(StringView identifier, const Vector3f& pos, float gain = 1.0f, float pitch = 1.0f) -> std::shared_ptr<AudioBufferPlayer> override: Plays a common sound effect.
void WarpCameraToTarget(Actors::ActorBase* actor, bool fast = false) override: Warps a camera to its assigned target.
void BroadcastTriggeredEvent(Actors::ActorBase* initiator, EventType eventType, std::uint8_t* eventParams) override: Broadcasts specified event to all other actors.
void BeginLevelChange(Actors::ActorBase* initiator, ExitType exitType, StringView nextLevel = {}) override: Starts transition to change current level.
void SendPacket(const Actors::ActorBase* self, ArrayView<const std::uint8_t> data) override: Sends a packet to the other side of a non-local session.
void HandleBossActivated(Actors::Bosses::BossBase* boss, Actors::ActorBase* initiator) override: Called when a boss is activated.
void HandleLevelChange(LevelInitialization&& levelInit) override: Called when the level is changed.
void HandleGameOver(Actors::Player* player) override: Called when the game is over.
auto HandlePlayerDied(Actors::Player* player) -> bool override: Called when a player dies.
void HandlePlayerWarped(Actors::Player* player, Vector2f prevPos, WarpFlags flags) override: Called when a player warps.
void HandlePlayerPushed(Actors::Player* player) override: Called after a server-side force/knockback is applied to a player.
void HandlePlayerCoins(Actors::Player* player, std::int32_t prevCount, std::int32_t newCount) override: Called when a player collects or losts coins.
void HandlePlayerGems(Actors::Player* player, std::uint8_t gemType, std::int32_t prevCount, std::int32_t newCount) override: Called when a player collects or losts gems.
void SetCheckpoint(Actors::Player* player, Vector2f pos) override: Sets checkpoint for a given player.
void RollbackToCheckpoint(Actors::Player* player) override: Rolls back to the last checkpoint for a given player.
void HandleActivateSugarRush(Actors::Player* player) override: Called when a player activates sugar rush.
void HandleCreateParticleDebrisOnPerish(const Actors::ActorBase* self, Actors::ParticleDebrisEffect effect, Vector2f speed) override: Called when an object creates a particle debris on perish.
void HandleCreateSpriteDebris(const Actors::ActorBase* self, AnimState state, std::int32_t count) override: Called when an object creates a sprite debris.
void ShowLevelText(StringView text, Actors::ActorBase* initiator = nullptr) override: Shows a text notification.
auto GetLevelText(std::uint32_t textId, std::int32_t index = -1, std::uint32_t delimiter = 0) -> StringView override: Returns a level text.
void OverrideLevelText(std::uint32_t textId, StringView value) override: Override specified level text.
void LimitCameraView(Actors::Player* player, Vector2f playerPos, std::int32_t left, std::int32_t width) override: Limits camera viewport for a given player.
void OverrideCameraView(Actors::Player* player, float x, float y, bool topLeft = false) override: Override camera viewport for a given player.
void ShakeCameraView(Actors::Player* player, float duration) override: Shake camera for a given player.
void ShakeCameraViewNear(Vector2f pos, float duration) override: Shake camera for all players near a given position.
void SetTrigger(std::uint8_t triggerId, bool newState) override: Sets state of a given trigger in the tile map.
void SetWeather(WeatherType type, std::uint8_t intensity) override: Sets current level weather.
auto BeginPlayMusic(StringView path, bool setDefault = false, bool forceReload = false) -> bool override: Plays specified music.
auto PlayerActionPressed(Actors::Player* player, PlayerAction action, bool includeGamepads, bool& isGamepad) -> bool override
auto PlayerActionHit(Actors::Player* player, PlayerAction action, bool includeGamepads, bool& isGamepad) -> bool override
auto PlayerHorizontalMovement(Actors::Player* player) -> float override: Returns value of desired horizontal player movement.
auto PlayerVerticalMovement(Actors::Player* player) -> float override: Returns value of desired vertical player movement.
void PlayerExecuteRumble(Actors::Player* player, StringView rumbleEffect) override: Executes a rumble effect.
auto SerializeResumableToStream(Stream& dest) -> bool override: Serializes object state to a stream.
void OnAdvanceDestructibleTileAnimation(std::int32_t tx, std::int32_t ty, std::int32_t amount) override: Called when a destructible tile animation is advanced.
auto GetLevelDisplayName() const -> StringView override: Returns display name of current level.
auto GetGameMode() const -> MpGameMode: Returns current game mode.
auto GetActiveGameMode() const -> GameModes::IGameMode*: Returns the active game-mode rules object, or nullptr if the mode has not been migrated to IGameMode yet.
auto DrawActiveGameModeHUD(GameModes::IGameModeHUD& hud, Actors::Player* player, const Rectf& view) -> bool: Lets the active game mode draw its part of the HUD into hud; returns false if no migrated mode is active (caller should fall back to its own drawing).
auto GetServerConfiguration() const -> const ServerConfiguration& override: Returns the active server configuration (win targets, elimination, invulnerability, ...).
auto GetPlayers() const -> ArrayView<Actors::Player* const> override: Returns list of players.
auto GetPlayerState(Actors::Player* player) -> MpPlayerState& override: Returns the mutable mode state of the specified player.
auto IsSpectating(Actors::Player* player) const -> bool override: Returns whether the specified player is currently spectating.
auto GetCtfFlagStateCount() const -> std::uint8_t override: Returns the number of Capture The Flag flag states (one per team), or 0 when not in CTF.
auto GetCtfFlagState(std::uint8_t team) const -> std::uint8_t override: Returns the flag state of the specified team in Capture The Flag (0 = home, 1 = taken, 2 = dropped).
auto GetSpawnPoint(Actors::Player* player) -> Vector2f override: Returns a spawn position appropriate for the specified player (its type and assigned team).
auto GetElapsedFrames() const -> float override: Returns number of elapsed frames.
void EndGame(Actors::Player* winner) override: Ends the round with the specified winning player (may be nullptr for a draw).
auto GetTotalLaps() const -> std::uint32_t: Returns the number of laps required to finish a race (Race/TeamRace).
auto GetLevelState() const -> LevelState: Returns the current round state (synced to clients).
auto SetGameMode(MpGameMode value) -> bool: Sets current game mode.
auto SynchronizeGameMode() -> bool: Synchronizes current game mode with all peers without restarting round.
void RequestChangeTeam(std::uint8_t team): Requests to change the local player's team (client) or applies it directly (host).
auto GetScoreboard() const -> const SmallVector<PlayerScore, 0>&: Returns the current scoreboard rows (built on the server and synced to clients).
auto GetRoundResults() const -> const SmallVector<RoundResult, 0>&: Returns the final round standings shown while the round is ending (empty in Cooperation).
auto ProcessCommand(const Peer& peer, StringView line, bool isAdmin) -> bool: Processes the specified server command.
void SendMessage(const Peer& peer, UI::MessageLevel level, StringView message): Sends the message to the specified peer.
void SendMessageToAll(StringView message, bool asChatFromServer = false): Sends the message to all authenticated peers.
void SetPlayerSpectateMode(Actors::Player* player, SpectateMode mode): Enables or disables spectate mode for the specified player (server-side).
void RequestSpectateMode(bool enable): Client-side method to request spectate mode.
auto IsSpectating() -> bool: Returns true if the local player is currently spectating.
auto IsSpectateAvailable() const -> bool: Returns true if spectate mode is enabled by the server.
auto GetSpectateFollowActorId() const -> std::uint32_t: Returns the actor ID of the player the local spectator follows, or SpectateFreeCamera.
auto GetSpectateFollowPlayerName() const -> StringView: Returns the name of the player the local spectator follows, or an empty view when free-flying.
auto GetSpectateFollowPlayerTeam() const -> std::uint8_t: Returns the team of the player the local spectator follows, or 0 when free-flying.
auto GetSpectateFollowPlayerPos(Vector2f& pos) -> bool: Returns the position of the player the local spectator follows.
void CycleSpectateFollow(std::int32_t direction): Moves the local spectator to the next/previous player to follow.
void StopSpectateFollow(): Stops following and hands the camera back to the spectator.
void ShowCharacterSelectLobby(): Shows the in-game lobby so the local player can (re)select a character, (re)joining the game on confirmation.
auto OnPeerDisconnected(const Peer& peer) -> bool: Called when a peer disconnects from the server, see INetworkHandler.
auto OnPacketReceived(const Peer& peer, std::uint8_t channelId, std::uint8_t packetType, ArrayView<const std::uint8_t> data) -> bool: Called when a packet is received, see INetworkHandler.

Protected functions

void AttachComponents(LevelDescriptor&& descriptor) override: Attaches all required level components to the handler.
auto CreateHUD() -> std::unique_ptr<UI::HUD> override: Creates HUD.
void SpawnPlayers(const LevelInitialization& levelInit) override: Spawns all players.
auto CreateResumablePlayer(std::int32_t index) -> std::shared_ptr<Actors::Player> override: Creates a player instance while restoring a resumable state from a stream (one per serialized player).
void PrepareNextLevelInitialization(LevelInitialization& levelInit) override: Prepares LevelInitialization for transition to the next level.
auto CanUseLevelStateSnapshots() const -> bool override: Returns true if actors can be stored in level state snapshots.
auto IsCheatingAllowed(Actors::Player* player) -> bool override: Returns true if cheats are enabled for the specified player, nullptr refers to the local console.
auto IsPlayerAdmin(Actors::Player* player) const -> bool: Returns true if the specified player has admin privileges, nullptr refers to the local console.
void BeforeActorDestroyed(Actors::ActorBase* actor) override: Called before an actor (object) is destroyed.
void ProcessEvents(float timeMult) override: Processes events.
void PauseGame() override: Pauses the game.
void ResumeGame() override: Resumes the paused game.
void ShowConsole() override: Shows the in-game console.
void HideConsole() override: Hides the in-game console.
void HandlePlayerLevelChanging(Actors::Player* player, ExitType exitType): Called when a player entered a transition to change the level.
auto HandlePlayerPush(Actors::Player* player, float pushSpeedX) -> bool: Called when a player pushes a solid object.
auto HandlePlayerSpring(Actors::Player* player, Vector2f pos, Vector2f force, bool keepSpeedX, bool keepSpeedY) -> bool: Called when a player interacts with a spring.
void HandlePlayerBeforeWarp(Actors::Player* player, Vector2f pos, WarpFlags flags): Called when a player is going to warp.
void HandlePlayerSetModifier(Actors::Player* player, Actors::Player::Modifier modifier, const std::shared_ptr<Actors::ActorBase>& decor): Called when a player changed modifier, to sync it to the owning client and its decoration to the other peers.
void HandlePlayerSetFlyCheat(Actors::Player* player, bool active): Called when fly-cheat behavior is enabled or disabled on a player, to sync it to the owning client.
void HandlePlayerFreeze(Actors::Player* player, float timeLeft): Called when a player freezes.
void HandlePlayerSetInvulnerability(Actors::Player* player, float timeLeft, Actors::Player::InvulnerableType type): Called when a player sets invulnerability.
void HandlePlayerSetScore(Actors::Player* player, std::int32_t value): Called when a player sets score.
void HandlePlayerSetHealth(Actors::Player* player, std::int32_t count): Called when a player sets health.
void HandlePlayerSetLives(Actors::Player* player, std::int32_t count): Called when a player sets lives.
void HandlePlayerTakeDamage(Actors::Player* player, std::int32_t amount, float pushForce): Called when a player takes a damage.
void HandlePlayerBumped(Actors::Player* player): Called when a player is bumped by another player to synchronize the resulting knockback.
auto IsPlayerStackingEnabled() const -> bool: Returns true if players can stand on top of each other (per-level ServerConfiguration::PlayerStacking).
auto IsMinimapAllowed() const -> bool: Returns true if the minimap is available to players (per-level ServerConfiguration::AllowMinimap).
auto IsLedgeClimbAllowed() const -> bool: Returns true if players are allowed to climb ledges (per-level ServerConfiguration::AllowLedgeClimb).
auto FindPlayerToStandOn(Actors::Player* player, float timeMult) -> Actors::ActorBase* override: Returns the player actor the given player is standing/landing on (one-way platform check), or nullptr.
void HandlePlayerRefreshAmmo(Actors::Player* player, WeaponType weaponType): Called when a player requests to synchronize weapon ammo.
void HandlePlayerRefreshWeaponUpgrades(Actors::Player* player, WeaponType weaponType): Called when a player requests to synchronize weapon upgrades.
void HandlePlayerMorphTo(Actors::Player* player, PlayerType type): Called when a player requests to morph to another type.
void HandlePlayerSetDizzy(Actors::Player* player, float timeLeft): Called when a player changed duration of dizziness.
void HandlePlayerSetBeingStoodOn(Actors::Player* player, bool beingStoodOn): Called when another player starts/stops standing on a player, to sync its cosmetic lift animation.
void HandlePlayerSetShield(Actors::Player* player, ShieldType shieldType, float timeLeft): Called when a player sets a shield.
void HandlePlayerSetSugarRush(Actors::Player* player, float timeLeft): Called when sugar rush starts or ends on a player, to sync it to the owning client and the other peers.
void HandlePlayerSetAmbientLight(Actors::Player* player, float value, bool applyNow, bool asCheckpoint): Sends an ambient light intensity to the client owning player.
void SyncPlayerInventoryToPeer(Actors::Player* player): Pushes the complete weapon inventory of a player to the owning client.
void HandlePlayerEmitWeaponFlare(Actors::Player* player): Called when a player emits a weapon flare.
void HandlePlayerWeaponChanged(Actors::Player* player, Actors::Player::SetCurrentWeaponReason reason): Called when a player changes their current weapon.

Private functions

auto GetTeamCount() const -> std::uint8_t override: Returns the number of teams (team-based modes only).
auto GetTeamScore(std::uint8_t team) -> std::uint32_t override: Returns the aggregate round score of the specified team (team-based modes only).
void EndGameWithTeam(std::uint8_t team) override: Ends the round with the specified winning team.

Enum documentation

enum class Jazz2::Multiplayer::MpLevelHandler::LevelState

Level state.

Enumerators
Unknown	Unknown
InitialUpdatePending	Level was just created and initial update needs to be sent
PreGame	Pre-game is active
WaitingForMinPlayers	Pre-game ended, but not enough players connected yet
Countdown3	Countdown started (3)
Countdown2	Countdown continues (2)
Countdown1	Countdown continues (1)
Running	Round started
Ending	Round is ending
Ended	Round ended

enum class Jazz2::Multiplayer::MpLevelHandler::AssetType

Asset type.

Enumerators
Unknown	Unknown
Level	Level
TileSet	Tile set
Music	Music
Script	Script

Function documentation

Jazz2::Multiplayer::MpLevelHandler::MpLevelHandler(IRootController* root, NetworkManager* networkManager, LevelState levelState)

Creates a new instance.

Parameters
root	Root controller
networkManager	Network manager that handles the connection
levelState	Initial level state

std::uint32_t Jazz2::Multiplayer::MpLevelHandler::GetPlayerFurColor(const Actors::Player* player, std::uint32_t furColor) const override

Returns the fur color a player should actually be recolored with.

Lets the level handler override a player's configured color; multiplayer team modes use this to force the team color. The default returns furColor unchanged.

bool Jazz2::Multiplayer::MpLevelHandler::IsPlayerColorForced(const Actors::Player* player) const override

Returns whether the level handler forces a fur color on the player, overriding local color preferences.

Multiplayer team modes force the team color on every player so teams stay distinguishable; such a forced color applies regardless of the cosmetic "Apply Colors" preference. The default returns false.

bool Jazz2::Multiplayer::MpLevelHandler::GetActiveBossHealth(std::int32_t& health, std::int32_t& maxHealth) const override

Returns true if a boss health bar should be shown, together with the boss' health.

Online clients never own the boss actor (boss activation is server-side only), so multiplayer reports the health synchronized from the server instead of reading the local boss actor.

void Jazz2::Multiplayer::MpLevelHandler::HandlePlayerPushed(Actors::Player* player) override

Called after a server-side force/knockback is applied to a player.

Allows the change to be synchronized to the owning client in a non-local session (no-op in local/single-player sessions).

bool Jazz2::Multiplayer::MpLevelHandler::PlayerActionPressed(Actors::Player* player, PlayerAction action, bool includeGamepads, bool& isGamepad) override

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Jazz2::Multiplayer::MpLevelHandler::PlayerActionHit(Actors::Player* player, PlayerAction action, bool includeGamepads, bool& isGamepad) override

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Jazz2::Multiplayer::MpLevelHandler::GetSpectateFollowPlayerPos(Vector2f& pos)

Returns the position of the player the local spectator follows.

If that player is gone - disconnected, finished the race or turned spectator itself - the camera moves on to the next player instead of being left behind where they were, and only returns false (handing the camera back to the spectator) when nobody is left to watch.

void Jazz2::Multiplayer::MpLevelHandler::CycleSpectateFollow(std::int32_t direction)

Moves the local spectator to the next/previous player to follow.

Parameters
direction	`1` for the next player, `-1` for the previous one

The free camera is one step of the cycle (right after the last player), so a single button can start following, step through everyone and drop back to flying the camera by hand.

bool Jazz2::Multiplayer::MpLevelHandler::CanUseLevelStateSnapshots() const override protected

Returns true if actors can be stored in level state snapshots.

Snapshots make it possible to roll back all actors to the last checkpoint, to resume them from a saved state and to return from a special level to the exact state the previous level was left in.

bool Jazz2::Multiplayer::MpLevelHandler::IsMinimapAllowed() const protected

Returns true if the minimap is available to players (per-level ServerConfiguration::AllowMinimap).

Meaningful only on the server, a client learns the outcome from whether the track is synchronized to it.

void Jazz2::Multiplayer::MpLevelHandler::HandlePlayerSetAmbientLight(Actors::Player* player, float value, bool applyNow, bool asCheckpoint) protected

Sends an ambient light intensity to the client owning player.

Parameters
player
value
applyNow	Apply the value to the player's view right away
asCheckpoint	Remember the value as the one to restore when respawning at the checkpoint

Does nothing for a player that isn't owned by a remote peer.

void Jazz2::Multiplayer::MpLevelHandler::SyncPlayerInventoryToPeer(Actors::Player* player) protected

Pushes the complete weapon inventory of a player to the owning client.

Ammo and upgrades are otherwise only sent when they change, so a client that just (re)spawned with restored progression has no way to verify it holds the same values as the server. Called after such a spawn.