GS2-Guild SDK for Game Engine API Reference

Specifications of models and API references for GS2-Guild SDK for Game Engine

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.

TypeConditionRequiredDefaultValue LimitsDescription
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
namestring
UUID~ 36 charsGuild 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.
displayNamestring
~ 64 charsDisplay 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.
attribute1int0 ~ 2147483645Attribute 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.
attribute2int0 ~ 2147483645Attribute 2
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute3int0 ~ 2147483645Attribute 3
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute4int0 ~ 2147483645Attribute 4
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute5int0 ~ 2147483645Attribute 5
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
metadatastring~ 1024 charsGuild 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.
joinPolicyString 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.
DefinitionDescription
“anybody”Anybody can join
“approval”Approval required
customRolesList<EzRoleModel>[]0 ~ 10 itemsCustom 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.
membersList<EzMember>[]0 ~ 100 itemsGuild 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.

TypeConditionRequiredDefaultValue LimitsDescription
userIdstring
~ 128 charsUser 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.
targetGuildNamestring
~ 128 charsTarget 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.

TypeConditionRequiredDefaultValue LimitsDescription
userIdstring
~ 128 charsUser 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.
targetGuildNamestring
~ 128 charsTarget 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.

TypeConditionRequiredDefaultValue LimitsDescription
guildModelNamestring
~ 128 charsGuild 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.
guildNamestring
~ 128 charsGuild Name
The unique name (UUID) of the guild that the user has joined. Used to identify the specific guild instance within the guild model.
userIdstring
~ 128 charsUser ID
createdAtlong
*
NowDatetime 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.

TypeConditionRequiredDefaultValue LimitsDescription
userIdstring
~ 128 charsUser 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.

TypeConditionRequiredDefaultValue LimitsDescription
userIdstring
~ 128 charsUser ID
updatedAtlong
*
NowDatetime 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.

TypeConditionRequiredDefaultValue LimitsDescription
namestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadatastring~ 2048 charsMetadata
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.
defaultMaximumMemberCountint
1 ~ 2147483646Default 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.
maximumMemberCountint
1 ~ 2147483646Maximum 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.
rolesList<EzRoleModel>
1 ~ 10 itemsList 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.
rejoinCoolTimeMinutesint00 ~ 2147483646Rejoin 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.

TypeConditionRequiredDefaultValue LimitsDescription
namestring
~ 128 charsRole Model name
Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadatastring~ 2048 charsMetadata
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.
policyDocumentstring
~ 10240 charsPolicy 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

TypeConditionRequiredDefaultValue LimitsDescription
userIdstring
~ 128 charsUser ID
roleNamestring
~ 128 charsRole Model name
Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadatastring~ 512 charsGuild 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.
joinedAtlong
*
NowDate and time of joining the guild
Unix time, milliseconds

EzVerifyActionResult

Verify Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2Dictionary:VerifyEntryByUserId",
"Gs2Distributor:IfExpressionByUserId",
"Gs2Distributor:AndExpressionByUserId",
"Gs2Distributor:OrExpressionByUserId",
"Gs2Enchant:VerifyRarityParameterStatusByUserId",
"Gs2Experience:VerifyRankByUserId",
"Gs2Experience:VerifyRankCapByUserId",
"Gs2Grade:VerifyGradeByUserId",
"Gs2Grade:VerifyGradeUpMaterialByUserId",
"Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
"Gs2Guild:VerifyIncludeMemberByUserId",
"Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
"Gs2Inventory:VerifyItemSetByUserId",
"Gs2Inventory:VerifyReferenceOfByUserId",
"Gs2Inventory:VerifySimpleItemByUserId",
"Gs2Inventory:VerifyBigItemByUserId",
"Gs2Limit:VerifyCounterByUserId",
"Gs2Matchmaking:VerifyIncludeParticipantByUserId",
"Gs2Mission:VerifyCompleteByUserId",
"Gs2Mission:VerifyCounterValueByUserId",
"Gs2Ranking2:VerifyGlobalRankingScoreByUserId",
"Gs2Ranking2:VerifyClusterRankingScoreByUserId",
"Gs2Ranking2:VerifySubscribeRankingScoreByUserId",
"Gs2Schedule:VerifyTriggerByUserId",
"Gs2Schedule:VerifyEventByUserId",
"Gs2SerialKey:VerifyCodeByUserId",
"Gs2Stamina:VerifyStaminaValueByUserId",
"Gs2Stamina:VerifyStaminaMaxValueByUserId",
"Gs2Stamina:VerifyStaminaRecoverIntervalMinutesByUserId",
"Gs2Stamina:VerifyStaminaRecoverValueByUserId",
"Gs2Stamina:VerifyStaminaOverflowValueByUserId",
}
Type of action to be executed in the Verify Action
verifyRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
verifyResultstring~ 1048576 charsResult payload

EzConsumeActionResult

Consume Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:ConsumePointByUserId",
"Gs2Dictionary:DeleteEntriesByUserId",
"Gs2Enhance:DeleteProgressByUserId",
"Gs2Exchange:DeleteAwaitByUserId",
"Gs2Experience:SubExperienceByUserId",
"Gs2Experience:SubRankCapByUserId",
"Gs2Formation:SubMoldCapacityByUserId",
"Gs2Grade:SubGradeByUserId",
"Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
"Gs2Inbox:OpenMessageByUserId",
"Gs2Inbox:DeleteMessageByUserId",
"Gs2Inventory:ConsumeItemSetByUserId",
"Gs2Inventory:ConsumeSimpleItemsByUserId",
"Gs2Inventory:ConsumeBigItemByUserId",
"Gs2JobQueue:DeleteJobByUserId",
"Gs2Limit:CountUpByUserId",
"Gs2LoginReward:MarkReceivedByUserId",
"Gs2Mission:ReceiveByUserId",
"Gs2Mission:BatchReceiveByUserId",
"Gs2Mission:DecreaseCounterByUserId",
"Gs2Mission:ResetCounterByUserId",
"Gs2Money:WithdrawByUserId",
"Gs2Money:RecordReceipt",
"Gs2Money2:WithdrawByUserId",
"Gs2Money2:VerifyReceiptByUserId",
"Gs2Quest:DeleteProgressByUserId",
"Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId",
"Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId",
"Gs2Schedule:DeleteTriggerByUserId",
"Gs2SerialKey:UseByUserId",
"Gs2Showcase:IncrementPurchaseCountByUserId",
"Gs2SkillTree:MarkRestrainByUserId",
"Gs2Stamina:DecreaseMaxValueByUserId",
"Gs2Stamina:ConsumeStaminaByUserId",
}
Type of action to be executed in the Consume Action
consumeRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
consumeResultstring~ 1048576 charsResult payload

EzAcquireActionResult

Acquire Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:AcquirePointByUserId",
"Gs2Dictionary:AddEntriesByUserId",
"Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
"Gs2Enchant:SetBalanceParameterStatusByUserId",
"Gs2Enchant:ReDrawRarityParameterStatusByUserId",
"Gs2Enchant:AddRarityParameterStatusByUserId",
"Gs2Enchant:SetRarityParameterStatusByUserId",
"Gs2Enhance:DirectEnhanceByUserId",
"Gs2Enhance:UnleashByUserId",
"Gs2Enhance:CreateProgressByUserId",
"Gs2Exchange:ExchangeByUserId",
"Gs2Exchange:IncrementalExchangeByUserId",
"Gs2Exchange:CreateAwaitByUserId",
"Gs2Exchange:AcquireForceByUserId",
"Gs2Exchange:SkipByUserId",
"Gs2Experience:AddExperienceByUserId",
"Gs2Experience:SetExperienceByUserId",
"Gs2Experience:AddRankCapByUserId",
"Gs2Experience:SetRankCapByUserId",
"Gs2Experience:MultiplyAcquireActionsByUserId",
"Gs2Formation:AddMoldCapacityByUserId",
"Gs2Formation:SetMoldCapacityByUserId",
"Gs2Formation:AcquireActionsToFormProperties",
"Gs2Formation:SetFormByUserId",
"Gs2Formation:AcquireActionsToPropertyFormProperties",
"Gs2Friend:UpdateProfileByUserId",
"Gs2Grade:AddGradeByUserId",
"Gs2Grade:ApplyRankCapByUserId",
"Gs2Grade:MultiplyAcquireActionsByUserId",
"Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
"Gs2Idle:SetMaximumIdleMinutesByUserId",
"Gs2Idle:ReceiveByUserId",
"Gs2Inbox:SendMessageByUserId",
"Gs2Inventory:AddCapacityByUserId",
"Gs2Inventory:SetCapacityByUserId",
"Gs2Inventory:AcquireItemSetByUserId",
"Gs2Inventory:AcquireItemSetWithGradeByUserId",
"Gs2Inventory:AddReferenceOfByUserId",
"Gs2Inventory:DeleteReferenceOfByUserId",
"Gs2Inventory:AcquireSimpleItemsByUserId",
"Gs2Inventory:SetSimpleItemsByUserId",
"Gs2Inventory:AcquireBigItemByUserId",
"Gs2Inventory:SetBigItemByUserId",
"Gs2JobQueue:PushByUserId",
"Gs2Limit:CountDownByUserId",
"Gs2Limit:DeleteCounterByUserId",
"Gs2LoginReward:DeleteReceiveStatusByUserId",
"Gs2LoginReward:UnmarkReceivedByUserId",
"Gs2Lottery:DrawByUserId",
"Gs2Lottery:ResetBoxByUserId",
"Gs2Mission:RevertReceiveByUserId",
"Gs2Mission:IncreaseCounterByUserId",
"Gs2Mission:SetCounterByUserId",
"Gs2Money:DepositByUserId",
"Gs2Money:RevertRecordReceipt",
"Gs2Money2:DepositByUserId",
"Gs2Quest:CreateProgressByUserId",
"Gs2Schedule:TriggerByUserId",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
Type of action to be executed in the Acquire Action
acquireRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
acquireResultstring~ 1048576 charsResult payload

EzTransactionResult

Transaction execution results

Result of a transaction executed using the server-side automatic transaction execution feature

TypeConditionRequiredDefaultValue LimitsDescription
transactionIdstring
36 ~ 36 charsTransaction ID
verifyResultsList<EzVerifyActionResult>0 ~ 10 itemsList of verify action execution results
consumeResultsList<EzConsumeActionResult>[]0 ~ 10 itemsList of Consume Action execution results
acquireResultsList<EzAcquireActionResult>[]0 ~ 100 itemsList 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

TypeDescription
itemEzGuildModelGuild 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

TypeDescription
itemsList<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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildNamestring
UUID~ 36 charsGuild 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

TypeDescription
tokenstringaccess token
userIdstringUser ID
expirelongExpiration 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.

TypeBase TypeDescription
NotIncludedGuildMemberExceptionNotFoundExceptionYou 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
membersList<EzMember>
1 ~ 100 itemsList of members to update

Result

TypeDescription
itemEzGuildGuild 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
displayNamestring
~ 64 charsDisplay 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.
attribute1int0 ~ 2147483645Attribute 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.
attribute2int0 ~ 2147483645Attribute 2
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute3int0 ~ 2147483645Attribute 3
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute4int0 ~ 2147483645Attribute 4
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute5int0 ~ 2147483645Attribute 5
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
metadatastring~ 1024 charsGuild 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.
memberMetadatastring~ 512 charsGuild 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.
DefinitionDescription
“anybody”Anybody can join
“approval”Approval required
customRolesList<EzRoleModel>[]0 ~ 10 itemsCustom 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.
guildMemberDefaultRolestring~ 128 charsDefault 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

TypeDescription
itemEzGuildGuild 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name

Result

TypeDescription
itemEzGuildGuild 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
targetUserIdstring
~ 128 charsUser ID to be expelled

Result

TypeDescription
itemEzGuildGuild 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.

TypeBase TypeDescription
GuildMasterRequiredExceptionBadRequestExceptionAt 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildNamestring
UUID~ 36 charsGuild 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

TypeDescription
itemEzGuildGuild

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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
displayNamestring~ 64 charsDisplay name to search for guild
attributes1List<int>0 ~ 10 itemsList of guild operation policies to search for guild
attributes2List<int>0 ~ 10 itemsList of guild operation policies to search for guild
attributes3List<int>0 ~ 10 itemsList of guild operation policies to search for guild
attributes4List<int>0 ~ 10 itemsList of guild operation policies to search for guild
attributes5List<int>0 ~ 10 itemsList of guild operation policies to search for guild
joinPoliciesList<string>0 ~ 10 itemsList of guild join policies to search for guild
includeFullMembersGuildboolfalseWhether to include full guilds in search results
orderBy“number_of_players”Sort order
DefinitionDescription
“number_of_players”Number of players joined
“attribute1_asc”Attribute1 ascending
“attribute1_desc”Attribute1 descending
“attribute2_asc”Attribute2 ascending
“attribute2_desc”Attribute2 descending
“attribute3_asc”Attribute3 ascending
“attribute3_desc”Attribute3 descending
“attribute4_asc”Attribute4 ascending
“attribute4_desc”Attribute4 descending
“attribute5_asc”Attribute5 ascending
“attribute5_desc”Attribute5 descending
“last_updated”Last updated
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data items to retrieve

Result

TypeDescription
itemsList<EzGuild>List of Guild
nextPageTokenstringPage 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
displayNamestring
~ 64 charsDisplay 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.
attribute1int0 ~ 2147483645Attribute 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.
attribute2int0 ~ 2147483645Attribute 2
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute3int0 ~ 2147483645Attribute 3
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute4int0 ~ 2147483645Attribute 4
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute5int0 ~ 2147483645Attribute 5
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
metadatastring~ 1024 charsGuild 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.
DefinitionDescription
“anybody”Anybody can join
“approval”Approval required
customRolesList<EzRoleModel>[]0 ~ 10 itemsCustom 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.
guildMemberDefaultRolestring~ 128 charsDefault 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

TypeDescription
itemEzGuildGuild 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
targetUserIdstring
~ 128 charsUser ID to be updated
roleNamestring
~ 128 charsRole Model name
Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

TypeDescription
itemEzGuildGuild 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
fromUserIdstring
~ 128 charsUser ID

Result

TypeDescription
itemEzReceiveMemberRequestAccepted join request
guildEzGuildGuild

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.

TypeBase TypeDescription
MaximumJoinedGuildsReachedExceptionBadRequestExceptionThe number of guilds you can join at the same time has reached the upper limit.
MaximumMembersReachedExceptionBadRequestExceptionThe 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
fromUserIdstring
~ 128 charsUser ID

Result

TypeDescription
itemEzReceiveMemberRequestJoin 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data items to retrieve

Result

TypeDescription
itemsList<EzReceiveMemberRequest>List of join request
nextPageTokenstringPage 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
fromUserIdstring
~ 128 charsUser ID

Result

TypeDescription
itemEzReceiveMemberRequestRejected 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
targetGuildNamestring
~ 128 charsTarget 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

TypeDescription
itemEzSendMemberRequestJoin 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
targetGuildNamestring
~ 128 charsTarget 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

TypeDescription
itemEzSendMemberRequestJoin 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data items to retrieve

Result

TypeDescription
itemsList<EzSendMemberRequest>List of join requests
nextPageTokenstringPage 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
targetGuildNamestring
~ 128 charsDestination Guild Name
metadatastring~ 512 charsGuild 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

TypeDescription
itemEzGuildJoined guild
Responds when a join request is made to a guild that does not require approval
sendMemberRequestEzSendMemberRequestSent 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.

TypeBase TypeDescription
MaximumMembersReachedExceptionBadRequestExceptionThe number of members has reached the upper limit.
MaximumJoinedGuildsReachedExceptionBadRequestExceptionThe number of guilds you can join at the same time has reached the upper limit.
MaximumReceiveRequestsReachedExceptionBadRequestExceptionThe number of requests to join the guild has reached the upper limit.
MaximumSendRequestsReachedExceptionBadRequestExceptionYou have reached the maximum number of requests you can send.
DotMeetJoinRequirementsExceptionBadRequestExceptionYou 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestring
UUID~ 36 charsGuild 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

TypeDescription
itemEzJoinedGuildJoining 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data items to retrieve

Result

TypeDescription
itemsList<EzJoinedGuild>Joining guild
nextPageTokenstringPage 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestring
UUID~ 36 charsGuild 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.
gameSessionGameSession
GameSession
metadatastring~ 512 charsGuild 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

TypeDescription
itemEzGuildGuild 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestring
UUID~ 36 charsGuild 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

TypeDescription
itemEzJoinedGuildGuild that withdrew
guildEzGuildGuild

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.

TypeBase TypeDescription
GuildMasterRequiredExceptionBadRequestExceptionAt 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
userIdstring
~ 128 charsUser ID

Result

TypeDescription
itemEzIgnoreUserUser ID that refuse to participate
guildEzGuildGuild

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
userIdstring
~ 128 charsUser ID

Result

TypeDescription
itemEzIgnoreUserUser 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
userIdstring
~ 128 charsUser ID

Result

TypeDescription
itemEzIgnoreUserUser 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data items to retrieve

Result

TypeDescription
itemsList<EzIgnoreUser>List of User IDs that refuse to participate
nextPageTokenstringPage 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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name

Result

TypeDescription
itemEzLastGuildMasterActivityUser ID that refuse to participate
guildEzGuildGuild

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);

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestring
~ 128 charsGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessTokenstring
~ 128 charsGuild name

Result

TypeDescription
itemEzLastGuildMasterActivityUser ID that refuse to participate
guildEzGuildGuild

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

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestringGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestringGuild 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.
fromUserIdstringUser 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

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestringGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestringGuild 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.
fromUserIdstringUser 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

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestringGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestringGuild 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

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestringGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestringGuild 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.
joinedUserIdstringUser 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

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestringGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestringGuild 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.
leavedUserIdstringUser 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

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelNamestringGuild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildNamestringGuild 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.
changedUserIdstringUser 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;
    });