Scene, görsel ve 3B modeller

Bu sayfa oyunun dünyasını oluşturan üç parçayı anlatır: gerçek zamanlı scene (sahne/oda) kaydı, panelden ve sunucudan yüklenen görseller ve operatörün yüklediği 3B modeller. Şehir odalarını sunucudan açmak, ikon ve afiş görselini yönetmek ya da modelleri oyuna sunmak istiyorsanız okuyun.

Ne işe yarar

• Scene: Gerçek zamanlı eklentinin oyuncuları topladığı oda. Oyun sunucusu açılışta ihtiyaç duyduğu scene’leri kaydeder; kayıt idempotenttir.
• Görsel (asset): PNG, JPEG ya da WebP. İçerik adreslidir: adres dosyanın sha256 özetidir, aynı dosya bir kez saklanır. Mağaza afişi, para birimi ikonu ve içerik grubu image alanları bu depoyu kullanır.
• 3B model: Operatörün panelde yüklediği glb (ya da dönüştürülen kaynak dosya). Yayınlanınca eşyaya ya da karaktere bağlanır ve oyun onu katalogdan alır.

Scene ve görsel yazma uçları scenes modülüne bağlıdır; modül kapalıysa 404 ve {"code":"module_disabled","module":"scenes"} döner. Görsel ve model okuma uçları çekirdektir ve modül kapalıyken de çalışır. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

Scene

• Kimlik üç parçadan türetilir: plugin_id (eklenti), module_id (gerçek zamanlı modül) ve key (en çok 96 karakter). Aynı üçlü her zaman aynı scene’e çıkar.
• capacity: Odanın oyuncu kapasitesi; en çok 10 000.
• state: open, draining (boşalıyor) ya da closed.
• partition_id: Scene’in dağıtık çalıştığı bölüm kimliği (sunucu üretir).

Görsel

• Tür dosyanın ilk baytlarından çıkarılır; Content-Type başlığı yalnız tavsiyedir. Kabul edilen türler image/png, image/jpeg, image/webp.
• En çok 2 MiB; genişlik ve yükseklik her biri en çok 4096 piksel.
• Yanıt sha256, contentType, byteSize ve created (bu çağrıda yazıldı mı) verir.

3B model

• Yükleme glb olabilir ya da fbx, obj, usdz, stl, blend, 3mf, dxf gibi kaynak biçimlerinden dönüştürülür. Dönüştürme durumu queued, converting, ready, failed’dır; başarısızlığın nedeni panelde Türkçe cümleyle görünür (ör. harici kaynağa başvuru, bütçe aşımı, 2B DXF).
• Her model sürümlüdür; yayınlanan sürüm katalogda görünür. Yaşam döngüsü active, archived, purged.
• Varsayılan sınırlar: yüklenen dosya 50 MiB, ortam kotası 1 GiB, ortamda 200 model, model başına 20 sürüm, operatör başına 10 dakikada 10 yükleme.
• Dönüştürücü yalnız amd64 mimarisinde çalışır; başka mimaride yalnız glb yüklenebilir.

Oyunun yaptığı çağrılar

Yönetim uçları Authorization: Bearer crx_live_<önek>_<gizli> ister; istemci anahtarı 403 alır.

Scene sağlamak

PUT /v1/scenes
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{ "plugin_id": "package-ride", "module_id": "package-ride.presence", "key": "istanbul-1", "capacity": 200 }

{ "scene_id": "…", "plugin_id": "package-ride", "module_id": "package-ride.presence", "key": "istanbul-1", "partition_id": "…", "capacity": 200, "state": "open", "created": true }

• Scene yoksa yazılır (201, created: true); varsa değiştirilmeden döner (200, created: false). Idempotency-Key gerekmez.
• 400: kimlik, anahtar ya da kapasite geçersiz (gövde hataları da 400’dür). 403: istemci anahtarı. 409: aynı anahtarda farklı kimlikli scene. 422: eklenti bu ortamda etkin değil.

Bir eklentinin gerçek zamanlı modüllerini ve oyuncu tarafı akışı için bkz. Gerçek zamanlı: genel bakış ve Eklentiler.

Görsel yüklemek

PUT /v1/assets
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: image/png

<ham PNG baytları>

{ "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "contentType": "image/png", "byteSize": 18234, "created": true }

201 ve created: true ilk yazımdır; aynı baytlar zaten varsa 200 ve created: false döner ve satır değişmez, yani yükleme idempotenttir. Boş gövde, tanınmayan tür, 2 MiB’ı aşan boyut ya da 4096 pikseli aşan en/boy 400 ile reddedilir (hata kodları asset_empty, asset_unsupported_type, asset_too_large, asset_dimensions_too_large).

Görseli oyunda göstermek için <img src="…/v1/assets/<sha256>?env=<ortam uuid>"> kullanın: uç kimliksizdir, ortamı x-crx-env başlığından ya da (başlık gönderemeyen <img>/doku yükleyicileri için) env sorgu parametresinden alır. Yanıt ETag olarak sha256 taşır ve süresiz önbelleğe alınabilir (immutable); If-None-Match eşleşirse 304 döner. Yeni görsel yeni sha256, yani yeni adres demektir.

Not

Görsel ve model okuma uçları, tarayıcının doku yükleyicisinin kullanabilmesi için çapraz kökenden okunabilir yanıt başlıkları gönderir. Diğer kamusal uçlar CORS’u yalnız ortamın alan adı listesindeki origin’lere verir; bkz. Mimari ve barındırma.

Uyarı

DELETE /v1/assets/{sha256} yalnız satırı siler; depo, başka kayıtların (ürün, ikon, içerik) bu görsele başvurup başvurmadığını bilmez. Silmeden önce görselin kullanılmadığından emin olun.

3B modeli oyuna almak

Modeli panelde yükleyip yayınlayın ve eşyaya ya da karaktere bağlayın. Oyun modelin adresini ve hesaplanmış gerçeklerini (üçgen sayısı, kemik, klipler, sınır kutusu) katalogdan okur; model.glb.url /v1/model-files/<sha256>?env=<ortam uuid> biçimindedir. Ayrıntı: İçerik grupları › Katalog ve Oyun katalog entegrasyonu (docs/oyun-katalog-entegrasyonu.md).

GET /v1/model-files/{sha256} kimliksizdir ve içerik adreslidir:

• Ortam x-crx-env başlığıyla ya da env sorgusuyla verilir; ikisi de verilip farklıysa ya da ikisi de yoksa 400.
• Yalnız hazır, dosyaları tutulan ve silinmemiş modelin glb dosyası döner; silinmiş modelde 404.
• Eşleşen If-None-Match dosyayı açmadan 304 verir. 200 yanıtı Content-Length, model/gltf-binary türü ve süresiz önbellek başlıklarını taşır. Range desteklenmez.
• Aynı sha256 her zaman aynı baytlardır: dosyayı sha256 ile önbelleğe alın, yeniden indirmeyin.

Not

Model yükleme ve yayınlama yalnız panelden yapılır; modeller için herkese açık bir yazma ucu yoktur. Unity SDK’sında katalog ve model okuma yardımcıları yoktur; ham REST kullanılır.

Sürümleme ve tekrar güvenliği

• PUT /v1/scenes ve PUT /v1/assets doğal olarak idempotenttir (türetilmiş kimlik, içerik adresi); Idempotency-Key istemezler.
• Model dosyası ve görsel içerik adreslidir: aynı adres hiçbir zaman başka bayt vermez.
• Model sürümleri panelde izlenir; oyun her zaman yayınlanmış güncel sürümü katalogdan görür.

Olaylar

Bu yüzeyler webhook olayı üretmez. Model değişikliği katalogda yeni sha256 olarak yansır; ETag ile yoklayın.

Sınırlar

• Görsel en çok 2 MiB ve 4096×4096 piksel; yalnız PNG, JPEG, WebP.
• Scene key en çok 96 karakter, capacity en çok 10 000.
• Model varsayılan sınırları yukarıdadır (50 MiB, 1 GiB kota, 200 model, 20 sürüm).
• GET /v1/assets sayfa boyu en çok 200 (varsayılan 50).

Sık görülen hatalar

Çalışan örnek

Görsel yükleme ve okuma:

curl -X PUT "$API/v1/assets" \
  -H "Authorization: Bearer $SERVER_KEY" -H "Content-Type: image/png" \
  --data-binary @afis.png

curl "$API/v1/assets/<sha256>?env=$ENV" -o afis.png

İlgili sayfalar

• İçerik grupları · Envanter ve eşyalar · Mağaza ve IAP
• Gerçek zamanlı: genel bakış · Eklentiler