İçerik grupları

Bu sayfa araçlar, silahlar, NPC’ler ya da polis birimleri gibi oyun verisini kod yayımlamadan değiştirmenizi sağlayan içerik gruplarını anlatır. Verinin panelde nasıl tanımlanıp yayınlandığını ve oyunun onu nasıl okuduğunu öğrenmek istiyorsanız okuyun.

Ne işe yarar

İçerik grubu, sizin tanımladığınız tipli bir tablodur: grubun alanları (ör. hiz, hasar, renk, model) vardır ve her kayıt (ör. sedan) bu alanlar için değer taşır. Operatör değeri panelde düzenler ve yayınlar; oyun yalnızca yayınlanmış güncel hâli okur. Böylece bir değeri değiştirmek için oyunu yeniden dağıtmanız gerekmez.

İçerik grupları çekirdektir: ayrı bir modül anahtarı yoktur ve her ortamda çalışır.

Panelde nerede

Veri modeli (düz dille)

• Grup: key (^[a-z][a-z0-9_]{1,47}$, yani 2–48 karakter), ad ve alanlar. Anahtar oluşturulduktan sonra değişmez.

• Alan: key (aynı kural) ve bir tür. On tür vardır:

  Tür (kind)	Ne tutar	Ayarlar
  integer	Tam sayı (isteğe bağlı ondalık gösterim ölçeği)	min, max, scale (0–3), unit (en çok 12 karakter), default
  percent	Baz puan yüzde (10000 = %100)	min_bp, max_bp, default_bp
  text	Metin	max_chars (en çok 512), multiline
  bool	Evet/hayır	default
  select	Seçenek(ler)	options (en çok 64), multiple
  color	Renk	#rrggbb
  model	3B model	model kütüphanesi kimliği
  image	Görsel	varlığın sha256 değeri
  reference	Başka kayda bağlantı	hedef: başka bir grup, yerleşik eşya ya da yerleşik karakter
  table	Tekrarlanan satırlı matris	columns (1–8), min_rows, max_rows (en çok 100)

• Görünürlük (audience): Her alan player (oyuncuya gider) ya da server (yalnız sunucu anahtarı görür) olabilir.

• Kayıt (entry): key (^[a-z0-9][a-z0-9_-]{0,63}$) ve alan değerleri. Durumu: Yayında, Taslak değişikliği var, Arşivli, Henüz yayınlanmadı.

• Yayın: Panelde “Değişiklikleri oyuna gönder” ile yapılır; en çok 280 karakterlik bir not alır ve sıralı bir yayın sayacı (seq) üretir. Bir sonraki yayın öncekini değiştirmez, yenisini ekler; geçmiş ve fark panelde görünür. Siz bakarken biri yayınladıysa panel farkı yeniler ve yeniden onay ister.

• Sayılar: Tamsayıdır; kesirli ya da üslü gösterim (40.0, 1e2) reddedilir. Ölçekli tamsayıyı oyunda formatScaled ile gösterin.

Not

Eşya ve karakter şablonları da panelde yerleşik gruplar olarak görünür; onlar “kaydedince hemen oyunda” davranır ve yayın adımı istemez. Kullanıcı tanımlı gruplar yayın ister.

Sınırlar: ortamda en çok 64 grup, grupta 48 alan ve 1000 kayıt; bir kaydın tablo verisi 128 KiB’ı, sunucu kitlesi için yayın görüntüsü 1 MiB’ı aşamaz.

Katalog: eşya ve karakter

Oyun, eşya ve karakter tanımlarını (anahtar, ad, tipli veri satırları ve 3B model adresi) katalog uçlarından okur:

Bunlar items ve characters modüllerine bağlıdır; modül kapalıysa 404. Liste sayfalıdır (limit 1–100, varsayılan 50; cursor). Her manifest kind, key, name, definition_version, data (tipli satırlar), model (yoksa null) ve content_sha256 taşır. Ayrıntı, ETag ile izleme ve three ile model gösterme: Oyun katalog entegrasyonu (docs/oyun-katalog-entegrasyonu.md) ve Scene, görsel ve 3B modeller.

Oyunun yaptığı çağrılar (içerik grupları)

İçerik grupları salt okunur bir yüzeyle sunulur; oyun taslağa ulaşamaz. İki kimlik türü vardır:

• Oyuncu oturumu (çerez ya da oturum belirteci + x-crx-env: <ortam uuid>): yalnız visibility = player alanları ve değerlerini görür.
• Sunucu anahtarı (Authorization: Bearer crx_live_<önek>_<gizli>): bütün alanları görünürlükleriyle ve seq ile görür. Geçersiz bir Bearer crx_… anahtarı geçerli bir çerezle bile 401 alır; çereze düşülmez.

Başlıklar:

Yanıtlar kitleye özgü ETag taşır. Oyuncu ETag’i ve content_sha256 değeri süzülmüş gövdeden hesaplanır; bu yüzden yalnız-sunucu bir alanı değiştirmek oyuncu tarafında hiçbir değişiklik göstermez. Hiç yayınlanmamış ya da olmayan grup 404 döner.

Not

Yalnız-sunucu satırlar bir sır deposu değildir: panelde operatörler ve sunucu anahtarı tutanlar görür. Parola, anahtar ya da kişisel veri koymayın.

Tablo alanı

table alanı bir kayıtta tekrarlanan satırları tutar (silahın seviye → hasar tablosu, NPC ganimet listesi). Sütun türleri integer, percent, text, bool, select ve reference’tır. Değer, satır sırasını koruyan nesne dizisidir; sırayı değiştirmek yeni bir yayın özeti demektir. Yalnız-sunucu tablo oyuncu gövdesinde hiç yoktur.

Oyundan okumak

TypeScript SDK’sı iki kitle için de tipli okuyucu sağlar (player.catalog.groups, sunucuda CrxClient.catalog.groups; list, get, entry). İzleme için watchCatalogGroup ve ölçekli sayıyı göstermek için formatScaled vardır. Unity SDK’sında katalog yoktur; ham REST kullanılır.

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

• Okuma uçlarında Idempotency-Key ya da If-Match yoktur; If-None-Match ile koşullu okuma yaparsınız.
• Yayın sayacı (seq) her yayında artar; seq değişmediyse içerik değişmemiştir.
• Grup, alan ve kayıt anahtarları oluşturulduktan sonra değişmez; alan türü değişimi denetlenir ve panel sorunları yayın öncesinde listeler.

Olaylar

İçerik grubu yayını outbox’a olay yazmaz (yalnız denetim kaydı düşer), dolayısıyla webhook üretmez. Değişikliği oyunda yakalamak için ETag ile yoklayın: değişim oyuncuya en geç bir yoklama aralığı sonra ulaşır; bir dakikalık aralık yeterlidir.

Sınırlar

• 64 grup / 48 alan / 1000 kayıt; tablo en çok 8 sütun ve 100 satır; kayıt tablo verisi 128 KiB; sunucu yayın görüntüsü 1 MiB.
• Metin alanı en çok 512 karakter; seçim alanı en çok 64 seçenek.
• Yayın notu en çok 280 karakter.

Sık görülen hatalar

Çalışan örnek

weapons grubunun güncel yayınını ETag ile okuma:

/** İçerik grubunu (panelde yayınlanan oyun verisi) oyuncu oturumuyla okur; ETag ile değişmediyse 304 döner. */
import type { PlayerClient } from "@ferdiunal/open-play-ts";

/** `weapons` grubunun güncel yayınındaki kayıt anahtarlarını döndürür; değişmediyse boş liste. */
export async function readWeapons(player: PlayerClient, previousEtag?: string): Promise<readonly string[]> {
  const result = await player.catalog.groups.get("weapons", previousEtag === undefined ? {} : { ifNoneMatch: previousEtag });
  if (result.status === 304) return [];
  return result.value.entries.map((entry) => entry.key);
}

İlgili sayfalar

• İçerik grupları ödül kaynağı olarak · Envanter ve eşyalar · Karakterler · Scene, görsel ve 3B modeller
• Oyun katalog entegrasyonu (ayrıntılı rehber) (docs/oyun-katalog-entegrasyonu.md) · TypeScript SDK