Temel kavramlar

Open Play’de her şey birkaç kavramın etrafında döner: verinin ait olduğu ortam, özellikleri açıp kapatan modüller, iki farklı API anahtarı türü, oyuncunun oturumu ve oyuna özel mantığı taşıyan eklenti. Bu sayfayı bir kez okuyun; diğer sayfalar bu kelimeleri bilindiğini varsayar.

Stüdyo, oyun, ortam

Open Play üç katmanlı bir hiyerarşi kullanır. Panelde Stüdyolar ve oyunlar ekranında (yalnız süper yönetici görür) bu ağacı yönetirsiniz.

Katman	Anlamı	Not
Stüdyo	Oyunlarınızı bir arada tutan kuruluş	Bir sunucuda birden çok stüdyo olabilir
Oyun	Tek bir ürün	Yeni oyun oluşturulunca `dev` ve `prod` ortamları otomatik açılır
Ortam	Oyunun yalıtılmış bir kopyası: `dev`, `prod`, istenirse `staging`	Oyuncular, karakterler, cüzdanlar, anahtarlar ortama aittir

Ortam, veri sınırıdır. Bir ortamdaki oyuncu, karakter, cüzdan ya da anahtar başka bir ortamdan görünmez. Her API çağrısı tek bir ortama karşı çalışır:

API anahtarıyla yapılan çağrılarda ortam anahtardan çıkar; ayrıca bir başlık göndermezsiniz.
Oyuncu oturumuyla yapılan çağrılarda ortamı x-crx-env: <ortam-kimliği> başlığıyla siz bildirirsiniz. Kimlik bir UUID’dir. SDK’lar bunu environmentId ayarından gönderir.

Not

Panel bugün ortam kimliğini (UUID) okunur bir alanda göstermez. Kimliği operatör ekibinizden isteyin ya da panel oturumundaki Oyun ayarları › Modüller sekmesinin yaptığı GET /v1/panel/modules isteğinin yanıtındaki environmentId alanından okuyun. Bu eksiklik kayıtlıdır.

Panel adımları için bkz. Hızlı başlangıç ve Oyun ayarları.

Modüller

Özelliklerin çoğu modüldür: characters, economy, items, trading, store, rewards, social, chat, competition, notifications, webhooks, scenes, plugins (13 modül). Modüller ortam başına açılıp kapatılır; kurulumda sihirbaz bir başlangıç kümesi seçtirir, sonrasında Oyun ayarları › Modüller sekmesi kullanılır (yalnız süper yönetici).

Kapalı modülün uçları çalışmaz: HTTP 404 ve gövde {"code":"module_disabled","message":"…","module":"<ad>"}. Kimliği geçersiz çağıran 401 alır; modülün kapalı olduğunu öğrenemez.
Kapatmak veriyi silmez, yalnız yüzeyi durdurur; yeniden açınca veri yerindedir.
Bazı modüller başkalarına bağlıdır (örneğin trading, economy ve items’a dayanır) ve etkin bir eklentinin ihtiyaç duyduğu modül kapatılamaz.
Çekirdek yüzeyler (oyuncu girişi, içerik grupları, API anahtarları) modül değildir ve kapatılamaz.

Hata ayrıntıları için bkz. Hatalar.

API anahtarları: sunucu ve istemci

API anahtarı, bir ortama bağlı gizli bir dizgedir ve Authorization: Bearer başlığıyla gönderilir. Biçimi:

crx_live_<önek>_<gizli>

Panelde yalnız crx_live_<önek> kısmı (önek) görünür; gizli değer oluşturulduğu anda bir kez gösterilir ve geri alınamaz. Kaybederseniz yeni anahtar oluşturur ya da anahtarı döndürürsünüz (rotate): eski gizli değer geçersiz olur, yenisi bir kez gösterilir.

	Sunucu anahtarı	İstemci anahtarı
Nerede kullanılır?	Oyun sunucunuz, arka uç kodunuz	Oyun istemcisi (tarayıcı, mobil)
Gömülebilir mi?	Hayır, gizli tutulur	Evet
Ne yapabilir?	Tüm işlemler: tanım oluşturma, para verme, eşya basma, webhook kaydı, yönetim	Yalnız izin verilen, hassas olmayan işlemler
Örnek	`add_xp` komutu, para verme, eşya basma	karakteri okuma, `set_flag` komutu

Kesin kural uç noktaya göre değişir ve kodda uç nokta başına sınanır. Hangi ucun hangi anahtar türünü kabul ettiği uç nokta başvurusunda listelenir. Anahtar türü yetersizse çağrı 403 alır.

Panelde anahtar oluşturma: Oyun ayarları › API anahtarları › Yeni API anahtarı (bkz. API anahtarları). Oluştururken ad, tür (Sunucu anahtarı ya da İstemci anahtarı), geçerlilik süresi ve denetim kaydına yazılan bir not (8–500 karakter) girilir.

Uyarı

Gelişmiş ayarlar (kapsam etiketleri, izinler, ek bilgiler) bugün yalnızca kayıt amaçlıdır; anahtarın neye erişebileceğini kısıtlamaz. Erişimi yalnızca anahtar türü belirler. Sunucu anahtarını “kısıtlı” saymayın.

Anahtar ve gizli değer yönetimi için bkz. Güvenlik.

Oyuncu oturumu

Oyuncular API anahtarıyla değil, kendi oturumlarıyla konuşur. Oturum şu yollarla açılır: misafir girişi, e-posta ve parola, Google. Başarılı girişte sunucu bir oturum çerezi (__Secure-crx.session) ve bir yenileme çerezi (__Secure-crx.refresh) yazar; aynı belirteçler yanıt gövdesinde de döner, böylece çerezsiz istemciler (Unity yerel derlemesi, komut satırı araçları) Authorization: Bearer <oturum-belirteci> kullanabilir.

Oyuncu oturumuyla yapılan her istek x-crx-env başlığı taşır. Çerezli (tarayıcı) oturumda durum değiştiren istekler ayrıca CSRF koruması ister (x-csrf-token başlığı). Bu ayrıntıları SDK’lar sizin yerinize yönetir; ham REST’te kendiniz uygularsınız:

Oyuncu oturumu oyun sunucunuza da taşınabilir: oyuncunun kısa ömürlü erişim JWT’si (EdDSA) ortak bir JWKS ile çevrimdışı doğrulanır. Bkz. Sunucuda doğrulama.

Eklenti (plugin)

Eklenti, bir oyuna özel sunucu mantığını (komutlar, sorgular, gerçek zamanlı modüller) taşıyan, sunucuya derlenmiş bir pakettir. Eklenti çağrıları /v1/plugins/{eklenti}/... altında yapılır; durum değiştiren komutlar idempotency anahtarı taşır ve şema isterse expectedVersion ile sürüm denetimi yapar. Eklentinin şeması bir artefakttır (<eklenti>.plugin.schema.json) ve TypeScript/Unity bağlamaları bu şemadan üretilir.

Not

Üçüncü taraf eklenti yükleme (panelden ya da API’den) bugün desteklenmez. Eklentiler Open Play sunucusunun yayınıyla birlikte gelir. Bkz. Eklentilere genel bakış.

Ortak çağrı kuralları

Birçok uçta aynı üç kural geçerlidir; ayrıntıları başvuru sayfalarında bulursunuz:

Idempotency-Key: durum değiştiren komutlarda aynı anahtar ve aynı gövde sonucu yeniden oynatır; aynı anahtarla farklı gövde 422 verir. Bkz. Idempotency ve eşzamanlılık.
If-Match / expectedVersion: kaynağın okuduğunuz sürümünü bildirerek eşzamanlı yazma çakışmasını yakalarsınız (409).
Sayılar: büyük tam sayılar (i64) JavaScript’te bigint olur; eklenti protokolünde ondalık dizge olarak taşınır. Bkz. Sayılar ve kodlama.

Terimlerin kısa tanımı için bkz. Sözlük.

Keyboard shortcuts