Clans and parties

This page describes how to set up and manage persistent player communities (clans) and temporary teams (parties) in Open Play. Read it if you want to manage membership, invites, the clan treasury, clan XP and party reward distribution from a trusted server.

What it does

The social module (social) manages two structures:

• Clan: A persistent community. It has leader, officer and member roles, an invite and application flow, a shared treasury (a currency) and XP/level.
• Party: A temporary team. It has a capacity, a loot rule and reward splitting; it ends when it disbands.

Important: All of these endpoints are called with a server key. A player client cannot call a clan or party endpoint directly; the player’s identity is written in the request body (as actor_player_id and similar) by your trusted server. Verifying that a player “can manage their own clan” is your server’s job; Open Play enforces the role rules inside the clan (who can kick whom, who can withdraw from the treasury).

If the module is disabled, the endpoints return 404 with {"code":"module_disabled","module":"social"}. Enable the module on the Game settings › Modules page.

Where it lives in the panel

Note

Panel help pages are not translated yet; the panel links above point to the Turkish source.

Data model (in plain words)

Clan

• name (3–64 characters), tag (2–8 characters), leader_player_id, xp, highest_level_reached, state (active or disbanded) and members.
• Roles: leader, officer, member.
• Environment settings (/v1/clan-settings): max_members (the member limit), request_ttl_seconds (the lifetime of invites and applications), officer_can_withdraw (whether an officer can withdraw from the treasury) and level_curve_key (the level curve for the clan level).
• Invite: A call the clan sends to a player. Its statuses are pending, accepted, declined, revoked, expired.
• Application: A player’s application to a clan. Its statuses are pending, accepted, rejected, cancelled, expired.
• Treasury: The clan’s wallet; currency movement is done with deposit and withdraw and appears in the ledger as clan_treasury.

Party

• leader_player_id, capacity (positive), loot_rule (equal: equal shares, weighted: basis-point shares), state (active, disbanded) and members.
• Invite: Carries share_bp (the member’s basis-point share; under the weighted rule the shares must add up to exactly 10000) and is valid for 24 hours. Its statuses are pending, accepted, expired.
• Reward distribution: Splits a single currency amount among the members. With equal distribution the leftover minor units are distributed in player_id order; the result is always deterministic. The distribution record carries the member snapshot, the legs, delivery_mode (inline or outbox) and the status (processing, queued, completed).

Calls your game makes

All with a server (or admin) key:

Authorization: Bearer crx_live_<prefix>_<secret>

A client key and a player session are rejected (403).

Clan

Idempotency-Key is required on all clan write commands. The response is always in the same envelope: { "type": "clan" | "invite" | "application" | "settings" | "treasury" | "xp", "<kind>": { … }, "replayed": false }. For example, creating a clan:

POST /v1/clans
Authorization: Bearer crx_live_<prefix>_<secret>
Idempotency-Key: create-clan-player-1234
Content-Type: application/json

{ "leader_player_id": "0192f0f2-5b1a-7c3e-9d11-4a5b6c7d8e9f", "name": "Wolf Pack", "tag": "WLF" }

Returns 201 and the clan record comes inside a type: "clan" envelope. The TypeScript SDK exposes these endpoints in a typed way (createClan, getClan, createClanInvite, respondClanInvite, depositClanTreasury, addClanXp …); see TypeScript SDK.

Party

Idempotency-Key is required on party reward distribution; the same key returns the same distribution again with replayed: true and does not distribute a second time. The other party commands do not ask for Idempotency-Key.

Note

The TypeScript SDK has no typed client for the party endpoints; call them with raw REST.

Versioning and replay safety

• Clan commands and party reward distribution ask for Idempotency-Key: the same key and the same body do not run again (replayed: true); the same key with a different body is 422; the same key in flight is 409.
• If-Match is not used in this module.
• General rules: Idempotency and concurrency.

Events

Clan and party events (ClanMemberJoined, ClanXpAdded, PartyMemberJoined, RewardDistributed …) can be used in rule automation and quest objectives. Among the types you can select as a webhook filter there is no clan or party event; endpoints registered without a filter receive all events and clan/party events are included, but the envelope format is not a documented contract. Selectable types: Webhook events.

Limits

• A clan name is 3–64 characters, its tag 2–8 characters.
• A party capacity must be positive; exceeding the capacity is rejected. A party invite is valid for 24 hours.
• The clan member limit and the invite/application lifetime are in the environment settings.
• In a party reward the weighted shares must add up to 10000; amount must be positive.

Common errors

Working example

Creating a clan and sending an invite in TypeScript (with the SDK’s typed clan client):

/** 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;
}

Related pages

• Chat · Economy · Characters · Game rules
• TypeScript SDK · Errors