SCRIPTING API / Multiplayer / GameSession

GameSession

The dedicated server's game session: players (clients and bots), ready states, map travel, the match state and the session rules. Server-only: on a client the queries return defaults and the changes throw (use RequestReady and the Kroys.Session.* messages there).

Kindclass

NamespaceKroys.EngineScripting

Members21

SourceGameSession.cs

EXAMPLE

In a script

A complete script that uses GameSession; copy it into your scripts project.

Multiplayer.cs

public sealed class MapRotation : GameMode
{
    private static readonly string[] Maps = ["Scenes/Docks.kscene", "Scenes/Yard.kscene"];
    private float secondsLeft;

    protected override void OnStart() => secondsLeft = GameSession.GetSetting("round_seconds", 600.0f);

    protected override void OnFixedUpdate(float fixedDeltaTime)
    {
        secondsLeft -= fixedDeltaTime;
        if (secondsLeft > 0.0f) return;
        // Travel loads the next map before the next frame; players move to its spawn points.
        int next = (Array.IndexOf(Maps, GameSession.Map) + 1) % Maps.Length;
        GameSession.Travel(Maps[next]);
        secondsLeft = GameSession.GetSetting("round_seconds", 600.0f);
    }

    protected override void OnTravelled(string map) => Debug.Log($"now playing {map} with {GameSession.PlayerCount} players");
}

REFERENCE

Members

Properties

#public static bool IsAuthority { get; }

True on the dedicated server, the authority over the game state.

propertystatic

#public static IReadOnlyList<Player> Players { get; }

Players in the session (clients and bots), in join order.

propertystatic

#public static int PlayerCount { get; }

Number of players in the session.

propertystatic

#public static bool AllPlayersReady { get; }

Whether every human player is ready (false without human players). Bots count as ready.

propertystatic

#public static string Map { get; }

The loaded map: the scene path relative to the server's content folder.

propertystatic

#public static string MatchState { get; set; }

The match state the game mode sets (for example "Warmup", "Playing", "Ended"; empty at start). Setting it sends MatchStateMessage to every client and raises SessionEventType.MatchStateChanged.

propertystatic

Constants

#public const string ReadyMessage = "Kroys.Session.Ready"

Script message a client sends to change its ready state (one byte: 1 ready, 0 not).

constantstatic

#public const string TravelMessage = "Kroys.Session.Travel"

Script message clients receive when the server travelled (payload: the map as a string).

constantstatic

#public const string MatchStateMessage = "Kroys.Session.MatchState"

Script message clients receive when the match state changed (payload: the state as a string).

constantstatic

Methods

#public static void RequireAuthority(string operation = "This operation")

Throws when not running on the dedicated server. Call it first in server-only code paths.

operation: What was attempted, for the error message.

methodstatic

#public static string GetSetting(string key)

A session rule (GameRules.kserverrules or --rule key=value); empty when unset.

methodstatic

#public static int GetSetting(string key, int fallback)

A numeric session rule, or fallback when unset or not a number.

methodstatic

#public static float GetSetting(string key, float fallback)

A numeric session rule, or fallback when unset or not a number.

methodstatic

#public static bool SetReady(Player player, bool ready)

Sets a player's ready state (raises SessionEventType.PlayerReadyChanged when it changes).

methodstatic

#public static bool Kick(Player player, string reason = "Kicked")

Disconnects a client (it receives the reason) or removes a bot.

methodstatic

#public static bool Travel(string scenePath)

Changes the map before the next server frame: the scene (relative to the content folder) loads, players move to its spawn points, clients receive TravelMessage and the game mode gets SessionEventType.Travelled. False when the scene does not exist.

methodstatic

#public static Player AddBot(string name = "")

Adds a server bot: a character the server simulates with the same movement step as client players, which replicates to every client. Drive it with Bot.SetInput. Raises SessionEventType.PlayerJoined.

methodstatic

#public static bool RemoveBot(Player bot)

Removes a bot. Raises SessionEventType.PlayerLeft.

methodstatic

#public static bool RequestReady(bool ready = true)

Client side: tells the server this player is (not) ready. The server's game mode gets SessionEventType.PlayerReadyChanged.

methodstatic

#public static bool TryReadTravel(NetworkMessage message, out string map)

Client side: reads the map from a TravelMessage.

methodstatic

#public static bool TryReadMatchState(NetworkMessage message, out string state)

Client side: reads the state from a MatchStateMessage.

methodstatic

Signatures

public const string ReadyMessage = "Kroys.Session.Ready"
public const string TravelMessage = "Kroys.Session.Travel"
public const string MatchStateMessage = "Kroys.Session.MatchState"
public static bool IsAuthority { get; }
public static void RequireAuthority(string operation = "This operation")
public static IReadOnlyList<Player> Players { get; }
public static int PlayerCount { get; }
public static bool AllPlayersReady { get; }
public static string Map { get; }
public static string MatchState { get; set; }
public static string GetSetting(string key)
public static int GetSetting(string key, int fallback)
public static float GetSetting(string key, float fallback)
public static bool SetReady(Player player, bool ready)
public static bool Kick(Player player, string reason = "Kicked")
public static bool Travel(string scenePath)
public static Player AddBot(string name = "")
public static bool RemoveBot(Player bot)
public static bool RequestReady(bool ready = true)
public static bool TryReadTravel(NetworkMessage message, out string map)
public static bool TryReadMatchState(NetworkMessage message, out string state)

KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.