Oyun kuralları ve otomasyonlar

Bu sayfa panelin “Kurallar” ekranının iki parçasını anlatır: oyunun eklentisinin bildirdiği oyun kuralı değerleri (örneğin polis eşikleri) ve olay olunca otomatik iş yapan otomasyonlar. Oyunun davranışını kod yayımlamadan ayarlamak ya da bir olaya otomatik tepki vermek istiyorsanız okuyun.

Ne işe yarar

• Oyun kuralı değerleri: Oyunun eklentisi hangi sayıların ayarlanabilir olduğunu bildirir (ad, birim, alt ve üst sınır, adım, varsayılan). Operatör bu değerleri panelde değiştirir ve yayınlar; yeni değerler oyunda kısa süre içinde (en geç yaklaşık 6 saniye) geçerli olur. Her yayın yeni bir sürüm olur ve tek tıkla eski değerlere dönülebilir.
• Otomasyonlar: “Şu olay olunca, şu koşul doğruysa, şunu yap” biçiminde kurallar. Kural, karakter olaylarına (level_up, xp_added …) bağlanır ve karaktere stat, kaynak, bayrak, değiştirici ya da ödül verir. Koşullar CEL ifadesiyle yazılır; panelde yapısal bir oluşturucu CEL’i sizin için üretir.

Oyun kuralı değerleri panel yüzeyidir: oyun sunucunuz bunları bir REST ucuyla yazmaz; eklenti değerleri sunucuda okur. Otomasyonlar ise hem panelden hem REST ile yönetilir (characters modülünün parçasıdır).

Panelde nerede

Oyun kuralı değerleri

Model

• Katalog: Oyunun eklentisi bildirir. Konular, kartlar ve her kartın parametreleri vardır; her parametre bir birimle (örn. saniye, metre, yüzde) ve sınırlarla gelir. Katalog yoksa ya da eklenti bildirmiyorsa panelde yalnız Otomasyonlar görünür.
• Sürüm: Etkin değerler en son sürümdür. Hiç yayın yoksa eklentinin kod varsayılanları kullanılır (“Kod varsayılanı”). Yayın ve geri alma yeni sürüm yazar; geçmiş silinmez.
• Uygulama zamanı: Parametre canlı ise yayından sonra kısa sürede uygulanır; yeniden başlatmada ise oyun sunucusu yeniden başlayana dek eski değer kalır ve panel “Yayında / Bekliyor” olarak ikisini birlikte gösterir.
• Doğrulama: Değerler katalog sınırı, adım ve alanlar arası kısıtlarla sunucuda doğrulanır; hatalı alan alan başına bildirilir. Eklenti ayrıca aynı sınırlarla yeniden doğrular; geçersiz bir değer oyunu bozmaz, eklenti kod varsayılanlarına döner.
• Yetki: Okuma dört panel rolünde; yayın ve geri alma yalnız super_admin ve game_manager rollerinde. Yayın ve geri alma 8–500 karakterlik bir gerekçe ister ve denetim kaydına yazılır.
• Eşzamanlılık: Yayın, gördüğünüz sürümü (expectedVersion) taşır; siz bakarken başka biri yayınladıysa 409 döner ve sekmeyi yenilemeniz gerekir.
• Önizleme: Panel, bir senaryoyu (örn. sürekli hız ihlali) eklentinin gerçek mantığıyla bugünkü ve önerilen değerlerle çalıştırıp olay zaman çizelgesini gösterir; hiçbir şey kaydetmez.
• İstemci uyarısı: Bir parametre clientVisible ise oyun istemcisi onu eklentinin sorgusundan okur. İstemci o değeri henüz okumuyorsa panel yayın sırasında sizi uyarır.

Oyuna etkisi

Oyun kuralı değerlerini oyun kodunuz REST ile okumaz. Eklenti değerleri sunucuda her adımda tek bir görüntüden alır; istemciye gereken değerler eklentinin kendi sorgusuyla gelir. Bu davranış eklentiye özgüdür; bugün yalnız package-ride eklentisi bir katalog bildirir. Üçüncü taraf eklentilerin katalog bildirmesi ve yüklenmesi henüz desteklenmez; bkz. Eklentiler: genel bakış.

Otomasyonlar

Model

• Kural (rule): key (tekil anahtar), trigger_type (tetikleyici olay), condition (CEL ifadesi), actions (eylem listesi) ve priority. Kural sürümlüdür; her yayın yeni sürümdür.
• Tetikleyici: flag_set, attribute_set, resource_changed, modifier_added, modifiers_removed, xp_added, level_up, ability_unlocked, event_emitted, character_rolled_back. Bilinmeyen tür reddedilir. Panel oluşturucusu character_rolled_back seçeneğini sunmaz.
• Eylemler: add_stat (key, delta), add_resource (key, delta), set_flag (key, value), add_modifier, remove_modifier ve grant_reward (what: sabit para { "type": "currency", "key", "amount" } ya da ödül tablosu { "type": "table", "key" }).
• CEL bağlamı: Koşulda character, event, now ve seed değişkenleri vardır; has_ability, base_stat ve clamp işlevleri kullanılabilir. Zamanı ve tohumu bağlam taşır, kural kendi saatini okuyamaz; now() ve random() yoktur. Kurallar kayıt anında derlenir, çalışma anında değil.
• Bütçe (değişmez): Bir komut zincirinde en çok 50 kural değerlendirilir, 200 eylem üretilir, zincir derinliği 5’i, koşul ifadesi 500 düğümü aşamaz. Aşım fail-closed’dur: komut 429 ile reddedilir ve hangi sınırın aşıldığı söylenir. Birbirini tetikleyen iki kural bu sınırla kesilir.

Panel oluşturucusu

Oluşturucu “Ne zaman → Koşullar → Ne yap” yapısından CEL üretir: koşul satırları (alan, işleç, değer) hepsi (&&) ya da herhangi biri (||) ile birleşir; en çok 20 koşul ve 10 eylem eklenebilir. Metin değerleri kaçışlanır; satır sonu ve kontrol karakterleri reddedilir. Oluşturucu varken sunucu kuralı yeniden derler (istemcinin gönderdiği CEL metni oluşturucu kuralında okunmaz). Yeni kural kapalı başlar; “hemen aç” seçeneği işaretsizdir. Yayın öncesi örnek bir olayla dry-run (deneme koşusu) yapabilirsiniz; zorunlu değildir.

Oyunun yaptığı çağrılar

Kural uçları API anahtarıyla çağrılır:

Authorization: Bearer crx_live_<önek>_<gizli>

Uyarı

Bilinen kısıt: Kural yazan uçlar anahtar türüne bakmaz; geçerli bir istemci anahtarı da kural kaydedebilir ya da silebilir. İstemci anahtarını oyuna gömüyorsanız kural yönetimini kendi sunucunuzdan yapın ve bu uçları istemciden çağırmayın.

TypeScript SDK’sı bu uçları tipli sunar: createRule, listRules, getRule, deleteRule, enableRule, disableRule, dryRunRule (bkz. TypeScript SDK). Bu uçlar ham CEL metni alır; panel oluşturucusunun yapısal modeli yalnız panel yüzeyindedir.

Kural kaydetmek

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

{
  "key": "lvl10_reward",
  "trigger_type": "level_up",
  "condition": "event.to == 10",
  "actions": [
    { "type": "grant_reward", "what": { "type": "currency", "key": "gold", "amount": 1000 } },
    { "type": "set_flag", "key": "reached_level_10", "value": true }
  ],
  "priority": 0
}

{ "key": "lvl10_reward", "current_version": 1, "enabled": true, "created_at": "2026-11-03T09:00:00Z" }

REST ile kaydedilen kural hemen açık başlar (enabled: true); panel oluşturucusundan farklı olarak kapalı başlatmak için kaydın ardından POST /v1/rules/{key}/disable çağırın. event.to seviye atlama olayının yeni seviyesidir; olay alanları tetikleyiciye göre değişir. Koşul derlenemezse, tetikleyici bilinmiyorsa ya da bütçe sınırı aşılıyorsa kayıt reddedilir.

Deneme koşusu

POST /v1/rules/dry-run
Authorization: Bearer crx_live_<önek>_<gizli>
Content-Type: application/json

{ "condition": "character.progression.level >= 10", "actions": [ { "type": "set_flag", "key": "veteran", "value": true } ], "character_id": "0192f0f2-…" }

{ "condition_result": true, "node_cost": 7, "would_produce_events": [ { "...": "…" } ], "would_grant": [], "warnings": [] }

Dry-run hiçbir olay yazmaz ve ödül vermez.

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

• Oyun kuralı yayını ve geri alma: Idempotency-Key ve expectedVersion ile panel tarafından yapılır; aynı anahtarla tekrar aynı sürümü döndürür, tek denetim kaydı yazar.
• Otomasyon yayını: her yayın yeni sürümdür; eski sürümler silinmez ve “geri al” eski sürümü yeni sürüm olarak yeniden yazar.
• REST kural uçlarında Idempotency-Key ve If-Match yoktur.

Olaylar

Kuralın çalıştırdığı eylemler normal karakter olaylarını üretir (flag_set, xp_added …); bunlar webhook’larla iletilebilir. Kuralın ürettiği ödül reward_granted olayı da üretir.

Sınırlar

• Komut zincirinde 50 kural, 200 eylem, derinlik 5, koşul başına 500 düğüm.
• Panel oluşturucusunda en çok 20 koşul ve 10 eylem.
• Oyun kuralı gerekçesi 8–500 karakter.
• Oyun kuralı tam sayı değerleri panelde ±(2^53−1) ile sınırlıdır.

Sık görülen hatalar

Çalışan örnek

Yukarıdaki iki istek (lvl10_reward kaydı ve dry-run) birlikte tam bir akıştır: önce dry-run ile koşulu deneyin, sonra POST /v1/rules ile kaydedin, sonra bir karaktere add_xp komutuyla seviye atlatarak kuralın çalıştığını Karakterler sayfasındaki akışla doğrulayın.

İlgili sayfalar

• Karakterler · Ödüller · Webhook’lar · Bildirimler
• Eklentiler: genel bakış · TypeScript SDK