Leírás: az AikaHub-készlet
Ez a haladó réteg: részletesen arról, hogyan beszél egy webes játék az AikaHubbal. Ha a Studiót vagy egy kezdő játékot használsz, ez mind kész van helyetted.
Itt kezdd
Az AikaHub-készlet (@aikahub/sdk) egy kicsi, függőség nélküli könyvtár. Böngészőben, Cloudflare Workerben, Node 18+-ban és Denóban fut, és három része van:
browser— Böngészős vagy asztali játék a saját domainjén: nyilvános PKCE-kliens (belépés, profil, karakter, achievementek).server— A játékod szervere: bizalmas kliens játékkulccsal (szerver szintű achievementek, jutalmak, újrapróbáló sor).same-origin— Az aikahub.com-on futó játék: a tag saját munkamenete, plusz vendég-sor.
Jelenlegi változat: @aikahub/sdk 1.5.0
A kiszolgált fájlok (élesben a pontos változatot rögzítsd; az integritás-hash-ek a manifest.json-ban):
/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
Élesben a rögzített verziót töltsd be, és a böngésző ellenőrizze az integritását egy import map-pel (lent). Asztali vagy csomagolt játéknál, vagy ahol az import map integrity mezője nem támogatott, másold a fájlt a saját buildedbe.
Játék regisztrálása
Nyisd meg a Fejlesztői konzolt, fogadd el az AikaHub Fejlesztői Megállapodást, és hozz létre egy fejlesztői klienst: azonnal kapsz egy client_id-t. Amíg fejlesztés alatt van, csak te és legfeljebb 5 tesztelő léphettek be vele. Ha működik, töltsd ki a Játéktér-oldalát, és küldd be: átnézzük, és utána bárki beléphet.
Asztali játék loopback címet is megadhat (http://127.0.0.1/…): a port tetszőleges.
A feltételek nyilvánosak, a regisztráció előtt is elolvashatod őket: Fejlesztői Megállapodás, SDK Licenc, Minden változat
Amit használhatsz
Minden funkció egy hatókör (scope): csak azt kérd, ami kell, a játékos a jóváhagyó oldalon mindet látja.
profile- becenév, avatar, szint, profilszín és profil-link
character- a tag 3D-s VRM-karaktere: fájl-cím, bélyegkép és licenc-jelzők
achievements- a játékod achievementjeinek feloldása és a tag játékbeli jutalmainak olvasása
save- felhőmentés: a játékod tagonként legfeljebb 4 mentést tárol (egyenként ≤ 64 KB), és csak a sajátjait olvassa SDK-leírás
scores- ranglisták: a játékod pontszámot küld a saját ranglistáira (csak a tag legjobb eredménye marad); a lista nyilvános SDK-leírás
visits- látogatás: a játékod a tag házának pillanatképét teszi ki (≤ 16 KB), szomszédokat és házakat olvas, és előre megadott ajándékot küld SDK-leírás
presence- jelenlét: a játékod 45–60 másodpercenként jelzi, hogy a tag most vele játszik (menu / playing / idle — szabad szöveg nincs); a tag profilján a belépett tagok látják, a tag kikapcsolhatja. Csak a játékos saját kliense küldheti, amíg ténylegesen játszik — ha egy szerver (vagy bármi más) a tag háta mögött tartja „online”-ban, az szabályszegés, és a játék elveszítheti a presence hatókört SDK-leírás
Achievementek bizalmi szintjei
A kliens kódját bárki átírhatja, ezért amit a kliens old fel, az legyen olcsó. Az értékes achievementekhez a szervered kell.
| Szint | Ki oldhatja fel | XP / achievement | Legendás |
|---|---|---|---|
client | A játékod kliense (böngésző vagy asztali program) | legfeljebb 50 | nem |
server | Csak a játékod szervere, a játékkulccsal | legfeljebb 250 | igen |
Hibakódok
Az SDK minden hibája AikaHubError, code, status és final mezővel (a true azt jelenti, hogy az újrapróbálás nem segít).
| Kód | HTTP | Jelentés |
|---|---|---|
invalid_token | 401 | A hozzáférési token lejárt vagy visszavonták. A böngészős kliens egyszer magától frissít. |
invalid_client | 401 | Rossz játékkulcs vagy client_id. Újrapróbáljuk, mert épp kulcscsere lehet folyamatban. |
invalid_grant | 400 | A kód vagy a frissítő token érvénytelen, vagy már felhasználták. Lépj be újra. |
insufficient_scope | 403 | A tag nem adta meg ezt a hatókört. |
wrong_game | 403 | Az achievement egy másik játéké. |
server_key_required | 403 | A szerver szintű achievement csak a játékod szerveréről jöhet. |
not_linked | 409 | A tag leválasztotta a játékodat. Végleges: dobd el. |
unknown_achievement | 404 | Nincs (még) ilyen a Hubon. Újrapróbáljuk. |
rate | 429 | Túl sok kérés. Várj (Retry-After), aztán próbáld újra. |
state_mismatch | — | A visszatérés nem egy ebben a fülben indított belépéshez tartozik. Kezdd újra. |
network_error | — | A Hub nem válaszolt. Újrapróbáljuk. |
Újrapróbálási szabályok
A szerveres feloldásokat az újrapróbáló soron át küldd, így egy Hub-kiesés miatt senki nem veszít achievementet.
- done 2xx: kész.
- drop 409 not_linked, 403 és 400: végleges. Dobd el, ne próbáld újra.
- retry 401, 404, 429, 5xx és hálózati hiba: újra, exponenciálisan növekvő várakozással (2 mp-től 6 óráig, véletlen szórással), a Retry-After-t tiszteletben tartva.
A feloldás idempotens: az ismétlés new: false választ ad, XP nélkül, így a legalább egyszeri kézbesítés biztonságos. A sor kulcsa unlock:<sub>:<id>, így ugyanaz a feloldás csak egyszer kerül be.
Adatvédelem
- A sub játékonként más: ugyanannak a tagnak minden játékban más a sub-ja, így a játékok nem tudják ez alapján összevetni az adataikat.
- A Hub soha nem adja ki az e-mail-címet és a belső tag-azonosítót.
- A tag a beállításaiban bármikor leválaszthatja a játékodat. Utána a szervered 409 not_linked választ kap: a saját oldaladon is bontsd a kapcsolatot.
- Soha ne naplózd a tokeneket, a játékkulcsot, az Authorization fejlécet és a sub-ot.
A közzétett játékok szabályai
A közzétett játék a saját címén, szigorú biztonsági szabályokkal fut: nincs beágyazott szkript, nincs más oldalról töltött szkript, és csak önmagához meg az AikaHubhoz csatlakozhat.
Márka-elemek
Tegyél a játékodba „Belépés AikaHubbal” gombot és „AikaHubon” jelvényt.
Szabályok: a gomb legalább 40 px, a jelvény legalább 48 px magas; körülötte legalább a magasság negyedének megfelelő szabad hely; ne színezd át, ne torzítsd, ne írj rá.