GS2-Guild SDK for Game Engine API Reference

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

Models

EzGuild

Guild

A guild can have up to 5 attributes, which can be used when searching for guilds and displaying guild lists.

A guild can set a participation policy, allowing for either open participation or approval-based participation. If open participation is selected, a user who requests to join the guild will immediately become a guild member. If approval-based participation is selected, a user who requests to join the guild will not become a guild member until approved by the guild master or a guild member.

Guild members can be assigned roles, including guild master, guild member, and up to 10 custom roles defined by the guild. A default role can be assigned to guild members when they join the guild.

Type Condition Required Default Value Limits Description
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
name string
UUID ~ 36 chars Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
displayName string
~ 64 chars Display Name
A human-readable name for the guild shown to players in the UI. Unlike the guild name (which is a system-generated UUID), the display name is set by the guild creator and can be updated. Used for guild search results, member lists, and other player-facing displays.
attribute1 int 0 ~ 2147483645 Attribute 1
A numeric attribute for the guild that can be used for filtering and sorting in guild search. Up to 5 attributes are available for developers to define custom guild properties such as level, region, play style, or activity requirements.
attribute2 int 0 ~ 2147483645 Attribute 2
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute3 int 0 ~ 2147483645 Attribute 3
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute4 int 0 ~ 2147483645 Attribute 4
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute5 int 0 ~ 2147483645 Attribute 5
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
metadata string ~ 1024 chars Guild Metadata
Arbitrary data associated with the guild that does not affect GS2 behavior. Can be used to store game-specific information such as guild emblems, descriptions, recruitment messages, or other custom data.
joinPolicy string (enum)
enum {
  “anybody”,
  “approval”
}
Join Policy
Controls how users can join this guild. “anybody” allows any user to join immediately without approval. “approval” requires the guild master or authorized members to approve join requests before the user becomes a member. This can be changed by the guild master at any time.
DefinitionDescription
“anybody”Anybody can join
“approval”Approval required
customRoles List<EzRoleModel> [] 0 ~ 10 items Custom Roles List
A list of guild-specific custom role definitions that override or extend the model-level roles. Each guild can define up to 10 custom roles with unique permission sets. These roles can be assigned to members in addition to the model-level roles.
members List<EzMember> [] 0 ~ 100 items Guild Member List
The list of all current members of this guild, including guild masters and regular members. Each entry contains the member’s user ID, assigned role, metadata, and join timestamp. The number of members cannot exceed currentMaximumMemberCount.

EzReceiveMemberRequest

Received Join Request

This entity represents a received guild join request that is awaiting approval. This is a participation request accepted by the relevant guild. Once the relevant guild approves it, the participation request is deleted and the member is added to the member list.

Type Condition Required Default Value Limits Description
userId string
~ 128 chars User ID
The GS2 user ID of the player who sent this join request to the guild. This identifies the applicant and is used to add them to the guild’s member list upon approval, or to notify them upon rejection.
targetGuildName string
~ 128 chars Target Guild Name
The unique name (UUID) of the guild that received this join request. This identifies the specific guild instance whose inbox contains this pending request, and is used to match the request with the guild’s member management operations.

EzSendMemberRequest

Sent Join Request

This entity represents the state of a member registration application in progress. This entity represents a guild join request sent by the user. When the recipient user approves it, the join request is deleted and the user is added to the member list.

Type Condition Required Default Value Limits Description
userId string
~ 128 chars User ID
The GS2 user ID of the player who sent this guild join request. This identifies the requesting user and is used to add them to the guild’s member list upon approval.
targetGuildName string
~ 128 chars Target Guild Name
The unique name (UUID) of the guild to which the join request was sent. This identifies the specific guild instance that the user is requesting to join, and is used to locate the guild’s inbox for request processing.

EzJoinedGuild

Joined Guild

Represents a user’s membership in a specific guild. Created when a user joins a guild (either directly or through approved request) and deleted when the user leaves or is expelled. Used to track which guilds a user currently belongs to, enabling enforcement of the maxConcurrentJoinGuilds limit.

Type Condition Required Default Value Limits Description
guildModelName string
~ 128 chars Guild Model Name
The name of the guild model that the joined guild belongs to. References the guild model definition which contains membership limits, role configurations, and other guild type settings.
guildName string
~ 128 chars Guild Name
The unique name (UUID) of the guild that the user has joined. Used to identify the specific guild instance within the guild model.
userId string
~ 128 chars User ID
createdAt long
*
Current time Creation Timestamp
Unix time, milliseconds
* Set automatically by the server

EzIgnoreUser

Ignore User

Represents a user who is blocked from joining a specific guild. When a user is added to the ignore list, their join requests are automatically rejected, and they cannot join the guild even if the join policy is set to open. Used by guild masters to manage unwanted members.

Type Condition Required Default Value Limits Description
userId string
~ 128 chars User ID

EzLastGuildMasterActivity

Last Guild Master Activity

Tracks the last time any guild master performed an activity within the guild. This timestamp is used by the inactivity-based succession system: when the configured inactivityPeriodDays in the guild model elapses without any guild master activity, leadership can be automatically transferred to another member. Each guild has one activity record that is updated whenever a guild master performs a guild operation.

Type Condition Required Default Value Limits Description
userId string
~ 128 chars User ID
updatedAt long
*
Current time Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server

EzGuildModel

Guild Model

A Guild Model is an entity that sets the maximum number of people who can join the guild and the permission settings for each position within the guild.

Type Condition Required Default Value Limits Description
name string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadata string ~ 2048 chars Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game.
defaultMaximumMemberCount int
1 ~ 2147483646 Default Maximum Member Count
The initial maximum number of members allowed when a new guild is created. This value is used as the starting currentMaximumMemberCount for new guilds. Can be increased later up to the maximumMemberCount limit through guild operations or acquire actions.
maximumMemberCount int
1 ~ 2147483646 Maximum Member Count
The absolute upper limit for the number of members a guild can have. The guild’s currentMaximumMemberCount cannot exceed this value. This serves as a hard cap to prevent guilds from growing beyond the intended size.
roles List<EzRoleModel>
1 ~ 10 items List of Role Models
The list of role definitions available within guilds of this type. Must include at least the roles referenced by guildMasterRole and guildMemberDefaultRole. Each role defines a unique set of permissions via a policy document. Up to 10 roles can be defined.
rejoinCoolTimeMinutes int 0 0 ~ 2147483646 Rejoin Cool Time (Minutes)
The cooldown period in minutes before a user can rejoin a guild after leaving. Set to 0 to allow immediate rejoining. This prevents abuse patterns where users repeatedly join and leave guilds.

EzRoleModel

Role Model

The role model defines the role within the guild and sets the permissions for each role.

Type Condition Required Default Value Limits Description
name string
~ 128 chars Role Model name
Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadata string ~ 2048 chars Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game.
policyDocument string
~ 10240 chars Policy Document
A JSON-formatted policy document that defines the permissions for this role. Specifies which guild operations (such as accepting/rejecting join requests, expelling members, updating guild info, changing member roles) are allowed or denied for members assigned to this role.

EzMember

Member

An entity that manages a list of guild members

Type Condition Required Default Value Limits Description
userId string
~ 128 chars User ID
roleName string
~ 128 chars Role Model name
Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadata string ~ 512 chars Guild Member Metadata
Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers.
joinedAt long
*
Current time Date and time of joining the guild
Unix time, milliseconds

EzVerifyActionResult

Verify Action execution result

Type Condition Required Default Value Limits Description
action string (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 Verify Action
verifyRequest string
~ 524288 chars JSON string of the request used when executing the action
statusCode int 0 ~ 999 Status code
verifyResult string ~ 1048576 chars Result content

EzConsumeActionResult

Consume Action execution result

Type Condition Required Default Value Limits Description
action string (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 Consume Action
consumeRequest string
~ 524288 chars JSON string of the request used when executing the action
statusCode int 0 ~ 999 Status code
consumeResult string ~ 1048576 chars Result content

EzAcquireActionResult

Acquire Action execution result

Type Condition Required Default Value Limits Description
action string (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 Acquire Action
acquireRequest string
~ 524288 chars JSON string of the request used when executing the action
statusCode int 0 ~ 999 Status code
acquireResult string ~ 1048576 chars Result content

EzTransactionResult

Transaction execution result

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

Type Condition Required Default Value Limits Description
transactionId string
36 ~ 36 chars Transaction ID
verifyResults List<EzVerifyActionResult> 0 ~ 10 items List of verify action execution results
consumeResults List<EzConsumeActionResult> [] 0 ~ 10 items List of Consume Action execution results
acquireResults List<EzAcquireActionResult> [] 0 ~ 100 items List of Acquire Action execution results

Methods

getGuildModel

Get a specific guild type definition by name

Retrieves a single guild model by specifying its name. The returned information includes the member capacity, role definitions and their permissions, join policy settings, rejoin cooldown period, and inactive guild master succession settings. Use this to display the rules of a specific guild type — for example, showing “Max Members: 30, Join: Approval Required, Roles: Master / Officer / Member” on a guild creation or detail screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

Type Description
item EzGuildModel Guild Model

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).GuildModel(
        guildModelName: "guild-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).GuildModel(
        guildModelName: "guild-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->GuildModel(
        "guild-0001" // guildModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).GuildModel(
        guildModelName: "guild-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).GuildModel(
        guildModelName: "guild-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->GuildModel(
        "guild-0001" // guildModelName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FGuildModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listGuildModels

Get a list of guild type definitions

Retrieves all guild models registered in this namespace. A guild model defines the rules for a type of guild — maximum number of members, role permissions (e.g., “Officer can kick members”), join policy (open/approval required), rejoin cooldown, and how many guilds a player can belong to at once. It also defines what happens when the guild master is inactive for too long (automatic succession to the most senior member). Use this to show the player what types of guilds exist when they’re browsing or creating a guild.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

Type Description
items List<EzGuildModel> List of Guild Model

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.GuildModelsAsync(
    ).ToListAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.GuildModels(
    );
    List<EzGuildModel> items = new List<EzGuildModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->GuildModels(
    );
    TArray<Gs2::UE5::Guild::Model::FEzGuildModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeGuildModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeGuildModels(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeGuildModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeGuildModels(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeGuildModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeGuildModels(CallbackId);

assume

Get permission to act on behalf of the guild

Obtains a guild access token that lets the player perform actions as the guild itself — such as updating guild settings, accepting join requests, or kicking members. The player must be a member of the guild, and the actions they can perform depend on their role permissions. This is a required first step before calling guild management APIs like UpdateGuild, AcceptRequest, RejectRequest, DeleteMemberFromGuild, etc. Think of it like “switching to guild management mode” — after calling this, use the returned token for subsequent guild operations.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildName string
UUID ~ 36 chars Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.

Result

Type Description
token string access token
userId string User ID
expire long Expiration time
A timestamp indicating the expiration time of the token. When this date is reached, the token becomes invalid.
Unix time, milliseconds

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type Base Type Description
NotIncludedGuildMemberException NotFoundException You are not a member of the guild.

Implementation Example

try {
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.AssumeAsync(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
} catch(Gs2.Gs2Guild.Exception.NotIncludedGuildMemberException e) {
    // You are not a member of the guild.
}
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.AssumeFuture(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Guild.Exception.NotIncludedGuildMemberException)
        {
            // You are not a member of the guild.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->Assume(
        "guild-model-0001", // guildModelName
        "guild-0001" // guildName
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Guild::Error::FNotIncludedGuildMemberError::Class))
        {
            // You are not a member of the guild.
        }
        return false;
    }
    const auto Result = Future->GetTask().Result();

batchUpdateGuildMemberRole

Change multiple guild members’ roles at once

Updates the roles of multiple guild members in a single call — for example, promoting several members to “Officer” at the same time. This is called as the guild (use Assume first). Only members with the appropriate role permissions can perform this operation. Use this when the guild master wants to reorganize roles for many members at once, rather than changing them one by one.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
members List<EzMember>
1 ~ 100 items List of members to update

Result

Type Description
item EzGuild Guild updated

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.BatchUpdateGuildMemberRoleAsync(
        guildModelName: "guild-model-0001",
        accessToken: null,
        members: new List<Gs2.Unity.Gs2Guild.Model.EzMember> {
            new Gs2.Unity.Gs2Guild.Model.EzMember() {
                UserId = "user-0002",
                RoleName = "role-0001",
            },
            new Gs2.Unity.Gs2Guild.Model.EzMember() {
                UserId = "user-0003",
                RoleName = "role-0002",
            },
        }
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.BatchUpdateGuildMemberRoleFuture(
        guildModelName: "guild-model-0001",
        accessToken: null,
        members: new List<Gs2.Unity.Gs2Guild.Model.EzMember> {
            new Gs2.Unity.Gs2Guild.Model.EzMember() {
                UserId = "user-0002",
                RoleName = "role-0001",
            },
            new Gs2.Unity.Gs2Guild.Model.EzMember() {
                UserId = "user-0003",
                RoleName = "role-0002",
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->BatchUpdateGuildMemberRole(
        "guild-model-0001", // guildModelName
        nullptr, // accessToken
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Guild::Model::FEzMember>>>();
            v->Add(
                MakeShared<Gs2::UE5::Guild::Model::FEzMember>()
                ->WithUserId(TOptional<FString>("user-0002"))
                ->WithRoleName(TOptional<FString>("role-0001"))
            );
            v->Add(
                MakeShared<Gs2::UE5::Guild::Model::FEzMember>()
                ->WithUserId(TOptional<FString>("user-0003"))
                ->WithRoleName(TOptional<FString>("role-0002"))
            );
            return v;
        }() // members
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

createGuild

Create a new guild

Creates a new guild with the player as the guild master (leader). You can set the guild’s display name, up to 5 custom attributes (e.g., play style, activity time, language), metadata, join policy (open / approval required), and custom role definitions. The player who creates the guild automatically becomes its first member with the guild master role. Use this for a “Create Guild” button or form where the player sets up their new guild’s name, rules, and settings.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
displayName string
~ 64 chars Display Name
A human-readable name for the guild shown to players in the UI. Unlike the guild name (which is a system-generated UUID), the display name is set by the guild creator and can be updated. Used for guild search results, member lists, and other player-facing displays.
attribute1 int 0 ~ 2147483645 Attribute 1
A numeric attribute for the guild that can be used for filtering and sorting in guild search. Up to 5 attributes are available for developers to define custom guild properties such as level, region, play style, or activity requirements.
attribute2 int 0 ~ 2147483645 Attribute 2
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute3 int 0 ~ 2147483645 Attribute 3
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute4 int 0 ~ 2147483645 Attribute 4
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute5 int 0 ~ 2147483645 Attribute 5
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
metadata string ~ 1024 chars Guild Metadata
Arbitrary data associated with the guild that does not affect GS2 behavior. Can be used to store game-specific information such as guild emblems, descriptions, recruitment messages, or other custom data.
memberMetadata string ~ 512 chars Guild Member Metadata
Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers.
joinPolicy
Join Policy
Controls how users can join this guild. “anybody” allows any user to join immediately without approval. “approval” requires the guild master or authorized members to approve join requests before the user becomes a member. This can be changed by the guild master at any time.
DefinitionDescription
“anybody”Anybody can join
“approval”Approval required
customRoles List<EzRoleModel> [] 0 ~ 10 items Custom Roles List
A list of guild-specific custom role definitions that override or extend the model-level roles. Each guild can define up to 10 custom roles with unique permission sets. These roles can be assigned to members in addition to the model-level roles.
guildMemberDefaultRole string ~ 128 chars Default Custom Role
The custom role automatically assigned to new members when they join this specific guild. If set, overrides the guild model’s guildMemberDefaultRole for this guild. Must reference a role defined in the customRoles list.

Result

Type Description
item EzGuild Guild created

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.CreateGuildAsync(
        guildModelName: "guild-model-0001",
        displayName: "My Guild",
        joinPolicy: "anybody",
        attribute1: 1,
        attribute2: null,
        attribute3: null,
        attribute4: null,
        attribute5: null,
        metadata: null,
        memberMetadata: null,
        customRoles: null,
        guildMemberDefaultRole: null
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.CreateGuildFuture(
        guildModelName: "guild-model-0001",
        displayName: "My Guild",
        joinPolicy: "anybody",
        attribute1: 1,
        attribute2: null,
        attribute3: null,
        attribute4: null,
        attribute5: null,
        metadata: null,
        memberMetadata: null,
        customRoles: null,
        guildMemberDefaultRole: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->CreateGuild(
        "guild-model-0001", // guildModelName
        "My Guild", // displayName
        "anybody", // joinPolicy
        1 // attribute1
        // attribute2
        // attribute3
        // attribute4
        // attribute5
        // metadata
        // memberMetadata
        // customRoles
        // guildMemberDefaultRole
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

deleteGuild

Disband (delete) the guild

Permanently deletes the guild. All members are removed and the guild ceases to exist. This is called as the guild (use Assume first). Typically only the guild master has permission to disband the guild. Use this for a “Disband Guild” button in the guild settings screen. This is a destructive action — always show a confirmation dialog since it affects all guild members.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name

Result

Type Description
item EzGuild Guild deleted

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var result = await domain.DeleteGuildAsync(
        accessToken: null
    );
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var future = domain.DeleteGuildFuture(
        accessToken: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    const auto Future = Domain->DeleteGuild(
        nullptr // accessToken
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

deleteMemberFromGuild

Kick a member from the guild

Removes the specified player from the guild’s member list. This is called as the guild (use Assume first). Only members with the appropriate role permissions (typically guild master or officers) can kick members. Use this for a “Kick” button on the member management screen. Consider showing a confirmation dialog since the action cannot be easily undone.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
targetUserId string
~ 128 chars User ID to be expelled

Result

Type Description
item EzGuild Guild updated

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type Base Type Description
GuildMasterRequiredException BadRequestException At least one member with guild master privileges is required.

Implementation Example

try {
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var result = await domain.DeleteMemberFromGuildAsync(
        accessToken: null,
        targetUserId: "user-0002"
    );
} catch(Gs2.Gs2Guild.Exception.GuildMasterRequiredException e) {
    // At least one member with guild master privileges is required.
}
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var future = domain.DeleteMemberFromGuildFuture(
        accessToken: null,
        targetUserId: "user-0002"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Guild.Exception.GuildMasterRequiredException)
        {
            // At least one member with guild master privileges is required.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    const auto Future = Domain->DeleteMemberFromGuild(
        nullptr, // accessToken
        "user-0002" // targetUserId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Guild::Error::FGuildMasterRequiredError::Class))
        {
            // At least one member with guild master privileges is required.
        }
        return false;
    }
    const auto Result = Future->GetTask().Result();

getGuild

Get a guild’s details

Retrieves the detailed information of a specific guild, including its display name, custom attributes, metadata, member list, and join policy. The information returned depends on the requesting player’s relationship to the guild — guild members can see full details including the member list, while non-members see only public information. Use this to display a guild detail screen — for example, “Dragon Knights — 25/30 members — Join: Approval Required”.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildName string
UUID ~ 36 chars Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.

Result

Type Description
item EzGuild Guild

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FGuild> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listGuilds

Search for guilds to join

Searches for guilds that the player can join, with optional filters for display name, attributes, and join policy. You can filter by up to 5 custom attributes (e.g., play style, language, activity level) and by join policy (open / approval required). You can also choose whether to include guilds that are already full. Note: only guilds updated in the last 24 hours appear in search results. If a guild should stay visible, call UpdateGuild periodically even if nothing changed. Use this to build a “Find Guild” screen with search filters and a list of matching guilds.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
displayName string ~ 64 chars Display name to search for guild
attributes1 List<int> 0 ~ 10 items List of guild operation policies to search for guild
attributes2 List<int> 0 ~ 10 items List of guild operation policies to search for guild
attributes3 List<int> 0 ~ 10 items List of guild operation policies to search for guild
attributes4 List<int> 0 ~ 10 items List of guild operation policies to search for guild
attributes5 List<int> 0 ~ 10 items List of guild operation policies to search for guild
joinPolicies List<string> 0 ~ 10 items List of guild join policies to search for guild
includeFullMembersGuild bool false Whether to include full guilds in search results
orderBy “number_of_players” Sort order
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
pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data
limit int 30 1 ~ 1000 Number of data items to retrieve

Result

Type Description
items List<EzGuild> List of Guild
nextPageToken string Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.SearchGuildsAsync(
        guildModelName: "guild-model-0001"
    ).ToListAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.SearchGuilds(
        guildModelName: "guild-model-0001"
    );
    List<EzGuild> items = new List<EzGuild>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->SearchGuilds(
        "guild-model-0001" // guildModelName
    );
    TArray<Gs2::UE5::Guild::Model::FEzGuildPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

updateGuild

Update the guild’s settings

Updates the guild’s display name, custom attributes, metadata, join policy, and role definitions. This is called as the guild — you need to use Assume first to get a guild access token, then call this API. Only members with the appropriate role permissions can update the guild settings. Also, calling this periodically keeps the guild visible in search results (guilds not updated for 24 hours are hidden from search). Use this for a “Guild Settings” screen where officers or the guild master can change the guild’s name, description, or recruitment policy.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
displayName string
~ 64 chars Display Name
A human-readable name for the guild shown to players in the UI. Unlike the guild name (which is a system-generated UUID), the display name is set by the guild creator and can be updated. Used for guild search results, member lists, and other player-facing displays.
attribute1 int 0 ~ 2147483645 Attribute 1
A numeric attribute for the guild that can be used for filtering and sorting in guild search. Up to 5 attributes are available for developers to define custom guild properties such as level, region, play style, or activity requirements.
attribute2 int 0 ~ 2147483645 Attribute 2
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute3 int 0 ~ 2147483645 Attribute 3
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute4 int 0 ~ 2147483645 Attribute 4
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
attribute5 int 0 ~ 2147483645 Attribute 5
A numeric attribute for the guild that can be used for filtering and sorting in guild search. See attribute1 for details.
metadata string ~ 1024 chars Guild Metadata
Arbitrary data associated with the guild that does not affect GS2 behavior. Can be used to store game-specific information such as guild emblems, descriptions, recruitment messages, or other custom data.
joinPolicy
Join Policy
Controls how users can join this guild. “anybody” allows any user to join immediately without approval. “approval” requires the guild master or authorized members to approve join requests before the user becomes a member. This can be changed by the guild master at any time.
DefinitionDescription
“anybody”Anybody can join
“approval”Approval required
customRoles List<EzRoleModel> [] 0 ~ 10 items Custom Roles List
A list of guild-specific custom role definitions that override or extend the model-level roles. Each guild can define up to 10 custom roles with unique permission sets. These roles can be assigned to members in addition to the model-level roles.
guildMemberDefaultRole string ~ 128 chars Default Custom Role
The custom role automatically assigned to new members when they join this specific guild. If set, overrides the guild model’s guildMemberDefaultRole for this guild. Must reference a role defined in the customRoles list.

Result

Type Description
item EzGuild Guild updated

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var result = await domain.UpdateGuildAsync(
        accessToken: null,
        displayName: "My Guild",
        joinPolicy: "anybody",
        attribute1: 1,
        attribute2: null,
        attribute3: null,
        attribute4: null,
        attribute5: null,
        metadata: null,
        customRoles: null,
        guildMemberDefaultRole: null
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var future = domain.UpdateGuildFuture(
        accessToken: null,
        displayName: "My Guild",
        joinPolicy: "anybody",
        attribute1: 1,
        attribute2: null,
        attribute3: null,
        attribute4: null,
        attribute5: null,
        metadata: null,
        customRoles: null,
        guildMemberDefaultRole: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    const auto Future = Domain->UpdateGuild(
        nullptr, // accessToken
        "My Guild", // displayName
        "anybody", // joinPolicy
        1 // attribute1
        // attribute2
        // attribute3
        // attribute4
        // attribute5
        // metadata
        // customRoles
        // guildMemberDefaultRole
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

updateGuildMemberRole

Change a guild member’s role

Changes the role of a specific guild member — for example, promoting a member to “Officer” or demoting an officer back to “Member”. This is called as the guild (use Assume first). Only members with the appropriate role permissions can change other members’ roles. Use this for a “Manage Members” screen where the guild master or officers can promote or demote members.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
targetUserId string
~ 128 chars User ID to be updated
roleName string
~ 128 chars Role Model name
Role Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

Type Description
item EzGuild Guild updated

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var result = await domain.UpdateGuildMemberRoleAsync(
        accessToken: null,
        targetUserId: "user-0002",
        roleName: "role-0001"
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var future = domain.UpdateGuildMemberRoleFuture(
        accessToken: null,
        targetUserId: "user-0002",
        roleName: "role-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    const auto Future = Domain->UpdateGuildMemberRole(
        nullptr, // accessToken
        "user-0002", // targetUserId
        "role-0001" // roleName
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

acceptRequest

Accept a player’s join request

Approves a pending join request, adding the requesting player to the guild’s member list. This is called as the guild (use Assume first). Only members with the appropriate role permissions can accept join requests. After acceptance, the player becomes a guild member with the default role defined in the guild model. Use this for an “Accept” button on the join request detail or list screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
fromUserId string
~ 128 chars User ID

Result

Type Description
item EzReceiveMemberRequest Accepted join request
guild EzGuild Guild

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type Base Type Description
MaximumJoinedGuildsReachedException BadRequestException The number of guilds you can join at the same time has reached the upper limit.
MaximumMembersReachedException BadRequestException The number of members has reached the upper limit.

Implementation Example

try {
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    ).ReceiveMemberRequest(
        fromUserId: null
    );
    var result = await domain.AcceptRequestAsync(
        accessToken: null
    );
} catch(Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException e) {
    // The number of guilds you can join at the same time has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumMembersReachedException e) {
    // The number of members has reached the upper limit.
}
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    ).ReceiveMemberRequest(
        fromUserId: null
    );
    var future = domain.AcceptRequestFuture(
        accessToken: null
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException)
        {
            // The number of guilds you can join at the same time has reached the upper limit.
        }
        if (future.Error is Gs2.Gs2Guild.Exception.MaximumMembersReachedException)
        {
            // The number of members has reached the upper limit.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-0001", // guildModelName
        "guildName-0001", // guildName
        "user-0001" // userId
    )->ReceiveMemberRequest(
        nullptr // fromUserId
    );
    const auto Future = Domain->AcceptRequest(
        nullptr // accessToken
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Guild::Error::FMaximumJoinedGuildsReachedError::Class))
        {
            // The number of guilds you can join at the same time has reached the upper limit.
        }
        if (e->IsChildOf(Gs2::Guild::Error::FMaximumMembersReachedError::Class))
        {
            // The number of members has reached the upper limit.
        }
        return false;
    }
    const auto Result = Future->GetTask().Result();

getReceiveRequest

Get the details of a specific join request

Retrieves the details of a specific join request received by the guild, identified by the sender’s user ID. This is called as the guild (use Assume first). Use this to show a join request detail screen — for example, displaying the applicant’s profile, their message, and “Accept” / “Reject” buttons.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
fromUserId string
~ 128 chars User ID

Result

Type Description
item EzReceiveMemberRequest Join request

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    ).ReceiveMemberRequest(
        fromUserId: null
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    ).ReceiveMemberRequest(
        fromUserId: null
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-0001", // guildModelName
        "guildName-0001", // guildName
        "user-0001" // userId
    )->ReceiveMemberRequest(
        nullptr // fromUserId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    ).ReceiveMemberRequest(
        fromUserId: null
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    ).ReceiveMemberRequest(
        fromUserId: null
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-0001", // guildModelName
        "guildName-0001", // guildName
        "user-0001" // userId
    )->ReceiveMemberRequest(
        nullptr // fromUserId
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FReceiveMemberRequest> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listReceiveRequests

Get a list of join requests received by the guild

Retrieves all pending join requests that players have sent to this guild. This is called as the guild (use Assume first to get a guild access token). Each request includes who sent it and any message or metadata they attached. Use this to build a “Join Requests” screen in the guild management panel — for example, showing a list like “PlayerA wants to join (Message: Level 50 healer, daily active)”.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data
limit int 30 1 ~ 1000 Number of data items to retrieve

Result

Type Description
items List<EzReceiveMemberRequest> List of join request
nextPageToken string Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    );
    var items = await domain.ReceiveRequestsAsync(
    ).ToListAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-0001",
        guildName: "guildName-0001",
        userId: "user-0001"
    );
    var it = domain.ReceiveRequests(
    );
    List<EzReceiveMemberRequest> items = new List<EzReceiveMemberRequest>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-0001", // guildModelName
        "guildName-0001", // guildName
        "user-0001" // userId
    );
    const auto It = Domain->ReceiveRequests(
    );
    TArray<Gs2::UE5::Guild::Model::FEzReceiveMemberRequestPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

rejectRequest

Reject a player’s join request

Denies a pending join request. The requesting player will not be added to the guild. This is called as the guild (use Assume first). Only members with the appropriate role permissions can reject join requests. The rejected player can send a new join request later unless they have been added to the guild’s block list (IgnoreUser). Use this for a “Reject” button on the join request detail or list screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
fromUserId string
~ 128 chars User ID

Result

Type Description
item EzReceiveMemberRequest Rejected join request

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: null,
        guildName: "guild-0001",
        userId: null
    ).ReceiveMemberRequest(
        fromUserId: "user-0002"
    );
    var result = await domain.RejectRequestAsync(
        accessToken: null
    );
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: null,
        guildName: "guild-0001",
        userId: null
    ).ReceiveMemberRequest(
        fromUserId: "user-0002"
    );
    var future = domain.RejectRequestFuture(
        accessToken: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        nullptr, // guildModelName
        "guild-0001", // guildName
        nullptr // userId
    )->ReceiveMemberRequest(
        "user-0002" // fromUserId
    );
    const auto Future = Domain->RejectRequest(
        nullptr // accessToken
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

cancelRequest

Cancel a join request the player sent

Cancels (withdraws) a pending join request that the player previously sent to a guild. After cancellation, the request is removed from both the player’s sent requests and the guild’s received requests. The player can send a new join request to the same guild after cancelling. Use this for a “Cancel Application” or “Withdraw Request” button on the pending request detail screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
targetGuildName string
~ 128 chars Target Guild Name
The unique name (UUID) of the guild to which the join request was sent. This identifies the specific guild instance that the user is requesting to join, and is used to locate the guild’s inbox for request processing.

Result

Type Description
item EzSendMemberRequest Join request deleted

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.CancelRequestAsync(
        guildModelName: "guild-0002",
        targetGuildName: "guild-0002"
    );
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.CancelRequestFuture(
        guildModelName: "guild-0002",
        targetGuildName: "guild-0002"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->CancelRequest(
        "guild-0002", // guildModelName
        "guild-0002" // targetGuildName
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

getSendRequest

Get the details of a join request the player sent

Retrieves the details of a specific join request that the player has sent to a guild. The returned information includes the target guild and the metadata (message) attached to the request. Use this to show the details of a pending application — for example, displaying “Applied to Dragon Knights — Message: Level 50 healer” with a “Cancel” button.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
targetGuildName string
~ 128 chars Target Guild Name
The unique name (UUID) of the guild to which the join request was sent. This identifies the specific guild instance that the user is requesting to join, and is used to locate the guild’s inbox for request processing.

Result

Type Description
item EzSendMemberRequest Join Request

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SendMemberRequest(
        guildModelName: "guild-0002",
        guildName: null
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SendMemberRequest(
        guildModelName: "guild-0002",
        guildName: null
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->SendMemberRequest(
        "guild-0002", // guildModelName
        nullptr // guildName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SendMemberRequest(
        guildModelName: "guild-0002",
        guildName: null
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SendMemberRequest(
        guildModelName: "guild-0002",
        guildName: null
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->SendMemberRequest(
        "guild-0002", // guildModelName
        nullptr // guildName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FSendMemberRequest> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listSendRequests

Get a list of join requests the player has sent

Retrieves all join requests that the player has sent to various guilds and are still pending. Each entry includes which guild the request was sent to and any metadata (message) attached to the request. Use this to build a “My Applications” or “Pending Requests” screen — for example, showing “Applied to Dragon Knights (pending), Applied to Star Alliance (pending)”.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data
limit int 30 1 ~ 1000 Number of data items to retrieve

Result

Type Description
items List<EzSendMemberRequest> List of join requests
nextPageToken string Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.SendRequestsAsync(
        guildModelName: "guild-0002"
    ).ToListAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.SendRequests(
        guildModelName: "guild-0002"
    );
    List<EzSendMemberRequest> items = new List<EzSendMemberRequest>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->SendRequests(
        "guild-0002" // guildModelName
    );
    TArray<Gs2::UE5::Guild::Model::FEzSendMemberRequestPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

sendRequest

Send a join request to a guild

Sends a join request to the specified guild. If the guild’s join policy is “open”, the player joins immediately. If it’s “approval required”, the request goes to the guild’s inbox for review. You can attach metadata (such as a message like “Level 50 healer, looking for a raid group”) to the request. The request will be rejected automatically if the player is on the guild’s block list (IgnoreUser). Use this for a “Request to Join” or “Apply” button on the guild detail screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
targetGuildName string
~ 128 chars Destination Guild Name
metadata string ~ 512 chars Guild Member Metadata
Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers.

Result

Type Description
item EzGuild Joined guild
Responds when a join request is made to a guild that does not require approval
sendMemberRequest EzSendMemberRequest Sent Join Request
Responds when a join request is made to a guild that requires approval

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type Base Type Description
MaximumMembersReachedException BadRequestException The number of members has reached the upper limit.
MaximumJoinedGuildsReachedException BadRequestException The number of guilds you can join at the same time has reached the upper limit.
MaximumReceiveRequestsReachedException BadRequestException The number of requests to join the guild has reached the upper limit.
MaximumSendRequestsReachedException BadRequestException You have reached the maximum number of requests you can send.
DotMeetJoinRequirementsException BadRequestException You do not meet the requirements to join the guild.

Implementation Example

try {
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.SendRequestAsync(
        guildModelName: "guild-0002",
        targetGuildName: "guild-0002",
        metadata: null
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Guild.Exception.MaximumMembersReachedException e) {
    // The number of members has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException e) {
    // The number of guilds you can join at the same time has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumReceiveRequestsReachedException e) {
    // The number of requests to join the guild has reached the upper limit.
} catch(Gs2.Gs2Guild.Exception.MaximumSendRequestsReachedException e) {
    // You have reached the maximum number of requests you can send.
} catch(Gs2.Gs2Guild.Exception.DotMeetJoinRequirementsException e) {
    // You do not meet the requirements to join the guild.
}
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.SendRequestFuture(
        guildModelName: "guild-0002",
        targetGuildName: "guild-0002",
        metadata: null
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Guild.Exception.MaximumMembersReachedException)
        {
            // The number of members has reached the upper limit.
        }
        if (future.Error is Gs2.Gs2Guild.Exception.MaximumJoinedGuildsReachedException)
        {
            // The number of guilds you can join at the same time has reached the upper limit.
        }
        if (future.Error is Gs2.Gs2Guild.Exception.MaximumReceiveRequestsReachedException)
        {
            // The number of requests to join the guild has reached the upper limit.
        }
        if (future.Error is Gs2.Gs2Guild.Exception.MaximumSendRequestsReachedException)
        {
            // You have reached the maximum number of requests you can send.
        }
        if (future.Error is Gs2.Gs2Guild.Exception.DotMeetJoinRequirementsException)
        {
            // You do not meet the requirements to join the guild.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->SendRequest(
        "guild-0002", // guildModelName
        "guild-0002" // targetGuildName
        // metadata
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Guild::Error::FMaximumMembersReachedError::Class))
        {
            // The number of members has reached the upper limit.
        }
        if (e->IsChildOf(Gs2::Guild::Error::FMaximumJoinedGuildsReachedError::Class))
        {
            // The number of guilds you can join at the same time has reached the upper limit.
        }
        if (e->IsChildOf(Gs2::Guild::Error::FMaximumReceiveRequestsReachedError::Class))
        {
            // The number of requests to join the guild has reached the upper limit.
        }
        if (e->IsChildOf(Gs2::Guild::Error::FMaximumSendRequestsReachedError::Class))
        {
            // You have reached the maximum number of requests you can send.
        }
        if (e->IsChildOf(Gs2::Guild::Error::FDotMeetJoinRequirementsError::Class))
        {
            // You do not meet the requirements to join the guild.
        }
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

getJoinedGuild

Get details of a specific guild the player belongs to

Retrieves the membership details for a specific guild that the player has joined. The returned information includes the guild name, the player’s role, join date, and membership metadata. Use this to show the player’s membership info for a specific guild — for example, “Joined: 2024-01-15, Role: Officer, Note: Tank main”.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string
UUID ~ 36 chars Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.

Result

Type Description
item EzJoinedGuild Joining guild

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->JoinedGuild(
        "guild-model-0001", // guildModelName
        "guild-0001" // guildName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->JoinedGuild(
        "guild-model-0001", // guildModelName
        "guild-0001" // guildName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FJoinedGuild> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listJoinedGuilds

Get a list of guilds the player belongs to

Retrieves all guilds that the player is currently a member of. You can optionally filter by guild model name — if omitted, guilds of all types are returned. Each entry includes the guild name, when the player joined, and their current role. Use this to build a “My Guilds” screen showing the player’s guild memberships — for example, “Dragon Knights (Officer), Star Alliance (Member)”.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string ~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data
limit int 30 1 ~ 1000 Number of data items to retrieve

Result

Type Description
items List<EzJoinedGuild> Joining guild
nextPageToken string Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.JoinedGuildsAsync(
        guildModelName: "guild-model-0001"
    ).ToListAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.JoinedGuilds(
        guildModelName: "guild-model-0001"
    );
    List<EzJoinedGuild> items = new List<EzJoinedGuild>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->JoinedGuilds(
        "guild-model-0001" // guildModelName
    );
    TArray<Gs2::UE5::Guild::Model::FEzJoinedGuildPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeJoinedGuilds(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeJoinedGuilds(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeJoinedGuilds(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeJoinedGuilds(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeJoinedGuilds(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeJoinedGuilds(CallbackId);

updateMemberMetadata

Update your own member metadata in a guild

Updates the player’s own metadata within a guild. Metadata is free-form text that can store any member-specific information. For example, you can use it to store the player’s preferred role (“Healer”), a personal message (“Looking for raid partners”), or gameplay preferences. Only the player themselves can update their own metadata — other members cannot change it. Use this for a “Edit My Guild Profile” feature where members can set their in-guild status or notes.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string
UUID ~ 36 chars Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
gameSession GameSession
GameSession
metadata string ~ 512 chars Guild Member Metadata
Arbitrary data associated with this guild member that does not affect GS2 behavior. Can be used to store member-specific information such as contribution points, last login time, or notes visible to guild officers.

Result

Type Description
item EzGuild Guild updated

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    var result = await domain.UpdateMemberMetadataAsync(
        metadata: "metadata-0001"
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    var future = domain.UpdateMemberMetadataFuture(
        metadata: "metadata-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->JoinedGuild(
        "guild-model-0001", // guildModelName
        "guild-0001" // guildName
    );
    const auto Future = Domain->UpdateMemberMetadata(
        "metadata-0001" // metadata
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

withdrawGuild

Leave a guild voluntarily

The player leaves a guild they are currently a member of. After withdrawing, the player is removed from the guild’s member list. Any player can leave a guild on their own — no approval from the guild master is needed. Note: if the guild model has a rejoin cooldown configured, the player won’t be able to rejoin the same guild until the cooldown period has passed. Use this for a “Leave Guild” button on the guild detail or settings screen. Consider showing a confirmation dialog since there may be a cooldown before rejoining.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession GameSession
GameSession
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string
UUID ~ 36 chars Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.

Result

Type Description
item EzJoinedGuild Guild that withdrew
guild EzGuild Guild

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type Base Type Description
GuildMasterRequiredException BadRequestException At least one member with guild master privileges is required.

Implementation Example

try {
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    var result = await domain.WithdrawGuildAsync(
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Guild.Exception.GuildMasterRequiredException e) {
    // At least one member with guild master privileges is required.
}
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).JoinedGuild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001"
    );
    var future = domain.WithdrawGuildFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Guild.Exception.GuildMasterRequiredException)
        {
            // At least one member with guild master privileges is required.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->JoinedGuild(
        "guild-model-0001", // guildModelName
        "guild-0001" // guildName
    );
    const auto Future = Domain->WithdrawGuild(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Guild::Error::FGuildMasterRequiredError::Class))
        {
            // At least one member with guild master privileges is required.
        }
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

addIgnoreUser

Block a player from joining the guild

Adds a player to the guild’s block list. Once blocked, the player cannot send join requests to this guild — any future requests are automatically rejected. This is called as the guild (use Assume first). Only members with the appropriate role permissions can manage the block list. Use this for a “Block” button — for example, after kicking a troublesome member to prevent them from requesting to rejoin.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
userId string
~ 128 chars User ID

Result

Type Description
item EzIgnoreUser User ID that refuse to participate
guild EzGuild Guild

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var result = await domain.AddIgnoreUserAsync(
        accessToken: null,
        userId: "user-0001"
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    );
    var future = domain.AddIgnoreUserFuture(
        accessToken: null,
        userId: "user-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    );
    const auto Future = Domain->AddIgnoreUser(
        nullptr, // accessToken
        "user-0001" // userId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

deleteIgnoreUser

Unblock a player from the guild’s block list

Removes a player from the guild’s block list. After unblocking, the player can send join requests to this guild again. This is called as the guild (use Assume first). Only members with the appropriate role permissions can manage the block list. Use this for an “Unblock” button on the blocked players management screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
userId string
~ 128 chars User ID

Result

Type Description
item EzIgnoreUser User ID that refuse to participate

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    ).IgnoreUser(
    );
    var result = await domain.DeleteIgnoreUserAsync(
        accessToken: null,
        userId: "user-0001"
    );
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    ).IgnoreUser(
    );
    var future = domain.DeleteIgnoreUserFuture(
        accessToken: null,
        userId: "user-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    )->IgnoreUser(
    );
    const auto Future = Domain->DeleteIgnoreUser(
        nullptr, // accessToken
        "user-0001" // userId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

getIgnoreUser

Check if a specific player is on the guild’s block list

Checks whether a specific player is blocked from joining this guild. This is called as the guild (use Assume first). Use this to check a player’s block status before showing a “Block” or “Unblock” button — for example, on a member management or player profile screen.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
userId string
~ 128 chars User ID

Result

Type Description
item EzIgnoreUser User ID that refuse to participate

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    ).IgnoreUser(
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    ).IgnoreUser(
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    )->IgnoreUser(
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    ).IgnoreUser(
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: "user-0001"
    ).IgnoreUser(
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        "user-0001" // userId
    )->IgnoreUser(
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FIgnoreUser> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listIgnoreUsers

Get the guild’s block list

Retrieves the list of players that the guild has blocked from joining. This is called as the guild (use Assume first to get a guild access token). Blocked players cannot send join requests to this guild — their requests are automatically rejected. Use this to build a “Blocked Players” management screen in the guild settings — for example, showing a list of blocked players with “Unblock” buttons.

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name
pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data
limit int 30 1 ~ 1000 Number of data items to retrieve

Result

Type Description
items List<EzIgnoreUser> List of User IDs that refuse to participate
nextPageToken string Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    );
    var items = await domain.IgnoreUsersAsync(
    ).ToListAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    );
    var it = domain.IgnoreUsers(
    );
    List<EzIgnoreUser> items = new List<EzIgnoreUser>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        nullptr // userId
    );
    const auto It = Domain->IgnoreUsers(
    );
    TArray<Gs2::UE5::Guild::Model::FEzIgnoreUserPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    );
    
    // Start event handling
    var callbackId = domain.SubscribeIgnoreUsers(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeIgnoreUsers(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    );
    
    // Start event handling
    var callbackId = domain.SubscribeIgnoreUsers(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeIgnoreUsers(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        nullptr // userId
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeIgnoreUsers(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeIgnoreUsers(CallbackId);

getLastGuildMasterActivity

Check when the guild master was last active

Retrieves the date and time of the guild master’s most recent activity. This is called as the guild (use Assume first to get a guild access token). Use this to display the guild master’s activity status — for example, “Guild Master last active: 3 days ago”. This information is useful for determining whether the guild master has been inactive long enough to trigger automatic succession (PromoteSeniorMember).

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name

Result

Type Description
item EzLastGuildMasterActivity User ID that refuse to participate
guild EzGuild Guild

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    ).LastGuildMasterActivity(
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    ).LastGuildMasterActivity(
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        nullptr // userId
    )->LastGuildMasterActivity(
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    ).LastGuildMasterActivity(
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    ).LastGuildMasterActivity(
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        nullptr // userId
    )->LastGuildMasterActivity(
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Guild::Model::FLastGuildMasterActivity> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

promoteSeniorMember

Replace an inactive guild master with the most senior member

If the guild master has not been active for the period defined in the guild model’s inactivity settings, this promotes the longest-serving member to become the new guild master. This is called as the guild (use Assume first). The inactivity period threshold is configured in the guild model. This prevents guilds from becoming “stuck” when the guild master stops playing the game. Use this for a “Claim Leadership” button that appears when the guild master has been inactive — for example, showing “The guild master has been inactive for 30 days. As the most senior member, you can take over.”

Request

Type Condition Required Default Value Limits Description
namespaceName string
~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string
~ 128 chars Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
accessToken string
~ 128 chars Guild name

Result

Type Description
item EzLastGuildMasterActivity User ID that refuse to participate
guild EzGuild Guild

Implementation Example

    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    );
    var result = await domain.PromoteSeniorMemberAsync(
        accessToken: null
    );
    var item = await result.ModelAsync();
    var domain = gs2.Guild.Namespace(
        namespaceName: "namespace-0001"
    ).Guild(
        guildModelName: "guild-model-0001",
        guildName: "guild-0001",
        userId: null
    );
    var future = domain.PromoteSeniorMemberFuture(
        accessToken: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Guild->Namespace(
        "namespace-0001" // namespaceName
    )->Guild(
        "guild-model-0001", // guildModelName
        "guild-0001", // guildName
        nullptr // userId
    );
    const auto Future = Domain->PromoteSeniorMember(
        nullptr // accessToken
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

Event Handlers

OnReceiveRequestNotification

Push notification used when a join request is received

Name Type Description
namespaceName string Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
fromUserId string User ID

Implementation Example

    gs2.Guild.OnReceiveRequestNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var fromUserId = notification.FromUserId;
    };
    gs2.Guild.OnReceiveRequestNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var fromUserId = notification.FromUserId;
    };
    Gs2->Guild->OnReceiveRequestNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GuildModelName = Notification->GuildModelNameValue;
        const auto GuildName = Notification->GuildNameValue;
        const auto FromUserId = Notification->FromUserIdValue;
    });

OnRemoveRequestNotification

Push notification used when a join request is deleted

Name Type Description
namespaceName string Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
fromUserId string User ID

Implementation Example

    gs2.Guild.OnRemoveRequestNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var fromUserId = notification.FromUserId;
    };
    gs2.Guild.OnRemoveRequestNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var fromUserId = notification.FromUserId;
    };
    Gs2->Guild->OnRemoveRequestNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GuildModelName = Notification->GuildModelNameValue;
        const auto GuildName = Notification->GuildNameValue;
        const auto FromUserId = Notification->FromUserIdValue;
    });

OnChangeNotification

Push notification issued when a guild information is updated

Name Type Description
namespaceName string Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.

Implementation Example

    gs2.Guild.OnChangeNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
    };
    gs2.Guild.OnChangeNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
    };
    Gs2->Guild->OnChangeNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GuildModelName = Notification->GuildModelNameValue;
        const auto GuildName = Notification->GuildNameValue;
    });

OnJoinNotification

Push notification issued when a guild member is added

Name Type Description
namespaceName string Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
joinedUserId string User ID

Implementation Example

    gs2.Guild.OnJoinNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var joinedUserId = notification.JoinedUserId;
    };
    gs2.Guild.OnJoinNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var joinedUserId = notification.JoinedUserId;
    };
    Gs2->Guild->OnJoinNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GuildModelName = Notification->GuildModelNameValue;
        const auto GuildName = Notification->GuildNameValue;
        const auto JoinedUserId = Notification->JoinedUserIdValue;
    });

OnLeaveNotification

Push notification issued when a guild member is removed

Name Type Description
namespaceName string Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
leavedUserId string User ID

Implementation Example

    gs2.Guild.OnLeaveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var leavedUserId = notification.LeavedUserId;
    };
    gs2.Guild.OnLeaveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var leavedUserId = notification.LeavedUserId;
    };
    Gs2->Guild->OnLeaveNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GuildModelName = Notification->GuildModelNameValue;
        const auto GuildName = Notification->GuildNameValue;
        const auto LeavedUserId = Notification->LeavedUserIdValue;
    });

OnChangeMemberNotification

Push notification issued when a guild member is updated

Name Type Description
namespaceName string Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildModelName string Guild Model name
Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
guildName string Guild Name
Maintains a unique name for each guild.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each guild.
changedUserId string User ID

Implementation Example

    gs2.Guild.OnChangeMemberNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var changedUserId = notification.ChangedUserId;
    };
    gs2.Guild.OnChangeMemberNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var guildModelName = notification.GuildModelName;
        var guildName = notification.GuildName;
        var changedUserId = notification.ChangedUserId;
    };
    Gs2->Guild->OnChangeMemberNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GuildModelName = Notification->GuildModelNameValue;
        const auto GuildName = Notification->GuildNameValue;
        const auto ChangedUserId = Notification->ChangedUserIdValue;
    });