@gametegra/sdk

@gametegra/sdk

SuperApp JS SDK üzerine inşa edilen bu yardımcı paket, oyun geliştiricileri için özel olarak tasarlanmıştır. Oyun odaklı işlevleri (oda yönetimi, skor, veri akışı) ve SuperApp özelliklerini (kullanıcı bilgisi, ödeme vb.) tek bir çatı altında toplar.

Özellikler

• Tek Noktadan Erişim: Hem oyun metodlarına (createRoom) hem de SuperApp metodlarına (getUserInfo) doğrudan gameTegra objesi üzerinden erişebilirsiniz.
• Otomatik Hazır Olma: superappReady olayını otomatik dinler. Metodları superapp hazır olmadan çağırsanız bile kuyruğa alır ve hazır olduğunda çalıştırır.
• Modüler Yapı: Oyun mantığı, veri akışı ve SuperApp proxy'leri modüler olarak ayrılmıştır.
• Kolay Veri Akışı: sendData ve listenData ile oyun içi gerçek zamanlı veri iletişimini kolaylaştırır.

Kurulum

GitHub Packages üzerinden paket yüklemek için npm kimlik doğrulaması yapmanız gerekir. Git kimlik bilgileriniz (SSH/HTTPS) npm için geçerli değildir.

1. Token Oluşturma

1. GitHub'da Settings > Developer settings > Personal access tokens > Tokens (classic) yolunu izleyin.
2. Generate new token (classic) deyin.
3. read:packages yetkisini seçin ve token'ı oluşturup kopyalayın.

2. Proje Ayarı (.npmrc)

Projenizin kök dizininde .npmrc dosyası oluşturun (veya varsa düzenleyin) ve şu satırları ekleyin. TOKEN_BURAYA kısmına oluşturduğunuz token'ı yapıştırın:

@gametegra:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=TOKEN_BURAYA

Güvenlik Notu: Token'ı doğrudan dosyaya yazmak yerine ortam değişkeni kullanmanız önerilir: //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

3. Yükleme

Artık paketi yükleyebilirsiniz:

npm install @gametegra/sdk

Kullanım

Başlangıç

import { GameTegraSDK, DEFAULT_METHOD_MAP } from "@gametegra/sdk";
import { gameTegra } from "@gametegra/sdk";
// SDK'nın hazır olmasını bekleyin (Opsiyonel ama önerilir)
gameTegra.onReady(async () => {
  console.log("GameTegra ve SuperApp hazır!");

  // Oyun Metodu Çağırma
  await gameTegra.createRoom({ roomId: "lobby-1" });

  // SuperApp Metodu Çağırma (Doğrudan erişim!)
  const userInfo = await gameTegra.getUserInfo();
  console.log("Kullanıcı:", userInfo);
});

Oyun Metodları

Oyun sunucusu (CustomModule) üzerindeki fonksiyonları tetikler.

Metod	Açıklama
createRoom(params)	Yeni bir oyun odası oluşturur.
joinRoom(params)	Mevcut bir odaya katılır.
leaveRoom(params)	Odadan ayrılır.
getScore(params)	Skor bilgisini çeker.
loadData(params)	Nakama'dan veri okur.
saveData(params)	Nakama'ya veri yazar.
showAd(params)	Uygulamada reklam gösterir.
createLeaderboard(params)	Yeni bir leaderboard oluşturur.
getLeaderboard(params)	Leaderboard sıralamasını getirir.
updateLeaderboard(params)	Leaderboard'a skor kaydeder.
custom(name, params)	Özel bir oyun fonksiyonunu ismen çağırır.

// Örnek: Odaya katılma
await gameTegra.joinRoom({ roomId: "12345" });

// Örnek: Leaderboard oluşturma
await gameTegra.createLeaderboard({
  id: "global_wins",
  authoritative: false,
  sortOrder: "desc",
  operator: "best",
  resetSchedule: "0 0 * * 1",
  metadata: { title: "Haftalık Skorlar" },
});

// Örnek: Skor güncelleme
await gameTegra.updateLeaderboard({
  id: "global_wins",
  score: 100,
  subscore: 5,
  metadata: { map: "desert" },
});

// Örnek: Sıralama listesini çekme
const leaderboard = await gameTegra.getLeaderboard({
  id: "global_wins",
  limit: 20,
});

// Ornek: Veri kaydetme
await gameTegra.saveData({
  key: "login",
  value: { id: 1, credential: "test" },
});

// Ornek: Veri okuma (key bos kalirsa koleksiyondaki tum objeleri dondurur)
const data = await gameTegra.loadData({
  collection: "test_data",
  key: "login",
});

// Ornek: Reklam gosterme
const data = await gameTegra.showAd({
  placement: "miniapp_open",
  adType: "rewarded", // or "interstitial"
  miniGameId: miniGameId,
  showLoading: true, // optional, defaults to false
});

SuperApp Metodları

SuperApp özelliklerine window.superapp demeden doğrudan erişebilirsiniz.

Metod	Açıklama
getUserInfo()	Kullanıcı bilgilerini döner.
requestLocation()	Konum bilgisini döner.
capturePhoto()	Kameradan fotoğraf çeker.
pickImage()	Galeriden görsel seçer.
captureScreenshot(options?)	MiniApp/MiniGame WebView'inin o anda görünen ekranını yakalar.
startPurchase(params)	Payment package code ile ödeme işlemini başlatır.
pay(params)	startPurchase için geriye uyumlu alias.
requestOrientation(params)	Ekran yönü isteği gönderir.
searchMiniapps(query)	Mini uygulama arar.
openMiniApp(params)	Başka bir mini uygulamayı açar.
showLoading() / hideLoading()	Yükleniyor ekranını yönetir.

Ekran görüntüsü native host tarafından alınır; bu nedenle DOM, Canvas ve WebGL içeriğini kapsar. Bu özellik capturePhoto() metodundan farklı olarak kamerayı açmaz. Çağrı mevcut CustomMethod hattı üzerinden iletilir; SuperApp JS SDK'ye ayrı bir metot eklenmesi gerekmez. Uyumlu host uygulamasında kullanım:

await gameTegra.waitUntilReady();

const screenshot = await gameTegra.captureScreenshot({
  format: "png",
});

console.log(screenshot.dataUrl, screenshot.width, screenshot.height);

getUserInfo() response data alanı name, email ve age döner. surname alanı yoktur; age seçilmediyse null, child menüsünden seçildiyse o sayısal değer olur.

// Ornek: Odeme
await gameTegra.startPurchase({
  code: "com.gametegra.diamond.100",
  amount: 100,
  currency: "DIAMOND",
});

Veri Akışı (Streaming)

Gerçek zamanlı veri gönderip almak için kullanılır.

// Veri Dinleme
const stream = await gameTegra.listenData({ channel: "game-events" });
stream.on("data", (data) => {
  console.log("Gelen veri:", data);
});

// Veri Gönderme
await gameTegra.sendData({
  channel: "game-events",
  payload: { action: "move", x: 10, y: 20 },
});

Yaşam Döngüsü Olayları

gameTegraReady olayı hem window hem de document üzerinde yayımlanır. Bu sayede SDK'nın tamamen yüklendiğinden ve SuperApp ile bağlantı kurduğundan emin olabilirsiniz.

document.addEventListener("gameTegraReady", (event) => {
  const { gameTegra, superapp } = event.detail;
  console.log("GameTegra hazır", gameTegra);

  // Artık güvenle işlem yapabilirsiniz
  gameTegra.joinRoom({ roomId: "public" });
  superapp.getUserInfo().then(console.log);
});

Event Detay İçeriği:

type ReadyDetail = {
  ready: true;
  superapp: SuperAppInstance;
  gameTegra: GameTegraSDK;
  /** @deprecated Use gameTegra instead */
  supergame: GameTegraSDK;
};

İleri Seviye: Metod Haritalama (setMethodMap)

Eğer SuperApp tarafındaki fonksiyon isimleri ile sizin kodunuzdaki isimler farklıysa veya yeni eklenen bir fonksiyonu SDK güncellemeden kullanmak isterseniz setMethodMap kullanabilirsiniz.

Not: setMethodMap mevcut harita ile yeni gönderdiğinizi birleştirir (merge). Yani varsayılan metodları (createRoom vb.) kaybetmezsiniz, tekrar tanımlamanıza gerek yoktur.

Senaryo: SuperApp tarafında fonksiyonun adı v2_start_tournament_beta ama siz kodunuzda startTournament olarak kullanmak istiyorsunuz.

// Haritalamayı yap (Mevcutlar korunur, bu yenisi eklenir)
gameTegra.setMethodMap({
  startTournament: "v2_start_tournament_beta",
});

// Artık kısa ismiyle çağırabilirsiniz
await gameTegra.custom("startTournament", { id: 1 });

Hazır Olma Garantisi

Tüm metodlar superapp hazır olana kadar bekler. Ancak uygulamanızın başlangıcında her şeyin yüklendiğinden emin olmak isterseniz:

await gameTegra.waitUntilReady();
// Buradan sonra her şey güvenli

Test Oyunları

SDK ile birlikte gelen örnek oyunlar:

• testgame ve testgame/game2: Oda/maç akışını ve veri gönderimini test eden örnekler.
• testgame/gyro: gameTegra.readGyroscope() metodunu dinleyen yeni gyro demo. Çalıştırmak için:
  1. cd testgame/gyro
  2. npm install
  3. Mobilde test edecekseniz npm run dev -- --host

Geriye Uyumluluk

v0.3.0 ile birlikte supergame ismi gameTegra olarak değiştirilmiştir. Eski supergame ismi hala kullanılabilir ancak deprecated olarak işaretlenmiştir:

// Yeni (Önerilen)
import { gameTegra } from "@gametegra/sdk";

// Eski (Deprecated, hala çalışır)
import { supergame } from "@gametegra/sdk";