JKz GameServer
Multiplayer, Spectator & Reconnect

1. Überblick

JKz GameServer stellt Multiplayer-Funktionen für Spiele bereit, die über JKz-Login authentifiziert werden. Entwickler erstellen pro Spiel ein GameServer-Projekt im DeveloperPortal und laden anschließend eine passend konfigurierte SDK-Datei herunter.

Der Client darf niemals als alleinige Wahrheit gelten. Bei Server-Hosted Matches validiert der JKz GameServer Inputs autoritativ. Bei P2P- oder Realtime-Modi müssen Spiele weiterhin eigene Plausibilitätsprüfungen und Anti-Cheat-Regeln einplanen.

2. Voraussetzungen

• Ein Spiel im DeveloperPortal.
• Ein JKz-Login Client für dieses Spiel.
• Ein GameServer-Projekt im Tab GameServer.
• Eine frisch heruntergeladene SDK-Datei aus der GameServer-Konfiguration.
• Ein gültiges JKz Access Token des Spielers.

<script src="./mein-spiel-jkz-sdk.js"></script>
<script src="./mein-spiel-gameserver-sdk.js"></script>

3. GameServer-Modi

4. SDK einbinden

Die GameServer-SDK wird im DeveloperPortal pro Projekt generiert. Sie enthält Game UUID, Project ID oder Slug, WebSocket-URL, HTTP-Fallback und nur die Module, die zum gewählten Modus passen.

JKzGameServer.setTokens(JKzLogin.getTokens());

const room = await JKzGameServer.join({
    roomKey: "lobby-1",
    transport: "websocket",
    playerName: "Player",
    state: { x: 120, y: 80 }
});

room.on("*", (type, message) => {
    console.log(type, message);
});

room.start();

5. Räume & Matchmaking

Ein Raum wird beim ersten Join automatisch geöffnet. Räume können gelistet oder privat sein. Gelistete Räume sind im DeveloperPortal sichtbar und können über die SDK geladen werden.

const rooms = await JKzGameServer.listRooms({
    listedOnly: true,
    limit: 20,
    filters: { mode: "ranked" }
});

const room = await JKzGameServer.quickJoin({
    roomPrefix: "match",
    listed: true,
    maxPlayers: 2,
    matchmaking: { mode: "ranked" }
});

6. P2P Assist

P2P Assist ist für Spiele gedacht, bei denen Clients eigene Zustände senden. Der JKz GameServer übernimmt Raumverwaltung, Relay, Presence, Ping/Pong, Reconnect und optional Matchhistorie-Ergebnisse.

room.send("position", {
    x: player.x,
    y: player.y,
    direction: player.direction
}, {
    includeSelf: false
});

room.on("position", message => {
    updateRemotePlayer(message.fromConnectionId, message.payload);
});

7. Server-Hosted

Server-Hosted Projekte akzeptieren nur konfigurierte Inputs. Der Server verarbeitet diese in Reihenfolge, aktualisiert den Matchzustand und verteilt bestätigte Inputs an Spieler und Zuschauer.

const room = await JKzGameServer.join({
    roomKey: "chess-match-1",
    allowSpectators: true,
    maxSpectators: 20,
    maxPlayers: 2
});

room.on("authoritative_input", event => {
    applyAcceptedInput(event.input);
});

room.on("match", match => {
    renderMatchState(match.state);
});

await room.sendInput("move", {
    from: "e2",
    to: "e4"
});

Bei Regeladaptern wie chess prüft der Server den Zug. Illegale Inputs werden abgelehnt und nicht in den Matchzustand übernommen.

8. Spectator

Zuschauer sind nur für Räume möglich, bei denen allowSpectators aktiviert wurde. Zuschauer bekommen Presence, Matchzustand und bestätigte Inputs, dürfen aber keine Gameplay-Inputs senden.

const publicMatches = await JKzGameServer.listSpectatableRooms({
    limit: 20
});

const spectator = await JKzGameServer.spectate({
    roomKey: publicMatches[0].roomKey
});

spectator.on("authoritative_input", event => {
    renderObservedMove(event.input);
});

9. Reconnect

GameServer-Projekte können eine Reconnect-Frist haben. Wenn ein Client kurzzeitig die Verbindung verliert, bleibt seine Session für diesen Zeitraum reserviert. Beim erneuten Join kann die bestehende Verbindung ersetzt werden.

const room = await JKzGameServer.join({
    roomKey: "match-1",
    replaceExisting: true,
    state: getCurrentPlayerState()
});

Für Server-Hosted Matches normalisiert der Server den aktiven Turn-Holder, falls eine alte Connection-ID durch Reconnect nicht mehr gültig ist.

10. Logs & Debugging

Im DeveloperPortal gibt es im GameServer-Tab einen Log-Dialog. Dort können Events, Fehler, Verbindungsabbrüche, Raumöffnungen, Reconnects und Client-Fehler nach Art, Zeitraum und Anzahl gefiltert werden.

• GameServer-Events werden maximal 30 Tage gespeichert.
• Client-Fehler können über die SDK automatisch an den Runtime-Endpoint gemeldet werden.
• Für Server-Hosted Matches werden bestätigte Inputs und Matchzustände in der Matchhistorie gespeichert.

11. Sicherheit & Grenzen

• Access Tokens niemals fest in Spielcode einbauen.
• Spielzustände aus P2P Assist niemals ungeprüft für Ranglisten, Rewards oder Käufe verwenden.
• Server-Hosted Inputs klein halten und auf die benötigten Felder beschränken.
• Spectator nur für Räume aktivieren, die wirklich öffentlich oder beobachtbar sein sollen.
• Für kompetitive Spiele bevorzugt Server-Hosted oder später eigene Dedicated Server verwenden.