GS2-Guild SDK for Game Engine API Reference
Model
EzGuild
Guild
A guild can have up to 5 attributes, which can be used when searching for guilds and displaying guild lists.
A guild can set a participation policy, allowing for either open participation or approval-based participation. If open participation is selected, a user who requests to join the guild will immediately become a guild member. If approval-based participation is selected, a user who requests to join the guild will not become a guild member until approved by the guild master or a guild member.
Guild members can be assigned roles, including guild master, guild member, and up to 10 custom roles defined by the guild. A default role can be assigned to guild members when they join the guild.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| name | string | ✓ | UUID | ~ 36 chars | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. | |||||||
| displayName | string | ✓ | ~ 64 chars | Display Name A human-readable name for the guild shown to players in the UI. Unlike the guild name (which is a system-generated UUID), the display name is set by the guild creator and can be updated. Used for guild search results, member lists, and other player-facing displays. | ||||||||
| attribute1 | int | 0 ~ 2147483645 | Attribute 1 A numeric attribute for the guild that can be used for filtering and sorting in guild search. Up to 5 attributes are available for developers to define custom guild properties such as level, region, play style, or activity requirements. | |||||||||
| attribute2 | int | 0 ~ 2147483645 | Attribute 2 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute3 | int | 0 ~ 2147483645 | Attribute 3 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute4 | int | 0 ~ 2147483645 | Attribute 4 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute5 | int | 0 ~ 2147483645 | Attribute 5 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| metadata | string | ~ 1024 chars | Guild Metadata Arbitrary data associated with the guild that does not affect GS2 behavior. Can be used to store game-specific information such as guild emblems, descriptions, recruitment messages, or other custom data. | |||||||||
| joinPolicy | String Enum enum { “anybody”, “approval” } | ✓ | Join Policy Controls how users can join this guild. “anybody” allows any user to join immediately without approval. “approval” requires the guild master or authorized members to approve join requests before the user becomes a member. This can be changed by the guild master at any time.
| |||||||||
| customRoles | List<EzRoleModel> | [] | 0 ~ 10 items | Custom Roles List A list of guild-specific custom role definitions that override or extend the model-level roles. Each guild can define up to 10 custom roles with unique permission sets. These roles can be assigned to members in addition to the model-level roles. | ||||||||
| members | List<EzMember> | [] | 0 ~ 100 items | Guild Member List The list of all current members of this guild, including guild masters and regular members. Each entry contains the member’s user ID, assigned role, metadata, and join timestamp. The number of members cannot exceed currentMaximumMemberCount. |
EzReceiveMemberRequest
Received Join Request
This entity represents a received guild join request that is awaiting approval. This is a participation request accepted by the relevant guild. Once the relevant guild approves it, the participation request is deleted and the member is added to the member list.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128 chars | User ID The GS2 user ID of the player who sent this join request to the guild. This identifies the applicant and is used to add them to the guild’s member list upon approval, or to notify them upon rejection. | ||
| targetGuildName | string | ✓ | ~ 128 chars | Target Guild Name The unique name (UUID) of the guild that received this join request. This identifies the specific guild instance whose inbox contains this pending request, and is used to match the request with the guild’s member management operations. |
EzSendMemberRequest
Sent Join Request
This entity represents the state of a member registration application in progress. This entity represents a guild join request sent by the user. When the recipient user approves it, the join request is deleted and the user is added to the member list.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128 chars | User ID The GS2 user ID of the player who sent this guild join request. This identifies the requesting user and is used to add them to the guild’s member list upon approval. | ||
| targetGuildName | string | ✓ | ~ 128 chars | Target Guild Name The unique name (UUID) of the guild to which the join request was sent. This identifies the specific guild instance that the user is requesting to join, and is used to locate the guild’s inbox for request processing. |
EzJoinedGuild
Joined Guild
Represents a user’s membership in a specific guild. Created when a user joins a guild (either directly or through approved request) and deleted when the user leaves or is expelled. Used to track which guilds a user currently belongs to, enabling enforcement of the maxConcurrentJoinGuilds limit.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| guildModelName | string | ✓ | ~ 128 chars | Guild Model Name The name of the guild model that the joined guild belongs to. References the guild model definition which contains membership limits, role configurations, and other guild type settings. | ||
| guildName | string | ✓ | ~ 128 chars | Guild Name The unique name (UUID) of the guild that the user has joined. Used to identify the specific guild instance within the guild model. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| createdAt | long | * | Now | Datetime of creation Unix time, milliseconds * Set automatically by the server |
EzIgnoreUser
Ignore User
Represents a user who is blocked from joining a specific guild. When a user is added to the ignore list, their join requests are automatically rejected, and they cannot join the guild even if the join policy is set to open. Used by guild masters to manage unwanted members.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128 chars | User ID |
EzLastGuildMasterActivity
Last Guild Master Activity
Tracks the last time any guild master performed an activity within the guild. This timestamp is used by the inactivity-based succession system: when the configured inactivityPeriodDays in the guild model elapses without any guild master activity, leadership can be automatically transferred to another member. Each guild has one activity record that is updated whenever a guild master performs a guild operation.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128 chars | User ID | ||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzGuildModel
Guild Model
A Guild Model is an entity that sets the maximum number of people who can join the guild and the permission settings for each position within the guild.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| defaultMaximumMemberCount | int | ✓ | 1 ~ 2147483646 | Default Maximum Member Count The initial maximum number of members allowed when a new guild is created. This value is used as the starting currentMaximumMemberCount for new guilds. Can be increased later up to the maximumMemberCount limit through guild operations or acquire actions. | ||
| maximumMemberCount | int | ✓ | 1 ~ 2147483646 | Maximum Member Count The absolute upper limit for the number of members a guild can have. The guild’s currentMaximumMemberCount cannot exceed this value. This serves as a hard cap to prevent guilds from growing beyond the intended size. | ||
| roles | List<EzRoleModel> | ✓ | 1 ~ 10 items | List of Role Models The list of role definitions available within guilds of this type. Must include at least the roles referenced by guildMasterRole and guildMemberDefaultRole. Each role defines a unique set of permissions via a policy document. Up to 10 roles can be defined. | ||
| rejoinCoolTimeMinutes | int | 0 | 0 ~ 2147483646 | Rejoin Cool Time (Minutes) The cooldown period in minutes before a user can rejoin a guild after leaving. Set to 0 to allow immediate rejoining. This prevents abuse patterns where users repeatedly join and leave guilds. |
EzRoleModel
Role Model
The role model defines the role within the guild and sets the permissions for each role.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Role Model name Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| policyDocument | string | ✓ | ~ 10240 chars | Policy Document A JSON-formatted policy document that defines the permissions for this role. Specifies which guild operations (such as accepting/rejecting join requests, expelling members, updating guild info, changing member roles) are allowed or denied for members assigned to this role. |
EzMember
Member
An entity that manages a list of guild members
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128 chars | User ID | ||
| roleName | string | ✓ | ~ 128 chars | Role Model name Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 512 chars | Guild Member Metadata Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers. | |||
| joinedAt | long | * | Now | Date and time of joining the guild Unix time, milliseconds |
EzVerifyActionResult
Verify Action execution result
EzConsumeActionResult
Consume Action execution result
EzAcquireActionResult
Acquire Action execution result
EzTransactionResult
Transaction execution results
Result of a transaction executed using the server-side automatic transaction execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of Acquire Action execution results |
Methods
getGuildModel
Get a specific guild type definition by name
Retrieves a single guild model by specifying its name. The returned information includes the member capacity, role definitions and their permissions, join policy settings, rejoin cooldown period, and inactive guild master succession settings. Use this to display the rules of a specific guild type — for example, showing “Max Members: 30, Join: Approval Required, Roles: Master / Officer / Member” on a guild creation or detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzGuildModel | Guild Model |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).GuildModel(
guildModelName: "guild-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->GuildModel(
"guild-0001" // guildModelName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FGuildModel> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listGuildModels
Get a list of guild type definitions
Retrieves all guild models registered in this namespace. A guild model defines the rules for a type of guild — maximum number of members, role permissions (e.g., “Officer can kick members”), join policy (open/approval required), rejoin cooldown, and how many guilds a player can belong to at once. It also defines what happens when the guild master is inactive for too long (automatic succession to the most senior member). Use this to show the player what types of guilds exist when they’re browsing or creating a guild.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGuildModel> | List of Guild Model |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.GuildModelsAsync(
).ToListAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.GuildModels(
);
List<EzGuildModel> items = new List<EzGuildModel>();
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;
}
} const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->GuildModels(
);
TArray<Gs2::UE5::Guild::Model::FEzGuildModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeGuildModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGuildModels(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeGuildModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGuildModels(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeGuildModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGuildModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
assume
Get permission to act on behalf of the guild
Obtains a guild access token that lets the player perform actions as the guild itself — such as updating guild settings, accepting join requests, or kicking members. The player must be a member of the guild, and the actions they can perform depend on their role permissions. This is a required first step before calling guild management APIs like UpdateGuild, AcceptRequest, RejectRequest, DeleteMemberFromGuild, etc. Think of it like “switching to guild management mode” — after calling this, use the returned token for subsequent guild operations.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildName | string | ✓ | UUID | ~ 36 chars | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
Result
| Type | Description | |
|---|---|---|
| token | string | access token |
| userId | string | User ID |
| expire | long | Expiration time A timestamp indicating the expiration time of the token. When this date is reached, the token becomes invalid. Unix time, milliseconds |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| NotIncludedGuildMemberException | NotFoundException | You are not a member of the guild. |
Implementation Example
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.
} 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;
} 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
Change multiple guild members’ roles at once
Updates the roles of multiple guild members in a single call — for example, promoting several members to “Officer” at the same time. This is called as the guild (use Assume first). Only members with the appropriate role permissions can perform this operation. Use this when the guild master wants to reorganize roles for many members at once, rather than changing them one by one.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| members | List<EzMember> | ✓ | 1 ~ 100 items | List of members to update |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild updated |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var result = await domain.BatchUpdateGuildMemberRoleAsync(
guildModelName: "guild-model-0001",
accessToken: null,
members: new List<Gs2.Unity.Gs2Guild.Model.EzMember> {
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(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
);
var future = domain.BatchUpdateGuildMemberRoleFuture(
guildModelName: "guild-model-0001",
accessToken: null,
members: new List<Gs2.Unity.Gs2Guild.Model.EzMember> {
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; const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
);
const auto Future = Domain->BatchUpdateGuildMemberRole(
"guild-model-0001", // guildModelName
nullptr, // accessToken
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Guild::Model::FEzMember>>>();
v->Add(
MakeShared<Gs2::UE5::Guild::Model::FEzMember>()
->WithUserId(TOptional<FString>("user-0002"))
->WithRoleName(TOptional<FString>("role-0001"))
);
v->Add(
MakeShared<Gs2::UE5::Guild::Model::FEzMember>()
->WithUserId(TOptional<FString>("user-0003"))
->WithRoleName(TOptional<FString>("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
Create a new guild
Creates a new guild with the player as the guild master (leader). You can set the guild’s display name, up to 5 custom attributes (e.g., play style, activity time, language), metadata, join policy (open / approval required), and custom role definitions. The player who creates the guild automatically becomes its first member with the guild master role. Use this for a “Create Guild” button or form where the player sets up their new guild’s name, rules, and settings.
Request
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| gameSession | GameSession | ✓ | GameSession | |||||||||
| displayName | string | ✓ | ~ 64 chars | Display Name A human-readable name for the guild shown to players in the UI. Unlike the guild name (which is a system-generated UUID), the display name is set by the guild creator and can be updated. Used for guild search results, member lists, and other player-facing displays. | ||||||||
| attribute1 | int | 0 ~ 2147483645 | Attribute 1 A numeric attribute for the guild that can be used for filtering and sorting in guild search. Up to 5 attributes are available for developers to define custom guild properties such as level, region, play style, or activity requirements. | |||||||||
| attribute2 | int | 0 ~ 2147483645 | Attribute 2 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute3 | int | 0 ~ 2147483645 | Attribute 3 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute4 | int | 0 ~ 2147483645 | Attribute 4 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute5 | int | 0 ~ 2147483645 | Attribute 5 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| metadata | string | ~ 1024 chars | Guild Metadata Arbitrary data associated with the guild that does not affect GS2 behavior. Can be used to store game-specific information such as guild emblems, descriptions, recruitment messages, or other custom data. | |||||||||
| memberMetadata | string | ~ 512 chars | Guild Member Metadata Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers. | |||||||||
| joinPolicy | ✓ | Join Policy Controls how users can join this guild. “anybody” allows any user to join immediately without approval. “approval” requires the guild master or authorized members to approve join requests before the user becomes a member. This can be changed by the guild master at any time.
| ||||||||||
| customRoles | List<EzRoleModel> | [] | 0 ~ 10 items | Custom Roles List A list of guild-specific custom role definitions that override or extend the model-level roles. Each guild can define up to 10 custom roles with unique permission sets. These roles can be assigned to members in addition to the model-level roles. | ||||||||
| guildMemberDefaultRole | string | ~ 128 chars | Default Custom Role The custom role automatically assigned to new members when they join this specific guild. If set, overrides the guild model’s guildMemberDefaultRole for this guild. Must reference a role defined in the customRoles list. |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild created |
Implementation Example
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(); 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; 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
Disband (delete) the guild
Permanently deletes the guild. All members are removed and the guild ceases to exist. This is called as the guild (use Assume first). Typically only the guild master has permission to disband the guild. Use this for a “Disband Guild” button in the guild settings screen. This is a destructive action — always show a confirmation dialog since it affects all guild members.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild deleted |
Implementation Example
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
); 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;
} 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
Kick a member from the guild
Removes the specified player from the guild’s member list. This is called as the guild (use Assume first). Only members with the appropriate role permissions (typically guild master or officers) can kick members. Use this for a “Kick” button on the member management screen. Consider showing a confirmation dialog since the action cannot be easily undone.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| targetUserId | string | ✓ | ~ 128 chars | User ID to be expelled |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild updated |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| GuildMasterRequiredException | BadRequestException | At least one member with guild master privileges is required. |
Implementation Example
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.
} 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;
} 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
Get a guild’s details
Retrieves the detailed information of a specific guild, including its display name, custom attributes, metadata, member list, and join policy. The information returned depends on the requesting player’s relationship to the guild — guild members can see full details including the member list, while non-members see only public information. Use this to display a guild detail screen — for example, “Dragon Knights — 25/30 members — Join: Approval Required”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildName | string | ✓ | UUID | ~ 36 chars | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
var item = await domain.ModelAsync(); 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; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FGuild> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listGuilds
Search for guilds to join
Searches for guilds that the player can join, with optional filters for display name, attributes, and join policy. You can filter by up to 5 custom attributes (e.g., play style, language, activity level) and by join policy (open / approval required). You can also choose whether to include guilds that are already full. Note: only guilds updated in the last 24 hours appear in search results. If a guild should stay visible, call UpdateGuild periodically even if nothing changed. Use this to build a “Find Guild” screen with search filters and a list of matching guilds.
Request
| Type | Condition | Required | Default | Value Limits | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||||||||||||||||||||||
| gameSession | GameSession | ✓ | GameSession | |||||||||||||||||||||||||||||
| displayName | string | ~ 64 chars | Display name to search for guild | |||||||||||||||||||||||||||||
| attributes1 | List<int> | 0 ~ 10 items | List of guild operation policies to search for guild | |||||||||||||||||||||||||||||
| attributes2 | List<int> | 0 ~ 10 items | List of guild operation policies to search for guild | |||||||||||||||||||||||||||||
| attributes3 | List<int> | 0 ~ 10 items | List of guild operation policies to search for guild | |||||||||||||||||||||||||||||
| attributes4 | List<int> | 0 ~ 10 items | List of guild operation policies to search for guild | |||||||||||||||||||||||||||||
| attributes5 | List<int> | 0 ~ 10 items | List of guild operation policies to search for guild | |||||||||||||||||||||||||||||
| joinPolicies | List<string> | 0 ~ 10 items | List of guild join policies to search for guild | |||||||||||||||||||||||||||||
| includeFullMembersGuild | bool | false | Whether to include full guilds in search results | |||||||||||||||||||||||||||||
| orderBy | “number_of_players” | Sort order
| ||||||||||||||||||||||||||||||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||||||||||||||||||||||||||||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGuild> | List of Guild |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SearchGuildsAsync(
guildModelName: "guild-model-0001"
).ToListAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.SearchGuilds(
guildModelName: "guild-model-0001"
);
List<EzGuild> items = new List<EzGuild>();
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;
}
} const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->SearchGuilds(
"guild-model-0001" // guildModelName
);
TArray<Gs2::UE5::Guild::Model::FEzGuildPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}updateGuild
Update the guild’s settings
Updates the guild’s display name, custom attributes, metadata, join policy, and role definitions. This is called as the guild — you need to use Assume first to get a guild access token, then call this API. Only members with the appropriate role permissions can update the guild settings. Also, calling this periodically keeps the guild visible in search results (guilds not updated for 24 hours are hidden from search). Use this for a “Guild Settings” screen where officers or the guild master can change the guild’s name, description, or recruitment policy.
Request
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||||||||
| displayName | string | ✓ | ~ 64 chars | Display Name A human-readable name for the guild shown to players in the UI. Unlike the guild name (which is a system-generated UUID), the display name is set by the guild creator and can be updated. Used for guild search results, member lists, and other player-facing displays. | ||||||||
| attribute1 | int | 0 ~ 2147483645 | Attribute 1 A numeric attribute for the guild that can be used for filtering and sorting in guild search. Up to 5 attributes are available for developers to define custom guild properties such as level, region, play style, or activity requirements. | |||||||||
| attribute2 | int | 0 ~ 2147483645 | Attribute 2 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute3 | int | 0 ~ 2147483645 | Attribute 3 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute4 | int | 0 ~ 2147483645 | Attribute 4 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| attribute5 | int | 0 ~ 2147483645 | Attribute 5 A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details. | |||||||||
| metadata | string | ~ 1024 chars | Guild Metadata Arbitrary data associated with the guild that does not affect GS2 behavior. Can be used to store game-specific information such as guild emblems, descriptions, recruitment messages, or other custom data. | |||||||||
| joinPolicy | ✓ | Join Policy Controls how users can join this guild. “anybody” allows any user to join immediately without approval. “approval” requires the guild master or authorized members to approve join requests before the user becomes a member. This can be changed by the guild master at any time.
| ||||||||||
| customRoles | List<EzRoleModel> | [] | 0 ~ 10 items | Custom Roles List A list of guild-specific custom role definitions that override or extend the model-level roles. Each guild can define up to 10 custom roles with unique permission sets. These roles can be assigned to members in addition to the model-level roles. | ||||||||
| guildMemberDefaultRole | string | ~ 128 chars | Default Custom Role The custom role automatically assigned to new members when they join this specific guild. If set, overrides the guild model’s guildMemberDefaultRole for this guild. Must reference a role defined in the customRoles list. |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild updated |
Implementation Example
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(); 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; 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
Change a guild member’s role
Changes the role of a specific guild member — for example, promoting a member to “Officer” or demoting an officer back to “Member”. This is called as the guild (use Assume first). Only members with the appropriate role permissions can change other members’ roles. Use this for a “Manage Members” screen where the guild master or officers can promote or demote members.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| targetUserId | string | ✓ | ~ 128 chars | User ID to be updated | ||
| roleName | string | ✓ | ~ 128 chars | Role Model name Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild updated |
Implementation Example
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(); 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; 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
Accept a player’s join request
Approves a pending join request, adding the requesting player to the guild’s member list. This is called as the guild (use Assume first). Only members with the appropriate role permissions can accept join requests. After acceptance, the player becomes a guild member with the default role defined in the guild model. Use this for an “Accept” button on the join request detail or list screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| fromUserId | string | ✓ | ~ 128 chars | User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveMemberRequest | Accepted join request |
| guild | EzGuild | Guild |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| MaximumJoinedGuildsReachedException | BadRequestException | The number of guilds you can join at the same time has reached the upper limit. |
| MaximumMembersReachedException | BadRequestException | The number of members has reached the upper limit. |
Implementation Example
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.
} 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;
} 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
Get the details of a specific join request
Retrieves the details of a specific join request received by the guild, identified by the sender’s user ID. This is called as the guild (use Assume first). Use this to show a join request detail screen — for example, displaying the applicant’s profile, their message, and “Accept” / “Reject” buttons.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| fromUserId | string | ✓ | ~ 128 chars | User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveMemberRequest | Join request |
Implementation Example
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(); 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; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
).ReceiveMemberRequest(
fromUserId: null
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-0001", // guildModelName
"guildName-0001", // guildName
"user-0001" // userId
)->ReceiveMemberRequest(
nullptr // fromUserId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FReceiveMemberRequest> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listReceiveRequests
Get a list of join requests received by the guild
Retrieves all pending join requests that players have sent to this guild. This is called as the guild (use Assume first to get a guild access token). Each request includes who sent it and any message or metadata they attached. Use this to build a “Join Requests” screen in the guild management panel — for example, showing a list like “PlayerA wants to join (Message: Level 50 healer, daily active)”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzReceiveMemberRequest> | List of join request |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
);
var items = await domain.ReceiveRequestsAsync(
).ToListAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-0001",
guildName: "guildName-0001",
userId: "user-0001"
);
var it = domain.ReceiveRequests(
);
List<EzReceiveMemberRequest> items = new List<EzReceiveMemberRequest>();
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;
}
} 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<Gs2::UE5::Guild::Model::FEzReceiveMemberRequestPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}rejectRequest
Reject a player’s join request
Denies a pending join request. The requesting player will not be added to the guild. This is called as the guild (use Assume first). Only members with the appropriate role permissions can reject join requests. The rejected player can send a new join request later unless they have been added to the guild’s block list (IgnoreUser). Use this for a “Reject” button on the join request detail or list screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| fromUserId | string | ✓ | ~ 128 chars | User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveMemberRequest | Rejected join request |
Implementation Example
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
); 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;
} 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
Cancel a join request the player sent
Cancels (withdraws) a pending join request that the player previously sent to a guild. After cancellation, the request is removed from both the player’s sent requests and the guild’s received requests. The player can send a new join request to the same guild after cancelling. Use this for a “Cancel Application” or “Withdraw Request” button on the pending request detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| targetGuildName | string | ✓ | ~ 128 chars | Target Guild Name The unique name (UUID) of the guild to which the join request was sent. This identifies the specific guild instance that the user is requesting to join, and is used to locate the guild’s inbox for request processing. |
Result
| Type | Description | |
|---|---|---|
| item | EzSendMemberRequest | Join request deleted |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.CancelRequestAsync(
guildModelName: "guild-0002",
targetGuildName: "guild-0002"
); 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;
} 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
Get the details of a join request the player sent
Retrieves the details of a specific join request that the player has sent to a guild. The returned information includes the target guild and the metadata (message) attached to the request. Use this to show the details of a pending application — for example, displaying “Applied to Dragon Knights — Message: Level 50 healer” with a “Cancel” button.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| targetGuildName | string | ✓ | ~ 128 chars | Target Guild Name The unique name (UUID) of the guild to which the join request was sent. This identifies the specific guild instance that the user is requesting to join, and is used to locate the guild’s inbox for request processing. |
Result
| Type | Description | |
|---|---|---|
| item | EzSendMemberRequest | Join Request |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
var item = await domain.ModelAsync(); 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; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SendMemberRequest(
guildModelName: "guild-0002",
guildName: null
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->SendMemberRequest(
"guild-0002", // guildModelName
nullptr // guildName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FSendMemberRequest> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listSendRequests
Get a list of join requests the player has sent
Retrieves all join requests that the player has sent to various guilds and are still pending. Each entry includes which guild the request was sent to and any metadata (message) attached to the request. Use this to build a “My Applications” or “Pending Requests” screen — for example, showing “Applied to Dragon Knights (pending), Applied to Star Alliance (pending)”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzSendMemberRequest> | List of join requests |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SendRequestsAsync(
guildModelName: "guild-0002"
).ToListAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.SendRequests(
guildModelName: "guild-0002"
);
List<EzSendMemberRequest> items = new List<EzSendMemberRequest>();
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;
}
} const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->SendRequests(
"guild-0002" // guildModelName
);
TArray<Gs2::UE5::Guild::Model::FEzSendMemberRequestPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}sendRequest
Send a join request to a guild
Sends a join request to the specified guild. If the guild’s join policy is “open”, the player joins immediately. If it’s “approval required”, the request goes to the guild’s inbox for review. You can attach metadata (such as a message like “Level 50 healer, looking for a raid group”) to the request. The request will be rejected automatically if the player is on the guild’s block list (IgnoreUser). Use this for a “Request to Join” or “Apply” button on the guild detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| targetGuildName | string | ✓ | ~ 128 chars | Destination Guild Name | ||
| metadata | string | ~ 512 chars | Guild Member Metadata Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers. |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Joined guild Responds when a join request is made to a guild that does not require approval |
| sendMemberRequest | EzSendMemberRequest | Sent Join Request Responds when a join request is made to a guild that requires approval |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| MaximumMembersReachedException | BadRequestException | The number of members has reached the upper limit. |
| MaximumJoinedGuildsReachedException | BadRequestException | The number of guilds you can join at the same time has reached the upper limit. |
| MaximumReceiveRequestsReachedException | BadRequestException | The number of requests to join the guild has reached the upper limit. |
| MaximumSendRequestsReachedException | BadRequestException | You have reached the maximum number of requests you can send. |
| DotMeetJoinRequirementsException | BadRequestException | You do not meet the requirements to join the guild. |
Implementation Example
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.
} 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; 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
Get details of a specific guild the player belongs to
Retrieves the membership details for a specific guild that the player has joined. The returned information includes the guild name, the player’s role, join date, and membership metadata. Use this to show the player’s membership info for a specific guild — for example, “Joined: 2024-01-15, Role: Officer, Note: Tank main”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildName | string | ✓ | UUID | ~ 36 chars | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
Result
| Type | Description | |
|---|---|---|
| item | EzJoinedGuild | Joining guild |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
var item = await domain.ModelAsync(); 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; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).JoinedGuild(
guildModelName: "guild-model-0001",
guildName: "guild-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->JoinedGuild(
"guild-model-0001", // guildModelName
"guild-0001" // guildName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FJoinedGuild> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listJoinedGuilds
Get a list of guilds the player belongs to
Retrieves all guilds that the player is currently a member of. You can optionally filter by guild model name — if omitted, guilds of all types are returned. Each entry includes the guild name, when the player joined, and their current role. Use this to build a “My Guilds” screen showing the player’s guild memberships — for example, “Dragon Knights (Officer), Star Alliance (Member)”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzJoinedGuild> | Joining guild |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.JoinedGuildsAsync(
guildModelName: "guild-model-0001"
).ToListAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.JoinedGuilds(
guildModelName: "guild-model-0001"
);
List<EzJoinedGuild> items = new List<EzJoinedGuild>();
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;
}
} const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->JoinedGuilds(
"guild-model-0001" // guildModelName
);
TArray<Gs2::UE5::Guild::Model::FEzJoinedGuildPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeJoinedGuilds(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeJoinedGuilds(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeJoinedGuilds(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeJoinedGuilds(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeJoinedGuilds(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeJoinedGuilds(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
updateMemberMetadata
Update your own member metadata in a guild
Updates the player’s own metadata within a guild. Metadata is free-form text that can store any member-specific information. For example, you can use it to store the player’s preferred role (“Healer”), a personal message (“Looking for raid partners”), or gameplay preferences. Only the player themselves can update their own metadata — other members cannot change it. Use this for a “Edit My Guild Profile” feature where members can set their in-guild status or notes.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildName | string | ✓ | UUID | ~ 36 chars | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. | |
| gameSession | GameSession | ✓ | GameSession | |||
| metadata | string | ~ 512 chars | Guild Member Metadata Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers. |
Result
| Type | Description | |
|---|---|---|
| item | EzGuild | Guild updated |
Implementation Example
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(); 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; 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
Leave a guild voluntarily
The player leaves a guild they are currently a member of. After withdrawing, the player is removed from the guild’s member list. Any player can leave a guild on their own — no approval from the guild master is needed. Note: if the guild model has a rejoin cooldown configured, the player won’t be able to rejoin the same guild until the cooldown period has passed. Use this for a “Leave Guild” button on the guild detail or settings screen. Consider showing a confirmation dialog since there may be a cooldown before rejoining.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildName | string | ✓ | UUID | ~ 36 chars | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
Result
| Type | Description | |
|---|---|---|
| item | EzJoinedGuild | Guild that withdrew |
| guild | EzGuild | Guild |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| GuildMasterRequiredException | BadRequestException | At least one member with guild master privileges is required. |
Implementation Example
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.
} 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; 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
Block a player from joining the guild
Adds a player to the guild’s block list. Once blocked, the player cannot send join requests to this guild — any future requests are automatically rejected. This is called as the guild (use Assume first). Only members with the appropriate role permissions can manage the block list. Use this for a “Block” button — for example, after kicking a troublesome member to prevent them from requesting to rejoin.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| userId | string | ✓ | ~ 128 chars | User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzIgnoreUser | User ID that refuse to participate |
| guild | EzGuild | Guild |
Implementation Example
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(); 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; 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
Unblock a player from the guild’s block list
Removes a player from the guild’s block list. After unblocking, the player can send join requests to this guild again. This is called as the guild (use Assume first). Only members with the appropriate role permissions can manage the block list. Use this for an “Unblock” button on the blocked players management screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| userId | string | ✓ | ~ 128 chars | User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzIgnoreUser | User ID that refuse to participate |
Implementation Example
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"
); 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;
} 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
Check if a specific player is on the guild’s block list
Checks whether a specific player is blocked from joining this guild. This is called as the guild (use Assume first). Use this to check a player’s block status before showing a “Block” or “Unblock” button — for example, on a member management or player profile screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| userId | string | ✓ | ~ 128 chars | User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzIgnoreUser | User ID that refuse to participate |
Implementation Example
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(); 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; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: "user-0001"
).IgnoreUser(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
"user-0001" // userId
)->IgnoreUser(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FIgnoreUser> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listIgnoreUsers
Get the guild’s block list
Retrieves the list of players that the guild has blocked from joining. This is called as the guild (use Assume first to get a guild access token). Blocked players cannot send join requests to this guild — their requests are automatically rejected. Use this to build a “Blocked Players” management screen in the guild settings — for example, showing a list of blocked players with “Unblock” buttons.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name | ||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzIgnoreUser> | List of User IDs that refuse to participate |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
var items = await domain.IgnoreUsersAsync(
).ToListAsync(); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
var it = domain.IgnoreUsers(
);
List<EzIgnoreUser> items = new List<EzIgnoreUser>();
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;
}
} 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<Gs2::UE5::Guild::Model::FEzIgnoreUserPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
// Start event handling
var callbackId = domain.SubscribeIgnoreUsers(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeIgnoreUsers(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
);
// Start event handling
var callbackId = domain.SubscribeIgnoreUsers(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeIgnoreUsers(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
);
// Start event handling
const auto CallbackId = Domain->SubscribeIgnoreUsers(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeIgnoreUsers(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getLastGuildMasterActivity
Check when the guild master was last active
Retrieves the date and time of the guild master’s most recent activity. This is called as the guild (use Assume first to get a guild access token). Use this to display the guild master’s activity status — for example, “Guild Master last active: 3 days ago”. This information is useful for determining whether the guild master has been inactive long enough to trigger automatic succession (PromoteSeniorMember).
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name |
Result
| Type | Description | |
|---|---|---|
| item | EzLastGuildMasterActivity | User ID that refuse to participate |
| guild | EzGuild | Guild |
Implementation Example
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
var item = await domain.ModelAsync(); 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; 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;
}Value change event handling
var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Guild.Namespace(
namespaceName: "namespace-0001"
).Guild(
guildModelName: "guild-model-0001",
guildName: "guild-0001",
userId: null
).LastGuildMasterActivity(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Guild->Namespace(
"namespace-0001" // namespaceName
)->Guild(
"guild-model-0001", // guildModelName
"guild-0001", // guildName
nullptr // userId
)->LastGuildMasterActivity(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Guild::Model::FLastGuildMasterActivity> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
promoteSeniorMember
Replace an inactive guild master with the most senior member
If the guild master has not been active for the period defined in the guild model’s inactivity settings, this promotes the longest-serving member to become the new guild master. This is called as the guild (use Assume first). The inactivity period threshold is configured in the guild model. This prevents guilds from becoming “stuck” when the guild master stops playing the game. Use this for a “Claim Leadership” button that appears when the guild master has been inactive — for example, showing “The guild master has been inactive for 30 days. As the most senior member, you can take over.”
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| guildModelName | string | ✓ | ~ 128 chars | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| accessToken | string | ✓ | ~ 128 chars | Guild name |
Result
| Type | Description | |
|---|---|---|
| item | EzLastGuildMasterActivity | User ID that refuse to participate |
| guild | EzGuild | Guild |
Implementation Example
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(); 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; 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();Event Handler
OnReceiveRequestNotification
Push notification used when a join request is received
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildModelName | string | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildName | string | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
| fromUserId | string | User ID |
Implementation Example
gs2.Guild.OnReceiveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
}; gs2.Guild.OnReceiveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
}; 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
Push notification used when a join request is deleted
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildModelName | string | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildName | string | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
| fromUserId | string | User ID |
Implementation Example
gs2.Guild.OnRemoveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
}; gs2.Guild.OnRemoveRequestNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var fromUserId = notification.FromUserId;
}; 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
Push notification issued when a guild information is updated
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildModelName | string | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildName | string | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
Implementation Example
gs2.Guild.OnChangeNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
}; gs2.Guild.OnChangeNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
}; Gs2->Guild->OnChangeNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GuildModelName = Notification->GuildModelNameValue;
const auto GuildName = Notification->GuildNameValue;
});OnJoinNotification
Push notification issued when a guild member is added
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildModelName | string | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildName | string | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
| joinedUserId | string | User ID |
Implementation Example
gs2.Guild.OnJoinNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var joinedUserId = notification.JoinedUserId;
}; gs2.Guild.OnJoinNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var joinedUserId = notification.JoinedUserId;
}; 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
Push notification issued when a guild member is removed
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildModelName | string | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildName | string | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
| leavedUserId | string | User ID |
Implementation Example
gs2.Guild.OnLeaveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var leavedUserId = notification.LeavedUserId;
}; gs2.Guild.OnLeaveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var leavedUserId = notification.LeavedUserId;
}; 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
Push notification issued when a guild member is updated
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildModelName | string | Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| guildName | string | Guild Name Maintains a unique name for each guild. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild. |
| changedUserId | string | User ID |
Implementation Example
gs2.Guild.OnChangeMemberNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var changedUserId = notification.ChangedUserId;
}; gs2.Guild.OnChangeMemberNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var guildModelName = notification.GuildModelName;
var guildName = notification.GuildName;
var changedUserId = notification.ChangedUserId;
}; 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;
});