JKz GameCloud
Tabellen, Records & Leaderboards

1. Überblick

JKz GameCloud stellt spielbezogene Cloud-Tabellen bereit. Für Entwickler fühlt sich eine Tabelle wie eine einfache Datenbanktabelle an, intern werden Records jedoch sicher und mandantengetrennt pro Spiel gespeichert.

Typische Einsätze sind Speicherstände, Inventare, Einstellungen, Level-Fortschritt, Matchdaten, öffentliche Bestenlisten oder serverseitige Konfigurationswerte.

2. Voraussetzungen

• Ein Spiel im DeveloperPortal.
• Ein JKz-Login Client mit aktiviertem gamecloud-Scope, wenn Spielclients zugreifen sollen.
• Mindestens eine GameCloud-Tabelle im Tab GameCloud.
• Eine frisch heruntergeladene GameCloud-SDK.

3. Tabellenmodell

Jede Tabelle gehört genau zu einem Spiel. Der interne Tabellenname wird in der API und SDK verwendet und sollte stabil bleiben. Die erste Tabelle pro Spiel ist kostenlos vorgesehen; weitere Tabellen können später abrechnungsrelevant werden.

• Internal Name: Technischer Name, zum Beispiel player_save.
• Label: Anzeigename im Portal.
• Access Preset: Vordefinierte Zugriffspolitik für typische Fälle.
• Custom Rules: Feiner steuerbare Regeln für Lesen, Schreiben und Löschen.

4. Spalten & Datentypen

Spalten beschreiben, welche Felder ein Record enthalten soll. Die Verwaltung ist bewusst an bekannte Datenbankoberflächen angelehnt.

5. Zugriff & Sicherheit

GameCloud unterscheidet zwischen Spielclient-Zugriffen mit JKz-Login Token und Serverzugriffen mit API-Key. Für Spielclients sollte immer das engste passende Preset genutzt werden.

• Owner Records: Spieler dürfen nur eigene Records lesen/schreiben.
• Public Read: Records sind öffentlich lesbar, aber nicht frei beschreibbar.
• Server Only: Zugriff nur über API-Key aus einem Backend.
• Leaderboard: Spezialisierter Zugriff auf Score-Felder.

Vertraue Spielclients nicht für monetäre Werte, Belohnungen oder kompetitive Ergebnisse. Nutze dafür Server-Only-Tabellen oder später Server-Hosted GameServer-Logik.

6. SDK einbinden

Die GameCloud-SDK wird im DeveloperPortal pro Spiel generiert. Sie enthält Game UUID, API-Basisadresse und Hilfsfunktionen für Tabellenzugriffe.

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

JKzCloud.setTokens(JKzLogin.getTokens());

const info = JKzCloud.diagnose({
    table: "player_save"
});

console.log(info);

7. Records lesen und schreiben

Ein Record wird über Tabellenname und Record-Key adressiert. Der Record-Key ist die stabile technische ID innerhalb der Tabelle.

await JKzCloud.save("player_save", "main", {
    level: 4,
    coins: 120,
    inventory: ["key", "potion"]
});

const save = await JKzCloud.get("player_save", "main");
console.log(save.data);

Nutze feste Keys wie main für einen Hauptspielstand oder eigene Keys wie slot-1, slot-2.

8. Query, Filter & Listen

Tabellen können gelistet und, abhängig von der Tabellenkonfiguration, gefiltert werden. Öffentliche Listen sollten nur Felder enthalten, die Spieler wirklich sehen dürfen.

const records = await JKzCloud.list("player_save", {
    limit: 20
});

const filtered = await JKzCloud.query("player_save", {
    where: {
        level: { gte: 5 }
    },
    limit: 10
});

9. Leaderboards

Eine Tabelle kann als Leaderboard genutzt werden, wenn die Leaderboard-Funktion aktiviert und ein Score-Feld konfiguriert ist.

await JKzCloud.leaderboard.submit("scores", {
    key: "main",
    score: 4200,
    data: {
        character: "mage",
        stage: "forest"
    }
});

const top = await JKzCloud.leaderboard.top("scores", {
    limit: 10
});

const rank = await JKzCloud.leaderboard.rank("scores");

Für kompetitive Leaderboards sollte der Score möglichst durch ein vertrauenswürdiges Backend oder einen Server-Hosted Matchabschluss entstehen.

10. API-Keys für Serverbackends

API-Keys sind für eigene Backends gedacht, nicht für HTML5-Spielclients. Ein API-Key darf nie in ein öffentliches Spielbundle eingebaut werden.

Authorization: Bearer DEIN_GAMECLOUD_API_KEY
Content-Type: application/json

Erstelle API-Keys nur mit den Berechtigungen, die dein Backend benötigt. Rotiere Keys regelmäßig und widerrufe ungenutzte Keys.

11. Limits & Quotas

GameCloud hat bewusst begrenzte kostenlose Limits, damit Missbrauch und versehentliche Massenspeicherung vermieden werden. Später können diese Limits über bezahlbare Upgrades erhöht werden.

• Records und Payloads sollten kompakt bleiben.
• Keine großen Binärdaten in GameCloud speichern.
• Häufige Realtime-Zustände gehören eher in GameServer als in GameCloud.
• Diagnose-Kacheln im Portal zeigen aktuelle Nutzung und Grenzwerte.

12. Diagnose & Fehler

Die SDK enthält Hilfsfunktionen, um häufige Fehler schneller zu verstehen.

try {
    await JKzCloud.save("player_save", "main", { level: 2 });
} catch (error) {
    console.error(JKzCloud.explainError(error));
}

• GameCloud scope missing: Client-Scope aktivieren, SDK neu herunterladen und erneut einloggen.
• Table not found: Internen Tabellennamen prüfen.
• Forbidden: Zugriffspolitik oder API-Key-Berechtigung passt nicht.
• Quota reached: Limit erreicht; Datenmenge reduzieren oder später Upgrade nutzen.