AikaHub.dev Studio öffnen

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):

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.

Entwicklerkonsole öffnen

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.

StufeWer freischalten darfXP pro AchievementLegendär
clientDein Spiel-Client (Browser oder Desktop)bis zu 50nein
serverNur dein Spielserver, mit dem Spielschlüsselbis zu 250ja

Fehlercodes

Jeder SDK-Fehler ist ein AikaHubError mit code, status und final (true heißt: erneutes Versuchen hilft nicht).

CodeHTTPBedeutung
invalid_token401Das Zugriffstoken ist abgelaufen oder wurde widerrufen. Der Browser-Client erneuert es einmal von selbst.
invalid_client401Falscher Spielschlüssel oder falsche client_id. Wird wiederholt, da gerade ein Schlüsselwechsel laufen kann.
invalid_grant400Code oder Refresh-Token ist ungültig oder wurde schon benutzt. Melde dich erneut an.
insufficient_scope403Das Mitglied hat diesen Scope nicht erlaubt.
wrong_game403Das Achievement gehört zu einem anderen Spiel.
server_key_required403Ein Server-Achievement muss von deinem Spielserver kommen.
not_linked409Das Mitglied hat dein Spiel getrennt. Endgültig: verwerfen.
unknown_achievement404Auf dem Hub (noch) nicht definiert. Wird wiederholt.
rate429Zu 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.

Veröffentlichen: Regeln und Grenzen

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.