AikaHub.dev Megnyitom a Studiót

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

É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.

A teljes SDK-leírás (minden függvény, példákkal)

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.

Fejlesztői konzol megnyitása

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.

SzintKi oldhatja felXP / achievementLegendás
clientA játékod kliense (böngésző vagy asztali program)legfeljebb 50nem
serverCsak a játékod szervere, a játékkulccsallegfeljebb 250igen

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ódHTTPJelentés
invalid_token401A hozzáférési token lejárt vagy visszavonták. A böngészős kliens egyszer magától frissít.
invalid_client401Rossz játékkulcs vagy client_id. Újrapróbáljuk, mert épp kulcscsere lehet folyamatban.
invalid_grant400A kód vagy a frissítő token érvénytelen, vagy már felhasználták. Lépj be újra.
insufficient_scope403A tag nem adta meg ezt a hatókört.
wrong_game403Az achievement egy másik játéké.
server_key_required403A szerver szintű achievement csak a játékod szerveréről jöhet.
not_linked409A tag leválasztotta a játékodat. Végleges: dobd el.
unknown_achievement404Nincs (még) ilyen a Hubon. Újrapróbáljuk.
rate429Tú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.

Közzététel: szabályok és korlátok

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á.