> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Guild Master Data Reference
Reference for the master data format and the models to be imported
## Master Data Format
**JSON**
```json
{
"version": "2024-04-25",
"guildModels": [
{
"name": "[string]Guild Model name",
"metadata": "[string?]Metadata",
"defaultMaximumMemberCount": "[int]Default Maximum Member Count",
"maximumMemberCount": "[int]Maximum Member Count",
"inactivityPeriodDays": "[int]Inactivity Period Days",
"roles": [
{
"name": "[string]Role Model name",
"metadata": "[string?]Metadata",
"policyDocument": "[string]Policy Document"
}
],
"guildMasterRole": "[string]Guild Master Role Name",
"guildMemberDefaultRole": "[string]Default Member Role Name",
"rejoinCoolTimeMinutes": "[int]Rejoin Cool Time (Minutes)",
"maxConcurrentJoinGuilds": "[int?]Maximum Concurrent Guild Memberships",
"maxConcurrentGuildMasterCount": "[int?]Maximum Concurrent Guild Master Count"
}
]
}
```
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2024-04-25 | | Master data format version |
| guildModels | [List<GuildModel>](#guildmodel) | | | | ~ 100 items | 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. |
## Models
### GuildModel
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 |
| --- | --- | --- | --- | --- | --- | --- |
| guildModelId | string | | * | | ~ 1024 chars | Guild Model GRN
* Set automatically by the server |
| name | string | | ✓ | | ~ 128 chars | Guild Model name
Unique Guild Model 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. |
| inactivityPeriodDays | int | | | 7 | 1 ~ 365 | Inactivity Period Days
The number of days of guild master inactivity after which a new guild master is automatically selected from the remaining guild members. This prevents guilds from becoming unmanageable when the guild master stops playing. |
| roles | [List<RoleModel>](#rolemodel) | | ✓ | | 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. |
| guildMasterRole | string | | ✓ | | ~ 128 chars | Guild Master Role Name
The name of the role assigned to guild masters. Must reference a role defined in the roles list. Guild masters typically have full permissions to manage the guild, including approving join requests, expelling members, changing roles, and updating guild settings. |
| guildMemberDefaultRole | string | | ✓ | | ~ 128 chars | Default Member Role Name
The name of the role automatically assigned to new guild members when they join. Must reference a role defined in the roles list. This is the baseline permission set for regular members before any role changes by the guild master. |
| 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. |
| maxConcurrentJoinGuilds | int | | | | 1 ~ 10 | Maximum Concurrent Guild Memberships
The maximum number of guilds of this type that a user can be a member of simultaneously. Allows for designs where players can belong to multiple guilds at the same time (e.g., a combat guild and a social guild). The value ranges from 1 to 10. |
| maxConcurrentGuildMasterCount | int | | | | 1 ~ 100 | Maximum Concurrent Guild Master Count
The maximum number of guild masters that can exist in a single guild at the same time. Allows for co-leadership designs where multiple players share guild master responsibilities and permissions. The value ranges from 1 to 100. |
---
### RoleModel
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
Unique Role Model 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. |
---