GS2-Guild Master Data Reference

Reference for the master data format and the models to be imported

Master Data Format

{
  "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		Format version of master data
guildModels	List<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	Required	Default	Value Limits	Description
guildModelId	string	*		~ 1024 chars	Guild Model GRN * Set automatically by the server
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.
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>	✓		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	Required	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.