Sayılar ve kodlama

Bu sayfa, Open Play’in sayıları, parayı, zamanı ve kimlikleri JSON üzerinde nasıl taşıdığını anlatır. En sık yapılan hata, 64 bit tam sayıları JavaScript number’ına çevirip hassasiyet kaybetmektir; bu sayfayı o hatadan kaçınmak için okuyun.

Kısa kurallar

64 bit tam sayılar

JavaScript’in JSON.parse işlevi sayıları double’a çevirir; 2^53 − 1 (9 007 199 254 740 991) üstü tam sayılar sessizce bozulur. Open Play bu yüzden iki profil kullanır:

• Çekirdek REST int64 alanları JSON sayısı olarak gönderir (version, balance, amount). Değerler pratikte güvenli aralıkta kalır, ama garanti bigint ile okuyan bir ayrıştırıcıdır. TypeScript SDK’sı lossless-json ile okur ve bigint döner.
• Eklenti ve realtime (plugin-v1-decimal-int64 kodlama profili) int64 alanları ondalık metin olarak gönderir ve bekler: {"expectedVersion":"3"}, {"sessionEpoch":"7"}. Böylece her istemci dili kayıpsız taşır.

Kurallı ondalık metin

Eklentilerde işaretli int64 kurallı biçimde yazılmalıdır; sunucu başka biçimi reddeder (400 invalid_argument):

Realtime çerçevelerindeki sayaçlar (sessionEpoch, inputSeq, revision, sequence, expectedVersion, streamEpoch, barrierSequence) aynı metin biçimindedir ve negatif olamaz. protocolVersion, schemaVersion ve diğer küçük sayaçlar JSON sayısıdır.

Eklenti şema belgesinde int64 alanın sınırları da metin olarak yazılır ("minimum": "0", "maximum": "9223372036854775807"); bu normaldir.

İstemci dillerinde

TypeScript’te JSON’u kendiniz ayrıştırıyorsanız lossless-json gibi bir kütüphane kullanın; aksi halde büyük değerler bozulur.

Para ve ölçekli değerler

• Para değerleri küçük birimli tam sayıdır (ör. kuruş): 250 kaç ana birim ettiği, oyununuzun gösterim kararına bağlıdır (panelde para biriminin “kuruş hanesi” ayarı gösterimi belirler); API yalnız tam sayıyı taşır. Bakiye ve tutar alanları amount, balance, eklentilerde ...Minor adıyla gelir.
• Kayan nokta (float/double) hiçbir yerde kullanılmaz: ne istek, ne yanıt, ne de hesaplama. Kendi tarafınızda da para için float kullanmayın; tam sayıyla çalışıp yalnız gösterimde ondalığa çevirin.
• İçerik gruplarındaki ölçekli değerler tamsayı + ölçek çiftidir: 4350 ve ölçek 2 → 43.50. TypeScript SDK’sında formatScaled(değer: bigint, ölçek) bunu kayıpsız biçimlendirir (0 ile 18 hane). Kendi float bölmenizi yapmayın.

Yüzdeler: baz puan

Yüzde ve oran alanları baz puan (basis point) tam sayısıdır: 10000 = %100, 2500 = %25, 1 = %0,01. Örnek: grup ödül payı share_bp 0 ile 10000 arasında olmalıdır; dışı 400 alır.

Zaman

Sunucu saatlerini UTC olarak yorumlayın. İstemci saati sunucu kararında kullanılmaz: zaman ve rastgelelik sunucuda üretilir ve olaya yazılır.

Kimlikler ve anahtarlar

• UUID: küçük harfli, tireli metin (0192a3b4-0000-7000-8000-000000000001). Çoğu kaynak kimliği zamana göre sıralanan UUID v7’dir; sıralama için kullanabilirsiniz, ama biçimden anlam çıkarmayın.
• key alanları (tanım anahtarları, skor tablosu, görev): oyun geliştiricinin verdiği okunabilir kimlikler; oluşturduktan sonra aynen kullanın, büyük/küçük harf ya da boşluk değiştirmeyin.
• Eklenti kimlikleri: küçük harf ve tire (package-ride). Mesaj türleri: nokta ile ayrılmış, eklenti önekli (package-ride.delivery-trip.active.input).
• İmleçler: opak metin; içeriğini ayrıştırmayın (sayfalama).
• API anahtarları: crx_live_<önek>_<gizli>; önek yalnız tanımlama içindir, gizli kısım yalnız bir kez gösterilir (güvenlik).

Numaralandırma (enum) değerleri

Tüm numaralandırma değerleri sunucuda tek bir tanımdan gelir ve bilinmeyen değer reddedilir (sessizce yok sayılmaz):

• Çekirdek REST alanları snake_case metindir ("type": "set_flag", "channel": "in_game", "status": "pending").
• Realtime çerçeve type ve kind değerleri PascalCase’tir (Authenticate, PlayerSelf); alan adları camelCase’tir.
• Sohbet soketi çerçeve type değerleri camelCase, alan adları snake_case’tir (channel_id).
• Webhook olay türleri snake_case’tir (webhook olayları).
• Eklenti şema belgesinde enum olarak listelenen değerler (ör. "image/png") birebir kullanılır.

İstemcinizde bilinmeyen bir enum değeri gelirse (yeni sürümde eklenmiş olabilir) çökmek yerine güvenli bir varsayılana düşün; SDK’lar bilinmeyen değeri kimi yerde reddeder, kimi yerde atlar, bu yüzden sürüm yükseltmelerini değişiklik günlüğünden izleyin.

Metin

• Tüm metin UTF-8 JSON metnidir.
• Alanların uzunluk sınırları vardır (ör. Idempotency-Key 200 karakter, eklenti dize alanlarında minLength/maxLength); sınır ihlali 400 alır.
• Düz metin hata mesajları (çekirdek REST) İngilizce ya da Türkçe olabilir ve sürümler arasında değişir; makine kararı için kullanmayın (hatalar).