Klanlar ve partiler

Bu sayfa kalıcı oyuncu topluluklarını (klan) ve geçici takımları (parti) Open Play’de nasıl kuracağınızı ve yöneteceğinizi anlatır. Üyelik, davet, klan hazinesi, klan XP’si ve parti ödül dağıtımını güvenilir bir sunucudan yönetmek istiyorsanız okuyun.

Ne işe yarar

Sosyal modül (social) iki yapıyı yönetir:

• Klan (clan): Kalıcı topluluk. Lider, subay ve üye rolleri, davet ve başvuru akışı, ortak hazine (para birimi) ve XP/seviye vardır.
• Parti (party): Geçici takım. Kapasitesi, ganimet kuralı ve ödül bölüştürmesi vardır; dağılınca sona erer.

Önemli: Bu uçların hepsi sunucu anahtarıyla çağrılır. Oyuncu istemcisi doğrudan klan ya da parti ucunu çağıramaz; oyuncunun kimliği isteğin gövdesinde (actor_player_id gibi) sizin güvenilir sunucunuz tarafından yazılır. Oyuncunun “kendi klanını yönetebildiğini” doğrulamak sizin sunucunuzun işidir; Open Play klan içindeki rol kurallarını (kimin kimi atabileceği, hazineden kimin çekebileceği) uygular.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"social"} döner. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Veri modeli (düz dille)

Klan

• name (3–64 karakter), tag (2–8 karakter), leader_player_id, xp, highest_level_reached, state (active ya da disbanded) ve members.
• Roller: leader, officer, member.
• Ortam ayarları (/v1/clan-settings): max_members (üye sınırı), request_ttl_seconds (davet ve başvuru ömrü), officer_can_withdraw (subay hazineden çekebilir mi) ve level_curve_key (klan seviyesi için seviye eğrisi).
• Davet (invite): Klanın oyuncuya gönderdiği çağrı. Durumları pending, accepted, declined, revoked, expired.
• Başvuru (application): Oyuncunun klana başvurusu. Durumları pending, accepted, rejected, cancelled, expired.
• Hazine: Klanın cüzdanı; deposit ve withdraw ile para birimi hareketi yapılır ve defterde clan_treasury olarak görünür.

Parti

• leader_player_id, capacity (pozitif), loot_rule (equal: eşit pay, weighted: baz puan payları), state (active, disbanded) ve members.
• Davet: share_bp (üyenin baz puan payı; weighted kuralda payların toplamı tam 10000 olmalıdır) taşır ve 24 saat geçerlidir. Durumları pending, accepted, expired.
• Ödül dağıtımı: Tek bir para birimi tutarını üyelere böler. Eşit dağıtımda artık kuruşlar player_id sırasına göre dağıtılır; sonuç her zaman belirlenimcidir. Dağıtım kaydı üye anlık görüntüsünü, bacakları, delivery_mode (inline ya da outbox) ve durumu (processing, queued, completed) taşır.

Oyunun yaptığı çağrılar

Hepsi sunucu (ya da yönetici) anahtarıyla:

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

İstemci anahtarı ve oyuncu oturumu reddedilir (403).

Klan

Klan yazma komutlarının hepsinde Idempotency-Key zorunludur. Yanıt hep aynı zarftadır: { "type": "clan" | "invite" | "application" | "settings" | "treasury" | "xp", "<tür>": { … }, "replayed": false }. Örneğin klan kurma:

POST /v1/clans
Authorization: Bearer crx_live_<önek>_<gizli>
Idempotency-Key: clan-kur-oyuncu-1234
Content-Type: application/json

{ "leader_player_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f", "name": "Kurt Sürüsü", "tag": "KRT" }

201 döner ve type: "clan" zarfı içinde klan kaydı gelir. TypeScript SDK’sı bu uçları tipli olarak sunar (createClan, getClan, createClanInvite, respondClanInvite, depositClanTreasury, addClanXp …); bkz. TypeScript SDK.

Parti

Parti ödül dağıtımında Idempotency-Key zorunludur; aynı anahtarla tekrar aynı dağıtımı replayed: true ile döndürür, ikinci dağıtım yapmaz. Diğer parti komutları Idempotency-Key istemez.

Not

TypeScript SDK’sında parti uçları için tipli istemci yoktur; ham REST ile çağrılır.

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

• Klan komutları ve parti ödül dağıtımı Idempotency-Key ister: aynı anahtar ve aynı gövde tekrar çalışmaz (replayed: true); aynı anahtar farklı gövde 422; uçuşta aynı anahtar 409.
• If-Match bu modülde kullanılmaz.
• Genel kurallar: Idempotency ve eşzamanlılık.

Olaylar

Klan ve parti olayları (ClanMemberJoined, ClanXpAdded, PartyMemberJoined, RewardDistributed …) kural otomasyonunda ve görev hedeflerinde kullanılabilir. Webhook filtresi olarak seçilebilen türler arasında klan ya da parti olayı yoktur; filtresiz kayıtlı uç noktalar bütün olayları alır ve bunlara klan/parti olayları dahildir, ancak zarf biçimi belgelenmiş bir sözleşme değildir. Seçilebilir türler: Webhook olayları.

Sınırlar

• Klan adı 3–64, etiketi 2–8 karakter.
• Parti kapasitesi pozitif olmalı; kapasite aşımı reddedilir. Parti daveti 24 saat geçerlidir.
• Klan üye sınırı ve davet/başvuru ömrü ortam ayarlarındadır.
• Parti ödülünde weighted payların toplamı 10000 olmalıdır; amount pozitif olmalıdır.

Sık görülen hatalar

Çalışan örnek

TypeScript’te klan kurup davet gönderme (SDK’nın tipli klan istemcisiyle):

/** Güvenilir backend örneği: klan kurar ve bir oyuncuya davet gönderir. Server anahtarı yalnız sunucuda durur. */
import { CrxClient } from "@ferdiunal/open-play-ts";

/** Lider için klan kurar, ardından davet gönderir; her yazma kendi `Idempotency-Key`'iyle tekrar güvenlidir. */
export async function foundClanAndInvite(baseUrl: string, serverApiKey: string, leaderId: string, friendId: string): Promise<string> {
  const crx = new CrxClient({ baseUrl, apiKey: serverApiKey });
  const created = await crx.createClan({
    body: { leader_player_id: leaderId, name: "Kurt Sürüsü", tag: "KRT" },
    headers: { "Idempotency-Key": `clan-kur-${leaderId}` },
  });
  if (created.type !== "clan") throw new Error("Beklenmeyen yanıt zarfı");
  await crx.createClanInvite({
    path: { clan_id: created.clan.id },
    body: { inviter_player_id: leaderId, invitee_player_id: friendId },
    headers: { "Idempotency-Key": `davet-${created.clan.id}-${friendId}` },
  });
  return created.clan.id;
}

İlgili sayfalar

• Sohbet · Ekonomi · Karakterler · Oyun kuralları
• TypeScript SDK · Hatalar