> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Guild SDK for Game Engine API リファレンス
ゲームエンジン向け GS2-Guild SDK の モデルの仕様 と API のリファレンス
## モデル
### EzGuild
ギルド
ギルドは最大5個の属性を持つことができ、ギルドの検索やギルド一覧表示の際に利用できます。
ギルドには参加ポリシーを設定でき、自由参加と承認制を選択できます。
自由参加を選択した場合、ギルドへの参加リクエストを行うと即座にギルドメンバーとなります。
承認制を選択した場合、ギルドへの参加リクエストを行うとギルドマスターまたはギルドメンバーが承認するまでギルドメンバーにはなりません。
ギルドメンバーにはロールを設定でき、ギルドマスター、ギルドメンバーに加えてギルドが独自に定義した最大10個のカスタムロールを設定できます。
ギルドメンバーはギルドに参加した際にデフォルトで付与されるロールを設定できます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| guildModelName | string | | ✓ | | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| name | string | | ✓ | UUID | ~ 36文字 | ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
| displayName | string | | ✓ | | ~ 64文字 | 表示名
UI でプレイヤーに表示されるギルドの人間が読める名前です。ギルド名（システム生成の UUID）とは異なり、表示名はギルド作成者が設定し、更新も可能です。ギルド検索結果、メンバーリスト、その他のプレイヤー向け表示に使用されます。 |
| attribute1 | int | | | | 0 ~ 2147483645 | 属性1
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。レベル、地域、プレイスタイル、アクティビティ要件などのカスタムギルドプロパティを定義するために、最大5つの属性を開発者が利用できます。 |
| attribute2 | int | | | | 0 ~ 2147483645 | 属性2
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute3 | int | | | | 0 ~ 2147483645 | 属性3
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute4 | int | | | | 0 ~ 2147483645 | 属性4
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute5 | int | | | | 0 ~ 2147483645 | 属性5
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| metadata | string | | | | ~ 1024文字 | ギルドのメタデータ
GS2 の動作に影響しないギルドに関連付けられた任意のデータです。ギルドの紋章、説明、募集メッセージ、その他のカスタムデータなど、ゲーム固有の情報を保存するために使用できます。 |
| joinPolicy | 文字列列挙型
enum {
"anybody",
"approval"
}
| | ✓ | | | 参加方針
ユーザーがこのギルドにどのように参加できるかを制御します。"anybody" は承認なしで任意のユーザーが即座に参加できます。"approval" はユーザーがメンバーになる前にギルドマスターまたは権限を持つメンバーが参加リクエストを承認する必要があります。ギルドマスターがいつでも変更可能です。"anybody": 自由参加 / "approval": 承認制 / |
| customRoles | [List<EzRoleModel>](#ezrolemodel) | | | [] | 0 ~ 10 items | カスタムロールリスト
モデルレベルのロールをオーバーライドまたは拡張するギルド固有のカスタムロール定義のリストです。各ギルドは固有の権限セットを持つ最大10個のカスタムロールを定義できます。これらのロールはモデルレベルのロールに加えてメンバーに割り当てることができます。 |
| members | [List<EzMember>](#ezmember) | | | [] | 0 ~ 100 items | ギルドメンバーリスト
ギルドマスターと一般メンバーを含む、このギルドの全現在メンバーのリストです。各エントリにはメンバーのユーザーID、割り当てられたロール、メタデータ、参加タイムスタンプが含まれます。メンバー数は currentMaximumMemberCount を超えることができません。 |
**関連するメソッド:**
batchUpdateGuildMemberRole - 複数のギルドメンバーのロールをまとめて変更する
createGuild - ギルドを新規作成する
deleteGuild - ギルドを解散（削除）する
deleteMemberFromGuild - メンバーをギルドから除名する
getGuild - ギルドの詳細を取得する
listGuilds - 参加できるギルドを検索する
updateGuild - ギルドの設定を更新する
updateGuildMemberRole - ギルドメンバーのロールを変更する
acceptRequest - プレイヤーの参加リクエストを承認する
sendRequest - ギルドに参加リクエストを送信する
updateMemberMetadata - ギルド内の自分のメンバーメタデータを更新する
withdrawGuild - ギルドから自主的に脱退する
addIgnoreUser - プレイヤーのギルド参加をブロックする
getLastGuildMasterActivity - ギルドマスターの最終アクティビティ日時を確認する
promoteSeniorMember - 非アクティブなギルドマスターを最古参メンバーに交代する
---
### EzReceiveMemberRequest
受信した参加リクエスト
メンバーの登録申請を受け付けた状態であることを表すエンティティです。
該当ギルドが受信した参加リクエストです。
該当ギルドが承認を行うと参加リクエストは削除され、メンバーリストに登録されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID
このギルドに参加リクエストを送信したプレイヤーのGS2ユーザーIDです。申請者を識別し、承認時にギルドのメンバーリストに追加するため、または拒否時に通知するために使用されます。 |
| targetGuildName | string | | ✓ | | ~ 128文字 | 宛先ギルド名
この参加リクエストを受信したギルドの一意な名前（UUID）です。この保留中のリクエストを受信ボックスに持つ特定のギルドインスタンスを識別し、ギルドのメンバー管理操作とリクエストを照合するために使用されます。 |
**関連するメソッド:**
acceptRequest - プレイヤーの参加リクエストを承認する
getReceiveRequest - 特定の参加リクエストの詳細を取得する
listReceiveRequests - ギルドが受け取った参加リクエストの一覧を取得する
rejectRequest - プレイヤーの参加リクエストを拒否する
---
### EzSendMemberRequest
送信した参加リクエスト
メンバーの登録を申請中である状態を表すエンティティです。
該当ユーザーがギルドに対して送信した参加リクエストです。
対象のギルドが承認すると参加リクエストは削除され、メンバーリストに登録されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID
このギルド参加リクエストを送信したプレイヤーのGS2ユーザーIDです。リクエスト元のユーザーを識別し、承認時にギルドのメンバーリストに追加するために使用されます。 |
| targetGuildName | string | | ✓ | | ~ 128文字 | 宛先ギルド名
参加リクエストが送信されたギルドの一意な名前（UUID）です。ユーザーが参加をリクエストしている特定のギルドインスタンスを識別し、リクエスト処理のためにギルドの受信ボックスを特定するために使用されます。 |
**関連するメソッド:**
cancelRequest - プレイヤーが送信した参加リクエストを取り下げる
getSendRequest - プレイヤーが送信した参加リクエストの詳細を取得する
listSendRequests - プレイヤーが送信した参加リクエストの一覧を取得する
sendRequest - ギルドに参加リクエストを送信する
---
### EzJoinedGuild
参加中のギルド
特定のギルドへのユーザーのメンバーシップを表します。ユーザーがギルドに参加した際（直接参加またはリクエスト承認）に作成され、ユーザーが離脱または追放された際に削除されます。ユーザーが現在どのギルドに所属しているかを追跡し、maxConcurrentJoinGuilds 制限の適用を可能にします。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| guildModelName | string | | ✓ | | ~ 128文字 | ギルドモデル名
参加中のギルドが属するギルドモデルの名前です。メンバーシップ制限、ロール設定、その他のギルドタイプ設定を含むギルドモデル定義を参照します。 |
| guildName | string | | ✓ | | ~ 128文字 | ギルド名
ユーザーが参加したギルドの一意な名前（UUID）です。ギルドモデル内の特定のギルドインスタンスを識別するために使用されます。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| createdAt | long | | ※ | 現在時刻 | | 作成日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getJoinedGuild - プレイヤーが所属する特定のギルドの詳細を取得する
listJoinedGuilds - プレイヤーが所属しているギルドの一覧を取得する
withdrawGuild - ギルドから自主的に脱退する
---
### EzIgnoreUser
拒否ユーザー
特定のギルドへの参加がブロックされているユーザーを表します。ユーザーが拒否リストに追加されると、参加リクエストは自動的に拒否され、参加ポリシーが自由参加に設定されていてもギルドに参加できません。ギルドマスターが不要なメンバーを管理するために使用します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
**関連するメソッド:**
addIgnoreUser - プレイヤーのギルド参加をブロックする
deleteIgnoreUser - ギルドのブロックリストからプレイヤーを解除する
getIgnoreUser - 特定のプレイヤーがギルドのブロックリストに登録されているか確認する
listIgnoreUsers - ギルドのブロックリストを取得する
---
### EzLastGuildMasterActivity
最後のギルドマスターアクティビティ
ギルド内でギルドマスターが最後にアクティビティを行った日時を追跡します。このタイムスタンプは非アクティブベースの継承システムで使用されます。ギルドモデルで設定された inactivityPeriodDays がギルドマスターのアクティビティなしに経過すると、リーダーシップを別のメンバーに自動的に移譲できます。各ギルドはギルドマスターがギルド操作を行うたびに更新される1つのアクティビティレコードを持ちます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getLastGuildMasterActivity - ギルドマスターの最終アクティビティ日時を確認する
promoteSeniorMember - 非アクティブなギルドマスターを最古参メンバーに交代する
---
### EzGuildModel
ギルドモデル
ギルドモデルとは、ギルドの加入可能最大人数の設定や、ギルド内での役職ごとの権限設定を持つエンティティです。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 2048文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| defaultMaximumMemberCount | int | | ✓ | | 1 ~ 2147483646 | デフォルト最大メンバー数
新しいギルドが作成される際に許可されるメンバーの初期最大数です。この値は新規ギルドの currentMaximumMemberCount の初期値として使用されます。ギルド操作や入手アクションを通じて、後から maximumMemberCount の上限まで増加させることができます。 |
| maximumMemberCount | int | | ✓ | | 1 ~ 2147483646 | 最大メンバー数上限
ギルドが持つことができるメンバー数の絶対的な上限です。ギルドの currentMaximumMemberCount はこの値を超えることができません。ギルドが意図されたサイズを超えて成長するのを防ぐハードキャップとして機能します。 |
| roles | [List<EzRoleModel>](#ezrolemodel) | | ✓ | | 1 ~ 10 items | ロールモデルリスト
このタイプのギルド内で利用可能なロール定義のリストです。guildMasterRole および guildMemberDefaultRole で参照されるロールを少なくとも含む必要があります。各ロールはポリシードキュメントを介して固有の権限セットを定義します。最大10個のロールを定義できます。 |
| rejoinCoolTimeMinutes | int | | | 0 | 0 ~ 2147483646 | 再参加クールタイム（分）
ユーザーがギルドを離脱した後、再度ギルドに参加できるようになるまでのクールダウン期間（分）です。0 に設定すると即時再参加が可能になります。ユーザーが繰り返しギルドに参加・離脱する悪用パターンを防止します。 |
**関連するメソッド:**
getGuildModel - 名前を指定してギルドタイプ定義を取得する
listGuildModels - ギルドタイプ定義の一覧を取得する
---
### EzRoleModel
ロールモデル
ロールモデルはギルド内での役割を定義し、その役割ごと実行できる処理に関する権限を設定します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | ロールモデル名
ロールモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 2048文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| policyDocument | string | | ✓ | | ~ 10240文字 | ポリシードキュメント
このロールの権限を定義する JSON 形式のポリシードキュメントです。このロールに割り当てられたメンバーに対して、どのギルド操作（参加リクエストの承認/拒否、メンバー追放、ギルド情報の更新、メンバーロールの変更など）が許可または拒否されるかを指定します。 |
**関連するメソッド:**
createGuild - ギルドを新規作成する
updateGuild - ギルドの設定を更新する
**関連するモデル:**
EzGuild - ギルド
EzGuildModel - ギルドモデル
---
### EzMember
メンバー
ギルドメンバーの一覧を管理するエンティティ
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| roleName | string | | ✓ | | ~ 128文字 | ロールモデル名
ロールモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 512文字 | ギルドメンバーのメタデータ
GS2 の動作に影響しないこのギルドメンバーに関連付けられた任意のデータです。貢献ポイント、最終ログイン時間、ギルド役員に表示されるメモなど、メンバー固有の情報を保存するために使用できます。 |
| joinedAt | long | | ※ | 現在時刻 | | 参加日時
UNIX 時間・ミリ秒 |
**関連するメソッド:**
batchUpdateGuildMemberRole - 複数のギルドメンバーのロールをまとめて変更する
**関連するモデル:**
EzGuild - ギルド
---
### EzVerifyActionResult
検証アクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 検証アクションで実行するアクションの種類 |
| verifyRequest | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int | | | | 0 ~ 999 | ステータスコード |
| verifyResult | string | | | | ~ 1048576文字 | 結果内容 |
**関連するモデル:**
EzTransactionResult - トランザクション実行結果
---
### EzConsumeActionResult
消費アクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 消費アクションで実行するアクションの種類 |
| consumeRequest | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int | | | | 0 ~ 999 | ステータスコード |
| consumeResult | string | | | | ~ 1048576文字 | 結果内容 |
**関連するモデル:**
EzTransactionResult - トランザクション実行結果
---
### EzAcquireActionResult
入手アクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 入手アクションで実行するアクションの種類 |
| acquireRequest | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int | | | | 0 ~ 999 | ステータスコード |
| acquireResult | string | | | | ~ 1048576文字 | 結果内容 |
**関連するモデル:**
EzTransactionResult - トランザクション実行結果
---
### EzTransactionResult
トランザクション実行結果
サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string | | ✓ | | 36 ~ 36文字 | トランザクションID |
| verifyResults | [List<EzVerifyActionResult>](#ezverifyactionresult) | | | | 0 ~ 10 items | 検証アクションの実行結果リスト |
| consumeResults | [List<EzConsumeActionResult>](#ezconsumeactionresult) | | | [] | 0 ~ 10 items | 消費アクションの実行結果リスト |
| acquireResults | [List<EzAcquireActionResult>](#ezacquireactionresult) | | | [] | 0 ~ 100 items | 入手アクションの実行結果リスト |
---
## メソッド
### getGuildModel
名前を指定してギルドタイプ定義を取得する
名前を指定して、ギルドモデルを1件取得します。
取得できる情報には、メンバー上限、ロール定義とその権限、参加方式の設定、再加入クールダウン期間、非アクティブギルドマスターの継承設定が含まれます。
特定のギルドタイプのルールを表示する際に使います。たとえば、ギルド作成画面や詳細画面で「最大メンバー: 30人、参加: 承認制、ロール: マスター / 副団長 / メンバー」のように表示できます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuildModel](#ezguildmodel) | ギルドモデル|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->GuildModel(
"guild-0001" // guildModelName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->GuildModel(
"guild-0001" // guildModelName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listGuildModels
ギルドタイプ定義の一覧を取得する
このネームスペースに登録されているすべてのギルドモデルを取得します。
ギルドモデルはギルドのルールを定義します。最大メンバー数、ロール権限（「副団長はメンバーを除名できる」など）、参加方式（自由参加/承認制）、再加入クールダウン、プレイヤーが同時に所属できるギルド数などです。
ギルドマスターが長期間ログインしない場合の自動交代（最古参メンバーへの継承）の設定も含まれます。
プレイヤーがギルドを閲覧・作成する際に、どんなタイプのギルドがあるかを表示するのに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzGuildModel>](#ezguildmodel) | ギルドモデルリスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.GuildModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.GuildModels(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->GuildModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGuildModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGuildModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGuildModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGuildModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeGuildModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeGuildModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### assume
ギルドの代理として操作する権限を取得する
ギルドとして操作を行うためのギルドアクセストークンを取得します。ギルド設定の更新、参加リクエストの承認、メンバーの除名などの操作に必要です。
プレイヤーはそのギルドのメンバーである必要があり、実行できる操作はロール権限に依存します。
UpdateGuild、AcceptRequest、RejectRequest、DeleteMemberFromGuild などのギルド管理APIを呼ぶ前に必ず必要なステップです。
「ギルド管理モードに切り替える」ようなイメージです。これを呼んだ後、返されたトークンを使って続くギルド操作を行います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildName | string | | ✓| UUID | ~ 36文字 | ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| token | string | アクセストークン|
| userId | string | ユーザーID|
| expire | long | 有効期限
トークンの有効期限を示すタイムスタンプです。この時刻に達すると、トークンは無効になります。
UNIX 時間・ミリ秒|
#### Error
このAPIには特別な例外が定義されています。
GS2-SDK for Game Engine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| NotIncludedGuildMemberException | NotFoundException | ギルドメンバーではありません。 |
#### 実装例
**Unity (UniTask)**
```csharp
try {
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.AssumeAsync(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
} catch(Gs2.Gs2Guild.Exception.NotIncludedGuildMemberException e) {
// You are not a member of the guild.
}
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.AssumeFuture(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Guild.Exception.NotIncludedGuildMemberException)
{
// You are not a member of the guild.
}
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto Future = Domain->Assume(
"guild-model-0001", // guildModelName
"guild-0001" // guildName
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Guild::Error::FNotIncludedGuildMemberError::Class))
{
// You are not a member of the guild.
}
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### batchUpdateGuildMemberRole
複数のギルドメンバーのロールをまとめて変更する
複数のギルドメンバーのロールを1回のAPI呼び出しでまとめて更新します。たとえば、複数のメンバーを同時に「副団長」に昇格させるといった操作です。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバーのみがこの操作を実行できます。
ギルドマスターが多数のメンバーのロールを一度に再編成したい場合に、1人ずつ変更する代わりに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| members | [List<EzMember>](#ezmember) | | ✓| | 1 ~ 100 items | 更新するメンバーリスト |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 更新したギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var result = await domain.BatchUpdateGuildMemberRoleAsync(
guildModelName: "guild-model-0001",
accessToken: null,
members: new List {
new Gs2.Unity.Gs2Guild.Model.EzMember() {
UserId = "user-0002",
RoleName = "role-0001",
},
new Gs2.Unity.Gs2Guild.Model.EzMember() {
UserId = "user-0003",
RoleName = "role-0002",
},
}
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var future = domain.BatchUpdateGuildMemberRoleFuture(
guildModelName: "guild-model-0001",
accessToken: null,
members: new List {
new Gs2.Unity.Gs2Guild.Model.EzMember() {
UserId = "user-0002",
RoleName = "role-0001",
},
new Gs2.Unity.Gs2Guild.Model.EzMember() {
UserId = "user-0003",
RoleName = "role-0002",
},
}
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
);
const auto Future = Domain->BatchUpdateGuildMemberRole(
"guild-model-0001", // guildModelName
nullptr, // accessToken
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithUserId(TOptional("user-0002"))
->WithRoleName(TOptional("role-0001"))
);
v->Add(
MakeShared()
->WithUserId(TOptional("user-0003"))
->WithRoleName(TOptional("role-0002"))
);
return v;
}() // members
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### createGuild
ギルドを新規作成する
プレイヤーをギルドマスター（リーダー）として新しいギルドを作成します。
ギルドの表示名、最大5つのカスタム属性（プレイスタイル、活動時間、言語など）、メタデータ、参加方式（自由参加/承認制）、カスタムロール定義を設定できます。
ギルドを作成したプレイヤーは自動的にギルドマスターロールの最初のメンバーになります。
「ギルドを作成」ボタンやフォームに使います。プレイヤーが新しいギルドの名前、ルール、設定を決める画面です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| displayName | string | | ✓| | ~ 64文字 | 表示名
UI でプレイヤーに表示されるギルドの人間が読める名前です。ギルド名（システム生成の UUID）とは異なり、表示名はギルド作成者が設定し、更新も可能です。ギルド検索結果、メンバーリスト、その他のプレイヤー向け表示に使用されます。 |
| attribute1 | int | | | | 0 ~ 2147483645 | 属性1
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。レベル、地域、プレイスタイル、アクティビティ要件などのカスタムギルドプロパティを定義するために、最大5つの属性を開発者が利用できます。 |
| attribute2 | int | | | | 0 ~ 2147483645 | 属性2
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute3 | int | | | | 0 ~ 2147483645 | 属性3
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute4 | int | | | | 0 ~ 2147483645 | 属性4
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute5 | int | | | | 0 ~ 2147483645 | 属性5
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| metadata | string | | | | ~ 1024文字 | ギルドのメタデータ
GS2 の動作に影響しないギルドに関連付けられた任意のデータです。ギルドの紋章、説明、募集メッセージ、その他のカスタムデータなど、ゲーム固有の情報を保存するために使用できます。 |
| memberMetadata | string | | | | ~ 512文字 | ギルドメンバーのメタデータ
GS2 の動作に影響しないこのギルドメンバーに関連付けられた任意のデータです。貢献ポイント、最終ログイン時間、ギルド役員に表示されるメモなど、メンバー固有の情報を保存するために使用できます。 |
| joinPolicy | 文字列列挙型
enum {
"anybody",
"approval"
}
| | ✓| | | 参加方針
ユーザーがこのギルドにどのように参加できるかを制御します。"anybody" は承認なしで任意のユーザーが即座に参加できます。"approval" はユーザーがメンバーになる前にギルドマスターまたは権限を持つメンバーが参加リクエストを承認する必要があります。ギルドマスターがいつでも変更可能です。"anybody": 自由参加 / "approval": 承認制 / |
| customRoles | [List<EzRoleModel>](#ezrolemodel) | | | [] | 0 ~ 10 items | カスタムロールリスト
モデルレベルのロールをオーバーライドまたは拡張するギルド固有のカスタムロール定義のリストです。各ギルドは固有の権限セットを持つ最大10個のカスタムロールを定義できます。これらのロールはモデルレベルのロールに加えてメンバーに割り当てることができます。 |
| guildMemberDefaultRole | string | | | | ~ 128文字 | デフォルトカスタムロール
この特定のギルドに新しいメンバーが参加した際に自動的に割り当てられるカスタムロールです。設定した場合、このギルドに対してギルドモデルの guildMemberDefaultRole をオーバーライドします。customRoles リストで定義されたロールを参照する必要があります。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 作成したギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.CreateGuildAsync(
guildModelName: "guild-model-0001",
displayName: "My Guild",
joinPolicy: "anybody",
attribute1: 1,
attribute2: null,
attribute3: null,
attribute4: null,
attribute5: null,
metadata: null,
memberMetadata: null,
customRoles: null,
guildMemberDefaultRole: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.CreateGuildFuture(
guildModelName: "guild-model-0001",
displayName: "My Guild",
joinPolicy: "anybody",
attribute1: 1,
attribute2: null,
attribute3: null,
attribute4: null,
attribute5: null,
metadata: null,
memberMetadata: null,
customRoles: null,
guildMemberDefaultRole: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto Future = Domain->CreateGuild(
"guild-model-0001", // guildModelName
"My Guild", // displayName
"anybody", // joinPolicy
1 // attribute1
// attribute2
// attribute3
// attribute4
// attribute5
// metadata
// memberMetadata
// customRoles
// guildMemberDefaultRole
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### deleteGuild
ギルドを解散（削除）する
ギルドを完全に削除します。すべてのメンバーが脱退し、ギルドはなくなります。
このAPIはギルドとして呼び出します（先に Assume が必要）。通常、ギルドマスターのみがギルドを解散する権限を持ちます。
ギルド設定画面の「ギルドを解散」ボタンに使います。全メンバーに影響する破壊的な操作なので、必ず確認ダイアログを表示してください。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 削除したギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var result = await domain.DeleteGuildAsync(
accessToken: null
);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var future = domain.DeleteGuildFuture(
accessToken: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
const auto Future = Domain->DeleteGuild(
nullptr // accessToken
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### deleteMemberFromGuild
メンバーをギルドから除名する
指定したプレイヤーをギルドのメンバーリストから削除します。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバー（通常はギルドマスターや副団長）のみがメンバーを除名できます。
メンバー管理画面の「除名」ボタンに使います。操作の取り消しが難しいため、確認ダイアログの表示をおすすめします。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| targetUserId | string | | ✓| | ~ 128文字 | 除名するユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 更新したギルド|
#### Error
このAPIには特別な例外が定義されています。
GS2-SDK for Game Engine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| GuildMasterRequiredException | BadRequestException | ギルドマスター権限を持つメンバーが最低1名必要です。 |
#### 実装例
**Unity (UniTask)**
```csharp
try {
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var result = await domain.DeleteMemberFromGuildAsync(
accessToken: null,
targetUserId: "user-0002"
);
} catch(Gs2.Gs2Guild.Exception.GuildMasterRequiredException e) {
// At least one member with guild master privileges is required.
}
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var future = domain.DeleteMemberFromGuildFuture(
accessToken: null,
targetUserId: "user-0002"
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Guild.Exception.GuildMasterRequiredException)
{
// At least one member with guild master privileges is required.
}
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
const auto Future = Domain->DeleteMemberFromGuild(
nullptr, // accessToken
"user-0002" // targetUserId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Guild::Error::FGuildMasterRequiredError::Class))
{
// At least one member with guild master privileges is required.
}
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### getGuild
ギルドの詳細を取得する
特定のギルドの詳細情報を取得します。表示名、カスタム属性、メタデータ、メンバーリスト、参加方式などが含まれます。
返される情報は、リクエストしたプレイヤーとギルドの関係によって異なります。ギルドメンバーはメンバーリストを含む完全な情報を見られますが、非メンバーは公開情報のみです。
ギルド詳細画面を表示するのに使います。たとえば「ドラゴンナイツ — 25/30人 — 参加: 承認制」のように表示できます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildName | string | | ✓| UUID | ~ 36文字 | ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | ギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listGuilds
参加できるギルドを検索する
プレイヤーが参加できるギルドを検索します。表示名、属性、参加方式でフィルタリングできます。
最大5つのカスタム属性（プレイスタイル、言語、活動レベルなど）と参加方式（自由参加/承認制）でフィルタリング可能です。
すでに定員に達したギルドを含めるかどうかも選択できます。
注意: 過去24時間以内に更新されたギルドのみが検索結果に表示されます。ギルドを検索対象に残したい場合は、変更がなくても定期的に UpdateGuild を呼んでください。
「ギルドを探す」画面を構築して、検索フィルターとマッチするギルドの一覧を表示するのに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| displayName | string | | | | ~ 64文字 | 検索するギルド表示名 |
| attributes1 | List<int> | | | | 0 ~ 10 items | 検索する属性1 |
| attributes2 | List<int> | | | | 0 ~ 10 items | 検索する属性2 |
| attributes3 | List<int> | | | | 0 ~ 10 items | 検索する属性3 |
| attributes4 | List<int> | | | | 0 ~ 10 items | 検索する属性4 |
| attributes5 | List<int> | | | | 0 ~ 10 items | 検索する属性5 |
| joinPolicies | List<string> | | | | 0 ~ 10 items | 検索するギルド参加方法リスト |
| includeFullMembersGuild | bool | | | false | | ギルドメンバーが満員のギルドを検索結果に含めるか |
| orderBy | 文字列列挙型
enum {
"number_of_players",
"attribute1_asc",
"attribute1_desc",
"attribute2_asc",
"attribute2_desc",
"attribute3_asc",
"attribute3_desc",
"attribute4_asc",
"attribute4_desc",
"attribute5_asc",
"attribute5_desc",
"last_updated"
}
| | | "number_of_players" | | 並び順"number_of_players": 参加プレイヤー数 / "attribute1_asc": 属性1昇順 / "attribute1_desc": 属性1降順 / "attribute2_asc": 属性2昇順 / "attribute2_desc": 属性2降順 / "attribute3_asc": 属性3昇順 / "attribute3_desc": 属性3降順 / "attribute4_asc": 属性4昇順 / "attribute4_desc": 属性4降順 / "attribute5_asc": 属性5昇順 / "attribute5_desc": 属性5降順 / "last_updated": 最終更新日時 / |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzGuild>](#ezguild) | ギルドのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SearchGuildsAsync(
guildModelName: "guild-model-0001"
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.SearchGuilds(
guildModelName: "guild-model-0001"
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->SearchGuilds(
"guild-model-0001" // guildModelName
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### updateGuild
ギルドの設定を更新する
ギルドの表示名、カスタム属性、メタデータ、参加方式、ロール定義を更新します。
このAPIはギルドとして呼び出します。先に Assume でギルドのアクセストークンを取得してから呼んでください。
適切なロール権限を持つメンバーのみがギルド設定を更新できます。
また、定期的にこれを呼ぶことで、ギルドが検索結果に表示され続けます（24時間更新がないギルドは検索から非表示になります）。
「ギルド設定」画面に使います。副団長やギルドマスターがギルド名、説明、募集方針を変更する画面です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| displayName | string | | ✓| | ~ 64文字 | 表示名
UI でプレイヤーに表示されるギルドの人間が読める名前です。ギルド名（システム生成の UUID）とは異なり、表示名はギルド作成者が設定し、更新も可能です。ギルド検索結果、メンバーリスト、その他のプレイヤー向け表示に使用されます。 |
| attribute1 | int | | | | 0 ~ 2147483645 | 属性1
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。レベル、地域、プレイスタイル、アクティビティ要件などのカスタムギルドプロパティを定義するために、最大5つの属性を開発者が利用できます。 |
| attribute2 | int | | | | 0 ~ 2147483645 | 属性2
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute3 | int | | | | 0 ~ 2147483645 | 属性3
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute4 | int | | | | 0 ~ 2147483645 | 属性4
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| attribute5 | int | | | | 0 ~ 2147483645 | 属性5
ギルド検索でのフィルタリングやソートに使用できるギルドの数値属性です。詳細は attribute1 を参照してください。 |
| metadata | string | | | | ~ 1024文字 | ギルドのメタデータ
GS2 の動作に影響しないギルドに関連付けられた任意のデータです。ギルドの紋章、説明、募集メッセージ、その他のカスタムデータなど、ゲーム固有の情報を保存するために使用できます。 |
| joinPolicy | 文字列列挙型
enum {
"anybody",
"approval"
}
| | ✓| | | 参加方針
ユーザーがこのギルドにどのように参加できるかを制御します。"anybody" は承認なしで任意のユーザーが即座に参加できます。"approval" はユーザーがメンバーになる前にギルドマスターまたは権限を持つメンバーが参加リクエストを承認する必要があります。ギルドマスターがいつでも変更可能です。"anybody": 自由参加 / "approval": 承認制 / |
| customRoles | [List<EzRoleModel>](#ezrolemodel) | | | [] | 0 ~ 10 items | カスタムロールリスト
モデルレベルのロールをオーバーライドまたは拡張するギルド固有のカスタムロール定義のリストです。各ギルドは固有の権限セットを持つ最大10個のカスタムロールを定義できます。これらのロールはモデルレベルのロールに加えてメンバーに割り当てることができます。 |
| guildMemberDefaultRole | string | | | | ~ 128文字 | デフォルトカスタムロール
この特定のギルドに新しいメンバーが参加した際に自動的に割り当てられるカスタムロールです。設定した場合、このギルドに対してギルドモデルの guildMemberDefaultRole をオーバーライドします。customRoles リストで定義されたロールを参照する必要があります。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 更新したギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var result = await domain.UpdateGuildAsync(
accessToken: null,
displayName: "My Guild",
joinPolicy: "anybody",
attribute1: 1,
attribute2: null,
attribute3: null,
attribute4: null,
attribute5: null,
metadata: null,
customRoles: null,
guildMemberDefaultRole: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var future = domain.UpdateGuildFuture(
accessToken: null,
displayName: "My Guild",
joinPolicy: "anybody",
attribute1: 1,
attribute2: null,
attribute3: null,
attribute4: null,
attribute5: null,
metadata: null,
customRoles: null,
guildMemberDefaultRole: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
const auto Future = Domain->UpdateGuild(
nullptr, // accessToken
"My Guild", // displayName
"anybody", // joinPolicy
1 // attribute1
// attribute2
// attribute3
// attribute4
// attribute5
// metadata
// customRoles
// guildMemberDefaultRole
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### updateGuildMemberRole
ギルドメンバーのロールを変更する
特定のギルドメンバーのロールを変更します。たとえば、メンバーを「副団長」に昇格させたり、副団長を「メンバー」に降格させたりできます。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバーのみが他のメンバーのロールを変更できます。
「メンバー管理」画面に使います。ギルドマスターや副団長がメンバーの昇格・降格を行う画面です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| targetUserId | string | | ✓| | ~ 128文字 | 更新するユーザーID |
| roleName | string | | ✓| | ~ 128文字 | ロールモデル名
ロールモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 更新したギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var result = await domain.UpdateGuildMemberRoleAsync(
accessToken: null,
targetUserId: "user-0002",
roleName: "role-0001"
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var future = domain.UpdateGuildMemberRoleFuture(
accessToken: null,
targetUserId: "user-0002",
roleName: "role-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
const auto Future = Domain->UpdateGuildMemberRole(
nullptr, // accessToken
"user-0002", // targetUserId
"role-0001" // roleName
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### acceptRequest
プレイヤーの参加リクエストを承認する
保留中の参加リクエストを承認して、リクエストしたプレイヤーをギルドのメンバーリストに追加します。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバーのみが参加リクエストを承認できます。
承認後、プレイヤーはギルドモデルで定義されたデフォルトロールでギルドメンバーになります。
参加リクエストの詳細画面やリスト画面の「承認」ボタンに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| fromUserId | string | | ✓| | ~ 128文字 | ユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzReceiveMemberRequest](#ezreceivememberrequest) | 承諾した参加リクエスト|
| guild | [EzGuild](#ezguild) | ギルド|
#### Error
このAPIには特別な例外が定義されています。
GS2-SDK for Game Engine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| MaximumJoinedGuildsReachedException | BadRequestException | ギルドへの同時参加数が最大値に達しています。 |
| MaximumMembersReachedException | BadRequestException | メンバーが上限に達しています。 |
#### 実装例
**Unity (UniTask)**
```csharp
try {
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
var result = await domain.AcceptRequestAsync(
accessToken: null
);
} catch(Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException e) {
// The number of guilds you can join at the same time has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumMembersReachedException e) {
// The number of members has reached the upper limit.
}
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
var future = domain.AcceptRequestFuture(
accessToken: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException)
{
// The number of guilds you can join at the same time has reached the upper limit.
}
if (future.Error is Gs2.Gs2Guild.Exception.MaximumMembersReachedException)
{
// The number of members has reached the upper limit.
}
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-0001", // guildModelName
"guildName-0001", // guildName
"user-0001" // userId
)->ReceiveMemberRequest(
nullptr // fromUserId
);
const auto Future = Domain->AcceptRequest(
nullptr // accessToken
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Guild::Error::FMaximumJoinedGuildsReachedError::Class))
{
// The number of guilds you can join at the same time has reached the upper limit.
}
if (e->IsChildOf(Gs2::Guild::Error::FMaximumMembersReachedError::Class))
{
// The number of members has reached the upper limit.
}
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### getReceiveRequest
特定の参加リクエストの詳細を取得する
送信者のユーザーIDを指定して、ギルドが受け取った特定の参加リクエストの詳細を取得します。
このAPIはギルドとして呼び出します（先に Assume が必要）。
参加リクエストの詳細画面を表示するのに使います。たとえば、応募者のプロフィール、メッセージ、「承認」「拒否」ボタンを表示する画面です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| fromUserId | string | | ✓| | ~ 128文字 | ユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzReceiveMemberRequest](#ezreceivememberrequest) | 参加リクエスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-0001", // guildModelName
"guildName-0001", // guildName
"user-0001" // userId
)->ReceiveMemberRequest(
nullptr // fromUserId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-0001", // guildModelName
"guildName-0001", // guildName
"user-0001" // userId
)->ReceiveMemberRequest(
nullptr // fromUserId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listReceiveRequests
ギルドが受け取った参加リクエストの一覧を取得する
プレイヤーたちがこのギルドに送った、保留中の参加リクエストをすべて取得します。
このAPIはギルドとして呼び出します（先に Assume でギルドのアクセストークンを取得してください）。
各リクエストには、送信者と添付されたメッセージやメタデータが含まれます。
ギルド管理パネルの「参加リクエスト」画面を構築するのに使います。たとえば「PlayerAが参加を希望（メッセージ: Lv50ヒーラー、毎日ログイン）」のようなリストを表示できます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzReceiveMemberRequest>](#ezreceivememberrequest) | 参加リクエストのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
);
var items = await domain.ReceiveRequestsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
);
var it = domain.ReceiveRequests(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-0001", // guildModelName
"guildName-0001", // guildName
"user-0001" // userId
);
const auto It = Domain->ReceiveRequests(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### rejectRequest
プレイヤーの参加リクエストを拒否する
保留中の参加リクエストを拒否します。リクエストしたプレイヤーはギルドに追加されません。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバーのみが参加リクエストを拒否できます。
拒否されたプレイヤーは、ギルドのブロックリスト（IgnoreUser）に追加されていない限り、再度参加リクエストを送ることができます。
参加リクエストの詳細画面やリスト画面の「拒否」ボタンに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| fromUserId | string | | ✓| | ~ 128文字 | ユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzReceiveMemberRequest](#ezreceivememberrequest) | 拒否した参加リクエスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: null,
guildName: "guild-0001",
userId: null
).ReceiveMemberRequest(
fromUserId: "user-0002"
);
var result = await domain.RejectRequestAsync(
accessToken: null
);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: null,
guildName: "guild-0001",
userId: null
).ReceiveMemberRequest(
fromUserId: "user-0002"
);
var future = domain.RejectRequestFuture(
accessToken: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
nullptr, // guildModelName
"guild-0001", // guildName
nullptr // userId
)->ReceiveMemberRequest(
"user-0002" // fromUserId
);
const auto Future = Domain->RejectRequest(
nullptr // accessToken
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### cancelRequest
プレイヤーが送信した参加リクエストを取り下げる
プレイヤーが以前ギルドに送った、保留中の参加リクエストを取り下げ（キャンセル）します。
取り下げ後、リクエストはプレイヤーの送信リクエストとギルドの受信リクエストの両方から削除されます。
取り下げ後、同じギルドに新しい参加リクエストを送ることができます。
申請中のリクエスト詳細画面の「申請を取り下げ」「リクエストをキャンセル」ボタンに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| targetGuildName | string | | ✓| | ~ 128文字 | 宛先ギルド名
参加リクエストが送信されたギルドの一意な名前（UUID）です。ユーザーが参加をリクエストしている特定のギルドインスタンスを識別し、リクエスト処理のためにギルドの受信ボックスを特定するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSendMemberRequest](#ezsendmemberrequest) | 削除した参加リクエスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.CancelRequestAsync(
guildModelName: "guild-0002",
targetGuildName: "guild-0002"
);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.CancelRequestFuture(
guildModelName: "guild-0002",
targetGuildName: "guild-0002"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto Future = Domain->CancelRequest(
"guild-0002", // guildModelName
"guild-0002" // targetGuildName
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### getSendRequest
プレイヤーが送信した参加リクエストの詳細を取得する
プレイヤーがギルドに送信した特定の参加リクエストの詳細を取得します。
取得できる情報には、リクエスト先のギルドとリクエストに添付されたメタデータ（メッセージ）が含まれます。
申請中のリクエストの詳細を表示するのに使います。たとえば「ドラゴンナイツに申請中 — メッセージ: Lv50ヒーラー」と「取り下げ」ボタンを表示する画面に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| targetGuildName | string | | ✓| | ~ 128文字 | 宛先ギルド名
参加リクエストが送信されたギルドの一意な名前（UUID）です。ユーザーが参加をリクエストしている特定のギルドインスタンスを識別し、リクエスト処理のためにギルドの受信ボックスを特定するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSendMemberRequest](#ezsendmemberrequest) | 参加リクエスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->SendMemberRequest(
"guild-0002", // guildModelName
nullptr // guildName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->SendMemberRequest(
"guild-0002", // guildModelName
nullptr // guildName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listSendRequests
プレイヤーが送信した参加リクエストの一覧を取得する
プレイヤーが各ギルドに送信した、まだ保留中の参加リクエストをすべて取得します。
各エントリには、リクエスト先のギルドとリクエストに添付されたメタデータ（メッセージ）が含まれます。
「申請中」「保留中のリクエスト」画面を構築するのに使います。たとえば「ドラゴンナイツに申請中（保留）、スターアライアンスに申請中（保留）」のような表示に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzSendMemberRequest>](#ezsendmemberrequest) | 参加リクエストのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SendRequestsAsync(
guildModelName: "guild-0002"
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.SendRequests(
guildModelName: "guild-0002"
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->SendRequests(
"guild-0002" // guildModelName
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### sendRequest
ギルドに参加リクエストを送信する
指定したギルドに参加リクエストを送信します。ギルドの参加方式が「自由参加」の場合は即座に加入し、「承認制」の場合はギルドの受信箱に審査待ちとして届きます。
リクエストにメタデータ（「Lv50ヒーラー、レイドグループ探し中」などのメッセージ）を添付できます。
プレイヤーがギルドのブロックリスト（IgnoreUser）に登録されている場合、リクエストは自動的に拒否されます。
ギルド詳細画面の「参加を申請」「加入リクエスト」ボタンに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| targetGuildName | string | | ✓| | ~ 128文字 | 送信先ギルド名 |
| metadata | string | | | | ~ 512文字 | ギルドメンバーのメタデータ
GS2 の動作に影響しないこのギルドメンバーに関連付けられた任意のデータです。貢献ポイント、最終ログイン時間、ギルド役員に表示されるメモなど、メンバー固有の情報を保存するために使用できます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 参加したギルド
承認が不要なギルドに参加した際に応答されます|
| sendMemberRequest | [EzSendMemberRequest](#ezsendmemberrequest) | 送信した参加リクエスト
承認が必要なギルドに参加リクエストを出した際に応答されます|
#### Error
このAPIには特別な例外が定義されています。
GS2-SDK for Game Engine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| MaximumMembersReachedException | BadRequestException | メンバーが上限に達しています。 |
| MaximumJoinedGuildsReachedException | BadRequestException | ギルドへの同時参加数が最大値に達しています。 |
| MaximumReceiveRequestsReachedException | BadRequestException | ギルドに対する参加リクエスト数が上限に達しています。 |
| MaximumSendRequestsReachedException | BadRequestException | 自分が出している参加リクエスト数が上限に達しています。 |
| DotMeetJoinRequirementsException | BadRequestException | ギルドへの参加条件を満たしていません。 |
#### 実装例
**Unity (UniTask)**
```csharp
try {
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.SendRequestAsync(
guildModelName: "guild-0002",
targetGuildName: "guild-0002",
metadata: null
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Guild.Exception.MaximumMembersReachedException e) {
// The number of members has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException e) {
// The number of guilds you can join at the same time has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumReceiveRequestsReachedException e) {
// The number of requests to join the guild has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumSendRequestsReachedException e) {
// You have reached the maximum number of requests you can send.
} catch(Gs2.Gs2Guild.Exception.DotMeetJoinRequirementsException e) {
// You do not meet the requirements to join the guild.
}
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.SendRequestFuture(
guildModelName: "guild-0002",
targetGuildName: "guild-0002",
metadata: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Guild.Exception.MaximumMembersReachedException)
{
// The number of members has reached the upper limit.
}
if (future.Error is Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException)
{
// The number of guilds you can join at the same time has reached the upper limit.
}
if (future.Error is Gs2.Gs2Guild.Exception.MaximumReceiveRequestsReachedException)
{
// The number of requests to join the guild has reached the upper limit.
}
if (future.Error is Gs2.Gs2Guild.Exception.MaximumSendRequestsReachedException)
{
// You have reached the maximum number of requests you can send.
}
if (future.Error is Gs2.Gs2Guild.Exception.DotMeetJoinRequirementsException)
{
// You do not meet the requirements to join the guild.
}
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto Future = Domain->SendRequest(
"guild-0002", // guildModelName
"guild-0002" // targetGuildName
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Guild::Error::FMaximumMembersReachedError::Class))
{
// The number of members has reached the upper limit.
}
if (e->IsChildOf(Gs2::Guild::Error::FMaximumJoinedGuildsReachedError::Class))
{
// The number of guilds you can join at the same time has reached the upper limit.
}
if (e->IsChildOf(Gs2::Guild::Error::FMaximumReceiveRequestsReachedError::Class))
{
// The number of requests to join the guild has reached the upper limit.
}
if (e->IsChildOf(Gs2::Guild::Error::FMaximumSendRequestsReachedError::Class))
{
// You have reached the maximum number of requests you can send.
}
if (e->IsChildOf(Gs2::Guild::Error::FDotMeetJoinRequirementsError::Class))
{
// You do not meet the requirements to join the guild.
}
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### getJoinedGuild
プレイヤーが所属する特定のギルドの詳細を取得する
プレイヤーが参加している特定のギルドのメンバーシップ詳細を取得します。
取得できる情報には、ギルド名、プレイヤーのロール、参加日、メンバーシップメタデータが含まれます。
特定のギルドでのプレイヤーのメンバーシップ情報を表示するのに使います。たとえば「参加日: 2024-01-15、ロール: 副団長、メモ: タンクメイン」のような表示に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string | | ✓| UUID | ~ 36文字 | ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzJoinedGuild](#ezjoinedguild) | 参加中のギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->JoinedGuild(
"guild-model-0001", // guildModelName
"guild-0001" // guildName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->JoinedGuild(
"guild-model-0001", // guildModelName
"guild-0001" // guildName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listJoinedGuilds
プレイヤーが所属しているギルドの一覧を取得する
プレイヤーが現在メンバーとして所属しているすべてのギルドを取得します。
ギルドモデル名でフィルタリングすることもできます。省略するとすべてのタイプのギルドが返されます。
各エントリにはギルド名、参加日時、現在のロールが含まれます。
「マイギルド」画面を構築するのに使います。たとえば「ドラゴンナイツ（副団長）、スターアライアンス（メンバー）」のような表示に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | | | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzJoinedGuild>](#ezjoinedguild) | 参加中のギルド|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.JoinedGuildsAsync(
guildModelName: "guild-model-0001"
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.JoinedGuilds(
guildModelName: "guild-model-0001"
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->JoinedGuilds(
"guild-model-0001" // guildModelName
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeJoinedGuilds(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeJoinedGuilds(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeJoinedGuilds(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeJoinedGuilds(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeJoinedGuilds(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeJoinedGuilds(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### updateMemberMetadata
ギルド内の自分のメンバーメタデータを更新する
ギルド内でのプレイヤー自身のメタデータを更新します。メタデータは自由形式のテキストで、メンバー固有の情報を何でも保存できます。
たとえば、希望ロール（「ヒーラー」）、自己紹介（「レイド仲間募集中」）、プレイスタイルの設定などを保存できます。
自分自身のメタデータのみ更新可能で、他のメンバーのメタデータは変更できません。
「ギルド内プロフィール編集」機能に使います。メンバーがギルド内でのステータスやメモを設定する画面に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string | | ✓| UUID | ~ 36文字 | ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
| gameSession | GameSession | | ✓| | | GameSession |
| metadata | string | | | | ~ 512文字 | ギルドメンバーのメタデータ
GS2 の動作に影響しないこのギルドメンバーに関連付けられた任意のデータです。貢献ポイント、最終ログイン時間、ギルド役員に表示されるメモなど、メンバー固有の情報を保存するために使用できます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGuild](#ezguild) | 更新したギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var result = await domain.UpdateMemberMetadataAsync(
metadata: "metadata-0001"
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var future = domain.UpdateMemberMetadataFuture(
metadata: "metadata-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->JoinedGuild(
"guild-model-0001", // guildModelName
"guild-0001" // guildName
);
const auto Future = Domain->UpdateMemberMetadata(
"metadata-0001" // metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### withdrawGuild
ギルドから自主的に脱退する
プレイヤーが現在所属しているギルドから脱退します。脱退後、プレイヤーはギルドのメンバーリストから削除されます。
どのメンバーでも自分の意志で脱退できます。ギルドマスターの承認は不要です。
注意: ギルドモデルに再加入クールダウンが設定されている場合、クールダウン期間が過ぎるまで同じギルドに再加入できません。
ギルド詳細画面や設定画面の「ギルドを脱退」ボタンに使います。再加入にクールダウンがある場合があるため、確認ダイアログの表示をおすすめします。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildName | string | | ✓| UUID | ~ 36文字 | ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzJoinedGuild](#ezjoinedguild) | 脱退したギルド|
| guild | [EzGuild](#ezguild) | ギルド|
#### Error
このAPIには特別な例外が定義されています。
GS2-SDK for Game Engine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| GuildMasterRequiredException | BadRequestException | ギルドマスター権限を持つメンバーが最低1名必要です。 |
#### 実装例
**Unity (UniTask)**
```csharp
try {
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var result = await domain.WithdrawGuildAsync(
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Guild.Exception.GuildMasterRequiredException e) {
// At least one member with guild master privileges is required.
}
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var future = domain.WithdrawGuildFuture(
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Guild.Exception.GuildMasterRequiredException)
{
// At least one member with guild master privileges is required.
}
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->JoinedGuild(
"guild-model-0001", // guildModelName
"guild-0001" // guildName
);
const auto Future = Domain->WithdrawGuild(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Guild::Error::FGuildMasterRequiredError::Class))
{
// At least one member with guild master privileges is required.
}
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### addIgnoreUser
プレイヤーのギルド参加をブロックする
プレイヤーをギルドのブロックリストに追加します。ブロックされると、そのプレイヤーはこのギルドに参加リクエストを送れなくなり、今後のリクエストは自動的に拒否されます。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバーのみがブロックリストを管理できます。
「ブロック」ボタンに使います。たとえば、問題のあるメンバーを除名した後に再加入リクエストを防ぐ場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| userId | string | | ✓| | ~ 128文字 | ユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzIgnoreUser](#ezignoreuser) | 参加を拒否するユーザーID|
| guild | [EzGuild](#ezguild) | ギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var result = await domain.AddIgnoreUserAsync(
accessToken: null,
userId: "user-0001"
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var future = domain.AddIgnoreUserFuture(
accessToken: null,
userId: "user-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
const auto Future = Domain->AddIgnoreUser(
nullptr, // accessToken
"user-0001" // userId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### deleteIgnoreUser
ギルドのブロックリストからプレイヤーを解除する
プレイヤーをギルドのブロックリストから削除します。ブロック解除後、そのプレイヤーは再びこのギルドに参加リクエストを送れるようになります。
このAPIはギルドとして呼び出します（先に Assume が必要）。適切なロール権限を持つメンバーのみがブロックリストを管理できます。
ブロック中のプレイヤー管理画面の「ブロック解除」ボタンに使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| userId | string | | ✓| | ~ 128文字 | ユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzIgnoreUser](#ezignoreuser) | 参加を拒否するユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
var result = await domain.DeleteIgnoreUserAsync(
accessToken: null,
userId: "user-0001"
);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
var future = domain.DeleteIgnoreUserFuture(
accessToken: null,
userId: "user-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
)->IgnoreUser(
);
const auto Future = Domain->DeleteIgnoreUser(
nullptr, // accessToken
"user-0001" // userId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### getIgnoreUser
特定のプレイヤーがギルドのブロックリストに登録されているか確認する
特定のプレイヤーがこのギルドへの参加をブロックされているかどうかを確認します。
このAPIはギルドとして呼び出します（先に Assume が必要）。
「ブロック」「ブロック解除」ボタンを表示する前にプレイヤーのブロック状態を確認するのに使います。たとえば、メンバー管理画面やプレイヤープロフィール画面で活用できます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| userId | string | | ✓| | ~ 128文字 | ユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzIgnoreUser](#ezignoreuser) | 参加を拒否するユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
)->IgnoreUser(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
)->IgnoreUser(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listIgnoreUsers
ギルドのブロックリストを取得する
ギルドが参加をブロックしているプレイヤーの一覧を取得します。
このAPIはギルドとして呼び出します（先に Assume でギルドのアクセストークンを取得してください）。
ブロックされたプレイヤーはこのギルドに参加リクエストを送れません。リクエストは自動的に拒否されます。
ギルド設定の「ブロック中のプレイヤー」管理画面を構築するのに使います。たとえば、ブロック中のプレイヤーのリストと「ブロック解除」ボタンを表示する画面です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzIgnoreUser>](#ezignoreuser) | 参加を拒否するユーザーIDリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
var items = await domain.IgnoreUsersAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
var it = domain.IgnoreUsers(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
);
const auto It = Domain->IgnoreUsers(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeIgnoreUsers(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeIgnoreUsers(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeIgnoreUsers(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeIgnoreUsers(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeIgnoreUsers(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeIgnoreUsers(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getLastGuildMasterActivity
ギルドマスターの最終アクティビティ日時を確認する
ギルドマスターの最新のアクティビティの日時を取得します。
このAPIはギルドとして呼び出します（先に Assume でギルドのアクセストークンを取得してください）。
ギルドマスターの活動状況を表示するのに使います。たとえば「ギルドマスター最終ログイン: 3日前」のような表示に便利です。
ギルドマスターが十分な期間非アクティブで、自動交代（PromoteSeniorMember）を実行すべきかどうかの判断に役立ちます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzLastGuildMasterActivity](#ezlastguildmasteractivity) | 参加を拒否するユーザーID|
| guild | [EzGuild](#ezguild) | ギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
)->LastGuildMasterActivity(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
)->LastGuildMasterActivity(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### promoteSeniorMember
非アクティブなギルドマスターを最古参メンバーに交代する
ギルドモデルの非アクティブ設定で定義された期間、ギルドマスターがアクティブでない場合に、最も長く在籍しているメンバーを新しいギルドマスターに昇格させます。
このAPIはギルドとして呼び出します（先に Assume が必要）。非アクティブ期間のしきい値はギルドモデルで設定されます。
ギルドマスターがゲームをプレイしなくなった際に、ギルドが「停滞」するのを防ぎます。
ギルドマスターが非アクティブの場合に表示される「リーダーを引き継ぐ」ボタンに使います。たとえば「ギルドマスターが30日間ログインしていません。最古参メンバーとして、あなたが引き継ぐことができます。」のように表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| guildModelName | string | | ✓| | ~ 128文字 | ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| accessToken | string | | ✓| | ~ 128文字 | ギルド名 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzLastGuildMasterActivity](#ezlastguildmasteractivity) | 参加を拒否するユーザーID|
| guild | [EzGuild](#ezguild) | ギルド|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
var result = await domain.PromoteSeniorMemberAsync(
accessToken: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
var future = domain.PromoteSeniorMemberFuture(
accessToken: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
);
const auto Future = Domain->PromoteSeniorMember(
nullptr // accessToken
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
## イベントハンドラ
### OnReceiveRequestNotification
参加リクエストを受信したときに使用するプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildModelName | string |ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildName | string |ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。|
| fromUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Guild.OnReceiveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Guild.OnReceiveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Guild->OnReceiveRequestNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
const auto FromUserId = Notification->FromUserIdValue;
});
```
---
### OnRemoveRequestNotification
参加リクエストが削除されたときに使用するプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildModelName | string |ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildName | string |ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。|
| fromUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Guild.OnRemoveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Guild.OnRemoveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Guild->OnRemoveRequestNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
const auto FromUserId = Notification->FromUserIdValue;
});
```
---
### OnChangeNotification
ギルド情報が更新されたときに発行されるプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildModelName | string |ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildName | string |ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Guild.OnChangeNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
};
```
**Unity (Vanilla)**
```cs
gs2.Guild.OnChangeNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
};
```
**Unreal Engine 5**
```cpp
Gs2->Guild->OnChangeNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
});
```
---
### OnJoinNotification
ギルドメンバーが追加されたときに発行されるプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildModelName | string |ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildName | string |ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。|
| joinedUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Guild.OnJoinNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var joinedUserId = notification.JoinedUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Guild.OnJoinNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var joinedUserId = notification.JoinedUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Guild->OnJoinNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
const auto JoinedUserId = Notification->JoinedUserIdValue;
});
```
---
### OnLeaveNotification
ギルドメンバーが除籍されたときに発行されるプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildModelName | string |ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildName | string |ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。|
| leavedUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Guild.OnLeaveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var leavedUserId = notification.LeavedUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Guild.OnLeaveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var leavedUserId = notification.LeavedUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Guild->OnLeaveNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
const auto LeavedUserId = Notification->LeavedUserIdValue;
});
```
---
### OnChangeMemberNotification
メンバーの情報が更新されたときに発行されるプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildModelName | string |ギルドモデル名
ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| guildName | string |ギルド名
ギルドの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。|
| changedUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Guild.OnChangeMemberNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var changedUserId = notification.ChangedUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Guild.OnChangeMemberNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var changedUserId = notification.ChangedUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Guild->OnChangeMemberNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
const auto ChangedUserId = Notification->ChangedUserIdValue;
});
```
---