Doku: das AikaHub-Kit
Das ist die Expertenebene: wie ein Webspiel mit AikaHub spricht, im Detail. Mit dem Studio oder einem Startspiel ist das alles schon für dich erledigt.
Hier anfangen
Das AikaHub-Kit (@aikahub/sdk) ist eine kleine Bibliothek ohne Abhängigkeiten. Es läuft im Browser, in Cloudflare Workers, Node 18+ und Deno und hat drei Teile:
browser— Ein Browser- oder Desktopspiel auf eigener Domain: öffentlicher PKCE-Client (Anmeldung, Profil, Charakter, Achievements).server— Dein Spielserver: vertraulicher Client mit Spielschlüssel (Server-Achievements, Belohnungen, Wiederholungs-Warteschlange).same-origin— Ein Spiel auf aikahub.com: die Sitzung des Mitglieds, plus Gast-Warteschlange.
Aktuelle Version: @aikahub/sdk 1.5.0
Gehostete Dateien (in Produktion die genaue Version festlegen; die Integritäts-Hashes stehen in manifest.json):
/sdk/1.5.0/browser.js/sdk/1.5.0/server.js/sdk/1.5.0/same-origin.js/sdk/1.5.0/aikahub-sdk.js/sdk/1.5.0/manifest.json
Lade im Livebetrieb die feste Version und lass den Browser ihre Integrität per Import-Map prüfen (unten). Bei Desktop- oder gepackten Spielen, oder wo Import-Maps mit integrity nicht unterstützt werden, kopiere die Datei in deinen eigenen Build.
Die vollständige SDK-Referenz (jede Funktion, mit Beispielen)
Spiel registrieren
Öffne die Entwicklerkonsole, nimm die AikaHub-Entwicklervereinbarung an und erstelle einen Entwickler-Client: Du bekommst sofort eine client_id. Solange das Spiel in Entwicklung ist, können sich nur du und bis zu 5 Tester damit anmelden. Wenn es läuft, füll seine Spielplatz-Seite aus und reich sie ein: Wir prüfen sie, danach kann sich jeder anmelden.
Desktopspiele können eine Loopback-URI (http://127.0.0.1/…) registrieren: jeder Port ist erlaubt.
Die Bedingungen sind öffentlich; du kannst sie schon vor der Registrierung lesen: Entwicklervereinbarung, SDK-Lizenz, Alle Fassungen
Was du nutzen kannst
Jede Funktion ist ein Scope: frag nur, was dein Spiel braucht — Spieler sehen jeden auf der Zustimmungsseite.
profile- Nickname, Avatar, Level, Profilfarbe und Profil-Link
character- der 3D-VRM-Charakter des Mitglieds: Datei-URL, Vorschaubild und Lizenzangaben
achievements- Achievements deines Spiels freischalten und die Belohnungen des Mitglieds in deinem Spiel lesen
save- Spielstände in der Cloud: dein Spiel speichert bis zu 4 Spielstände pro Mitglied (je ≤ 64 KB) und liest nur seine eigenen SDK-Referenz
scores- Bestenlisten: dein Spiel sendet Punkte an seine eigenen Bestenlisten (nur das beste Ergebnis jedes Mitglieds bleibt); die Listen sind öffentlich SDK-Referenz
visits- Besuche: dein Spiel zeigt einen Schnappschuss vom Zuhause des Mitglieds (≤ 16 KB), liest Nachbarn und Häuser und sendet vorgegebene Geschenke SDK-Referenz
presence- Anwesenheit: dein Spiel meldet alle 45–60 Sekunden, dass das Mitglied es gerade spielt (menu / playing / idle — kein freier Text); angemeldete Mitglieder sehen es auf dem Profil, das Mitglied kann es ausschalten. Nur vom eigenen Client des Spielers senden, solange er wirklich spielt — Mitglieder von einem Server (oder sonst wie) hinter ihrem Rücken „online“ zu halten, ist ein Regelverstoß und kann den presence-Scope deines Spiels kosten SDK-Referenz
Vertrauensstufen für Achievements
Client-Code kann jeder verändern, darum muss alles, was der Client freischaltet, günstig sein. Wertvolle Achievements brauchen deinen Server.
| Stufe | Wer freischalten darf | XP pro Achievement | Legendär |
|---|---|---|---|
client | Dein Spiel-Client (Browser oder Desktop) | bis zu 50 | nein |
server | Nur dein Spielserver, mit dem Spielschlüssel | bis zu 250 | ja |
Fehlercodes
Jeder SDK-Fehler ist ein AikaHubError mit code, status und final (true heißt: erneutes Versuchen hilft nicht).
| Code | HTTP | Bedeutung |
|---|---|---|
invalid_token | 401 | Das Zugriffstoken ist abgelaufen oder wurde widerrufen. Der Browser-Client erneuert es einmal von selbst. |
invalid_client | 401 | Falscher Spielschlüssel oder falsche client_id. Wird wiederholt, da gerade ein Schlüsselwechsel laufen kann. |
invalid_grant | 400 | Code oder Refresh-Token ist ungültig oder wurde schon benutzt. Melde dich erneut an. |
insufficient_scope | 403 | Das Mitglied hat diesen Scope nicht erlaubt. |
wrong_game | 403 | Das Achievement gehört zu einem anderen Spiel. |
server_key_required | 403 | Ein Server-Achievement muss von deinem Spielserver kommen. |
not_linked | 409 | Das Mitglied hat dein Spiel getrennt. Endgültig: verwerfen. |
unknown_achievement | 404 | Auf dem Hub (noch) nicht definiert. Wird wiederholt. |
rate | 429 | Zu viele Anfragen. Warte (Retry-After) und versuch es dann erneut. |
state_mismatch | — | Die Rückkehr gehört zu keiner in diesem Tab gestarteten Anmeldung. Starte neu. |
network_error | — | Der Hub hat nicht geantwortet. Wird wiederholt. |
Wiederholungsregeln
Schick Server-Freischaltungen über die Wiederholungs-Warteschlange, dann kostet ein Hub-Ausfall niemanden ein Achievement.
- done 2xx: erledigt.
- drop 409 not_linked, 403 und 400: endgültig. Verwerfen, nicht wiederholen.
- retry 401, 404, 429, 5xx und Netzwerkfehler: erneut versuchen, mit exponentiell wachsender Wartezeit (2 s bis 6 h, mit Zufallsanteil) und unter Beachtung von Retry-After.
Freischaltungen sind idempotent: Eine Wiederholung liefert new: false ohne XP, daher ist mindestens einmalige Zustellung sicher. Der Warteschlangen-Schlüssel ist unlock:<sub>:<id>, dieselbe Freischaltung steht also nur einmal darin.
Datenschutz
- Die sub ist paarweise: Dasselbe Mitglied hat in jedem Spiel eine andere sub, Spiele können ihre Daten darüber also nicht abgleichen.
- Der Hub gibt nie E-Mail-Adressen oder interne Nutzer-IDs weiter.
- Mitglieder können dein Spiel jederzeit in ihren Einstellungen trennen. Danach bekommt dein Server 409 not_linked: Trenne die Verknüpfung auch bei dir.
- Protokolliere nie Tokens, den Spielschlüssel, den Authorization-Header oder die sub.
Regeln für veröffentlichte Spiele
Veröffentlichte Spiele laufen unter eigener Adresse mit strengen Sicherheitsregeln: keine Inline-Skripte, keine Skripte von anderen Seiten, Verbindungen nur zum Spiel selbst und zu AikaHub.
Markenelemente
Bau einen „Mit AikaHub anmelden“-Knopf und ein „Auf AikaHub“-Abzeichen in dein Spiel ein.
Regeln: Button mindestens 40 px, Abzeichen mindestens 48 px hoch; rundherum mindestens ein Viertel der Höhe Freiraum; nicht umfärben, verzerren oder beschriften.